<a id="storage"></a>

# Storage

Different frameworks support different ORMs, Storage solves the different
interfaces moving the common API to mixins classes. These mixins are used on
apps when defining the different models used by `python-social-auth`.

<a id="social-user"></a>

## Social User

This model associates a social account data with a user in the system, it
contains the provider name, the user ID (`uid`) which identifies the social
account in the remote provider, and `id_key` naming the provider field from
which that ID was obtained. It also contains JSON-encoded `extra_data` with
additional provider information. Existing rows created before `id_key` was
introduced use an empty string until social-core migrates them.

When implementing this model, it must inherits from [UserMixin](https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L21) and extend the
needed methods:

* Username:
  ```default
  @classmethod
  def get_username(cls, user):
      """Return the username for given user"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def username_max_length(cls):
      """Return the max length for username"""
      raise NotImplementedError('Implement in subclass')
  ```
* User model:
  ```default
  @classmethod
  def user_model(cls):
      """Return the user model"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def changed(cls, user):
      """The given user instance is ready to be saved"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def user_exists(cls, username):
      """
      Return True/False if a User instance exists with the given arguments.
      Arguments are directly passed to filter() manager method.
      """
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def create_user(cls, username, email=None):
      """Create a user with given username and (optional) email"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def get_user(cls, pk):
      """Return user instance for given id"""
      raise NotImplementedError('Implement in subclass')
  ```
* Social user:
  ```default
  @classmethod
  def get_social_auth(cls, provider, uid, id_key=None):
      """Return UserSocialAuth for the provider, uid, and optional key"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def get_social_auth_by_extra_data(cls, provider, key, value, id_key=''):
      """Return one unambiguous association matching stable provider data"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def get_social_auth_for_user(cls, user):
      """Return all the UserSocialAuth instances for given user"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def create_social_auth(cls, user, uid, provider, id_key=''):
      """Create a UserSocialAuth instance for given user"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def migrate_social_auth(cls, social, uid, id_key):
      """Atomically replace the association identifier and its key"""
      raise NotImplementedError('Implement in subclass')
  ```

Identifier migration must preserve the storage’s provider/UID uniqueness
guarantee, lock the association while updating it, and fail rather than select
an arbitrary row when stored provider data matches multiple associations.

* Social disconnection:
  ```default
  @classmethod
  def allowed_to_disconnect(cls, user, backend_name, association_id=None):
      """Return if it's safe to disconnect the social account for the
      given user"""
      raise NotImplementedError('Implement in subclass')

  @classmethod
  def disconnect(cls, name, user, association_id=None):
      """Disconnect the social account for the given user"""
      raise NotImplementedError('Implement in subclass')
  ```

<a id="nonce"></a>

## Nonce

This is a helper class for OpenID mechanism, it stores a one-use number,
shouldn’t be used by the project since it’s for internal use only.

When implementing this model, it must inherit from [NonceMixin](https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L166), and override
the needed methods:

```default
@classmethod
def use(cls, server_url, timestamp, salt):
    """Create a Nonce instance"""
    raise NotImplementedError('Implement in subclass')

@classmethod
def get(cls, server_url, salt):
    """Retrieve a Nonce instance"""
    raise NotImplementedError('Implement in subclass')

@classmethod
def delete(cls, nonce):
    """Delete a Nonce instance"""
    raise NotImplementedError('Implement in subclass')
```

<a id="association"></a>

## Association

This internal model stores OpenID protocol associations and temporary OpenID
Connect login nonces. It is separate from the model linking a user to a provider.
For OIDC, `handle` stores the nonce, `secret` is empty, and `assoc_type`
stores OAuth state. `issued` is the integer Unix creation timestamp and
`lifetime` is the duration in seconds.

`AssociationMixin.is_expired(now=None)` returns whether the lifetime has
elapsed, including the exact expiry boundary. Nonpositive lifetimes are expired.
OIDC validation removes matching expired records and rejects the login.

Storage integrations must preserve `issued` and `lifetime`. During upgrade,
existing OIDC nonce records with an empty secret and both values zero can receive
the upgrade timestamp and a 1,800-second grace period. Other unbounded records
are rejected. Stop old login-serving processes before this conversion so they
do not create additional undated nonces afterward.

Django provides `Association.cleanup_expired(now=None)`, which deletes expired
OpenID associations and OIDC nonces and returns the deleted record count.
`now` is an optional integer Unix timestamp; it defaults to the current time.
Other integrations should implement scheduled cleanup using the same expiry
rule. OpenID’s existing on-demand cleanup only visits associations for the
provider being queried.

When implementing this model, it must inherits from [AssociationMixin](https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L178), and
override the needed methods:

```default
@classmethod
def store(cls, server_url, association):
    """Create an Association instance"""
    raise NotImplementedError('Implement in subclass')

@classmethod
def get(cls, *args, **kwargs):
    """Get an Association instance"""
    raise NotImplementedError('Implement in subclass')

@classmethod
def remove(cls, ids_to_delete):
    """Remove an Association instance"""
    raise NotImplementedError('Implement in subclass')
```

<a id="validation-code"></a>

## Validation code

This class is used to keep track of email validations codes following the usual
email validation mechanism of sending an email to the user with a unique code.
This model is used by the partial pipeline `social_core.pipeline.mail.mail_validation`.
Check the docs at *Email validation* in [pipeline docs](pipeline.html#email-validation).

The model must inherit from `CodeMixin` and persist the `email`, `code`,
`verified`, and `timestamp` attributes. `make_code()` initializes
`timestamp` with the creation time in UTC. A framework-managed creation
timestamp can also be used. Naive timestamps are interpreted as UTC by the
default `is_expired(seconds)` implementation; override this method if your
storage uses another timezone. The Django integration interprets naive
timestamps in Django’s configured timezone.

Codes without a timestamp are rejected when expiry is enabled. Existing storage
integrations must add timestamp persistence and migrate existing data, or have
users request new codes. Do not assign a new creation time to old codes.

The storage lookup method must also be overridden:

```default
@classmethod
def get_code(cls, code):
    """Return the Code instance with the given code value"""
    raise NotImplementedError('Implement in subclass')
```

<a id="storage-interface"></a>

## Storage interface

There’s a helper class used by strategies to hide the real models names under
a common API, an instance of this class is used by strategies to access the
storage modules.

When implementing this class it must inherits from [BaseStorage](https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L248), add the needed
models references and implement the needed method:

```default
class StorageImplementation(BaseStorage):
    user = UserModel
    nonce = NonceModel
    association = AssociationModel
    code = CodeModel

    @classmethod
    def is_integrity_error(cls, exception):
        """Check if given exception flags an integrity error in the DB"""
        raise NotImplementedError('Implement in subclass')
```

<a id="sqlalchemy-and-django-mixins"></a>

## SQLAlchemy and Django mixins

Currently there are partial implementations of mixins for [SQLAlchemy ORM](https://github.com/python-social-auth/social-storage-sqlalchemy/blob/master/social_sqlalchemy/storage.py) and
[Django ORM](https://github.com/python-social-auth/social-app-django/blob/master/social_django/storage.py) with common code used later on current implemented applications.

#### NOTE
When using [SQLAlchemy ORM](https://github.com/python-social-auth/social-storage-sqlalchemy/blob/master/social_sqlalchemy/storage.py) and `ZopeTransactionExtension`, it’s
recommended to use the [transaction](https://pypi.python.org/pypi/transaction) application to handle them.

<a id="models-examples"></a>

## Models Examples

Check for current implementations for [Django App](https://github.com/python-social-auth/social-app-django/blob/master/social_django/models.py), [Flask App](https://github.com/python-social-auth/social-app-flask/blob/master/social_flask/models.py), [Pyramid
App](https://github.com/python-social-auth/social-app-pyramid/blob/master/social_pyramid/models.py), and [Webpy App](https://github.com/python-social-auth/social-app-webpy/blob/master/social_webpy/models.py) for examples of implementations.