Developer Interface — Flask Dance 1.1.0 documentation

# Developer Interface

## Consumers

An OAuth consumer is a website that allows users to log in with other websites (known as OAuth providers). Once a user has gone through the OAuth dance, the consumer website is allowed to interact with the provider website on behalf of the user.

class `flask_dance.consumer.` `OAuth1ConsumerBlueprint`(...)

  A subclass of `flask.Blueprint` that sets up OAuth 1 authentication.

  `__init__`(name, import_name, client_key=None, client_secret=None, signature_method='HMAC-SHA1', signature_type='AUTH_HEADER', rsa_key=None, client_class=None, force_include_body=False, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, request_token_url=None, authorization_url=None, access_token_url=None, redirect_url=None, redirect_to=None, session_class=None, backend=None, **kwargs)

    Most of the constructor arguments are forwarded either to the `flask.Blueprint` constructor or the `requests_oauthlib.OAuth1Session` construtor, including `**kwargs` (which is forwarded to `OAuth1Session`). Only the arguments that are relevant to Flask-Dance are documented here.

    Parameters: | base_url – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL. request_token_url – The URL specified by the OAuth provider for obtaining a request token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. authorization_url – The URL specified by the OAuth provider for the user to grant token authorization. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. access_token_url – The URL specified by the OAuth provider for obtaining an access token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. login_url – The URL route for the `login` view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}`, so that the URL is based on the name of the blueprint. authorized_url – The URL route for the `authorized` view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}/authorized`, so that the URL is based on the name of the blueprint. redirect_url – When the OAuth dance is complete, redirect the user to this URL. redirect_to – When the OAuth dance is complete, redirect the user to the URL obtained by calling `url_for()` with this argument. If you do not specify either `redirect_url` or `redirect_to`, the user will be redirected to the root path (`/`). session_class – The class to use for creating a Requests session between the consumer (your website) and the provider (e.g. Twitter). Defaults to `OAuth1Session`. backend – A storage backend class, or an instance of a storage backend class, to use for this blueprint. Defaults to `SessionBackend`.

  `session`

    An `OAuth1Session` instance that automatically loads tokens for the OAuth provider from the backend. This instance is automatically created the first time it is referenced for each request to your Flask application.

  `backend`

    The token storage backend that this blueprint uses.

  `token`

    The OAuth token currently loaded in the `session` attribute.

  `config`

    A special dictionary that holds information about the current state of the application, which the backend can use to look up the correct OAuth token from storage. For example, in a multi-user system, where each user has their own OAuth token, information about which user is currently logged in for this request is stored in this dictionary. This dictionary is special because it automatically alerts the backend when any attribute in the dictionary is changed, so that the backend’s caches are appropriately invalidated.

  `from_config`

    A dictionary used to dynamically load variables from the Flask application config into the blueprint at the start of each request. To tell this blueprint to pull configuration from the app, set key-value pairs on this dict. Keys are the name of the local variable to set on the blueprint object, and values are the variable name in the Flask application config. Variable names can be a dotpath. For example:

        blueprint.from_config["session.client_id"] = "GITHUB_OAUTH_CLIENT_ID"

    Which will cause this line to execute at the start of every request:

        blueprint.session.client_id = app.config["GITHUB_OAUTH_CLIENT_ID"]

class `flask_dance.consumer.` `OAuth2ConsumerBlueprint`(...)

  A subclass of `flask.Blueprint` that sets up OAuth 2 authentication.

  `__init__`(name, import_name, client_id=None, client_secret=None, client=None, auto_refresh_url=None, auto_refresh_kwargs=None, scope=None, state=None, static_folder=None, static_url_path=None, template_folder=None, url_prefix=None, subdomain=None, url_defaults=None, root_path=None, login_url=None, authorized_url=None, base_url=None, authorization_url=None, authorization_url_params=None, token_url=None, token_url_params=None, redirect_url=None, redirect_to=None, session_class=None, backend=None, **kwargs)

    Most of the constructor arguments are forwarded either to the `flask.Blueprint` constructor or the `requests_oauthlib.OAuth2Session` construtor, including `**kwargs` (which is forwarded to `OAuth2Session`). Only the arguments that are relevant to Flask-Dance are documented here.

    Parameters: | base_url – The base URL of the OAuth provider. If specified, all URLs passed to this instance will be resolved relative to this URL. authorization_url – The URL specified by the OAuth provider for obtaining an authorization grant. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. authorization_url_params (dict) – A dict of extra key-value pairs to include in the query string of the `authorization_url`, beyond those necessary for a standard OAuth 2 authorization grant request. token_url – The URL specified by the OAuth provider for obtaining an access token. This can be an fully-qualified URL, or a path that is resolved relative to the `base_url`. token_url_params (dict) – A dict of extra key-value pairs to include in the query string of the `token_url`, beyond those necessary for a standard OAuth 2 access token request. login_url – The URL route for the `login` view that kicks off the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}`, so that the URL is based on the name of the blueprint. authorized_url – The URL route for the `authorized` view that completes the OAuth dance. This string will be formatted with the instance so that attributes can be interpolated. Defaults to `/{bp.name}/authorized`, so that the URL is based on the name of the blueprint. redirect_url – When the OAuth dance is complete, redirect the user to this URL. redirect_to – When the OAuth dance is complete, redirect the user to the URL obtained by calling `url_for()` with this argument. If you do not specify either `redirect_url` or `redirect_to`, the user will be redirected to the root path (`/`). session_class – The class to use for creating a Requests session between the consumer (your website) and the provider (e.g. Twitter). Defaults to `OAuth2Session`. backend – A storage backend class, or an instance of a storage backend class, to use for this blueprint. Defaults to `SessionBackend`.

  `session`

    An `OAuth2Session` instance that automatically loads tokens for the OAuth provider from the backend. This instance is automatically created the first time it is referenced for each request to your Flask application.

  `backend`

    The token storage backend that this blueprint uses.

  `token`

    The OAuth token currently loaded in the `session` attribute.

  `config`

    A special dictionary that holds information about the current state of the application, which the backend can use to look up the correct OAuth token from storage. For example, in a multi-user system, where each user has their own OAuth token, information about which user is currently logged in for this request is stored in this dictionary. This dictionary is special because it automatically alerts the backend when any attribute in the dictionary is changed, so that the backend’s caches are appropriately invalidated.

  `from_config`

    A dictionary used to dynamically load variables from the Flask application config into the blueprint at the start of each request. To tell this blueprint to pull configuration from the app, set key-value pairs on this dict. Keys are the name of the local variable to set on the blueprint object, and values are the variable name in the Flask application config. Variable names can be a dotpath. For example:

        blueprint.from_config["session.client_id"] = "GITHUB_OAUTH_CLIENT_ID"

    Which will cause this line to execute at the start of every request:

        blueprint.session.client_id = app.config["GITHUB_OAUTH_CLIENT_ID"]

## Backends

class `flask_dance.consumer.backend.session.` `SessionBackend`(...)

  The default storage backend. Stores and retrieves OAuth tokens using the Flask session.

  `__init__`(key='{bp.name}_oauth_token')

    Parameters: | key (str) – The name to use as a key for storing the OAuth token in the Flask session. This string will have `.format(bp=self.blueprint)` called on it before it is used. so you can refer to information on the blueprint as part of the key. For example, `{bp.name}` will be replaced with the name of the blueprint.

class `flask_dance.consumer.backend.sqla.` `SQLAlchemyBackend`(...)

  Stores and retrieves OAuth tokens using a relational database through the SQLAlchemy ORM.

  `__init__`(model, session, user=None, user_id=None, user_required=None, anon_user=None, cache=None)

    Parameters: | model – The SQLAlchemy model class that represents the OAuth token table in the database. At a minimum, it must have a `provider` column and a `token` column. If tokens are to be associated with individual users in the application, it must also have a `user` relationship to your User model. It is recommended, though not required, that your model class inherit from `OAuthConsumerMixin`. session – The `SQLAlchemy session` for the database. If you’re using Flask-SQLAlchemy, this is `db.session`. user – If you want OAuth tokens to be associated with individual users in your application, this is a reference to the user that you want to use for the current request. It can be an actual User object, a function that returns a User object, or a proxy to the User object. If you’re using Flask-Login, this is `current_user`. user_id – If you want to pass an identifier for a user instead of an actual User object, use this argument instead. Sometimes it can save a database query or two. If both `user` and `user_id` are provided, `user_id` will take precendence. user_required – If set to `True`, an exception will be raised if you try to set or retrieve an OAuth token without an associated user. If set to `False`, OAuth tokens can be set with or without an associated user. The default is auto-detection: it will be `True` if you pass a `user` or `user_id` parameter, `False` otherwise. anon_user – If anonymous users are represented by a class in your application, provide that class here. If you are using Flask-Login, anonymous users are represented by the `flask_login.AnonymousUserMixin` class, but you don’t have to provide that – Flask-Dance treats it as the default. cache – An instance of Flask-Caching. Providing a caching system is highly recommended, but not required.

  `get`(blueprint, user=None, user_id=None)

    When you have a statement in your code that says “if <provider>.authorized:” (for example “if twitter.authorized:”), a long string of function calls result in this function being used to check the Flask server’s cache and database for any records associated with the current_user. The user and user_id parameters are actually not set in that case (see base.py:token(), that’s what calls this function), so the user information is instead loaded from the current_user (if that’s what you specified when you created the blueprint) with blueprint.config.get(‘user_id’).

    Parameters: | blueprint – user – user_id –
    Returns: |

Fork me on GitHub