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``.


Social User
-----------

This model associates a social account data with a user in the system, it
contains the provider name and user ID (``uid``) which should identify the
social account in the remote provider, plus some extra data (``extra_data``)
which is JSON encoded field with extra information from the provider (usually
avatars and similar).

When implementing this model, it must inherits from UserMixin_ and extend the
needed methods:

* Username::

    @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::

    @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::

    @classmethod
    def get_social_auth(cls, provider, uid):
        """Return UserSocialAuth for given provider and uid"""
        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):
        """Create a UserSocialAuth instance for given user"""
        raise NotImplementedError('Implement in subclass')

* Social disconnection::

    @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')


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_, and override
the needed methods::

    @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')


Association
-----------

Another OpenID helper class, it stores basic data to keep the OpenID
association. Like Nonce_ this is for internal use only.

When implementing this model, it must inherits from AssociationMixin_, and
override the needed methods::

    @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')


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`_.

When implementing the model for your framework only one method needs to be
overridden::

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


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_, add the needed
models references and implement the needed method::

    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')


SQLAlchemy and Django mixins
----------------------------

Currently there are partial implementations of mixins for `SQLAlchemy ORM`_ and
`Django ORM`_ with common code used later on current implemented applications.

.. note::

    When using `SQLAlchemy ORM`_ and ``ZopeTransactionExtension``, it's
    recommended to use the transaction_ application to handle them.

Models Examples
---------------

Check for current implementations for `Django App`_, `Flask App`_, `Pyramid
App`_, and `Webpy App`_ for examples of implementations.


.. _UserMixin: https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L21
.. _NonceMixin: https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L166
.. _AssociationMixin: https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L178
.. _BaseStorage: https://github.com/python-social-auth/social-core/blob/master/social_core/storage.py#L248
.. _SQLAlchemy ORM: https://github.com/python-social-auth/social-storage-sqlalchemy/blob/master/social_sqlalchemy/storage.py
.. _Django ORM: https://github.com/python-social-auth/social-app-django/blob/master/social_django/storage.py
.. _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-django/blob/master/social_flask/models.py
.. _Pyramid App: https://github.com/python-social-auth/social-app-pyramid/blob/master/social_pyramid/models.py
.. _Webpy App: https://github.com/python-social-auth/social-app-webpy/blob/master/social_webpy/models.py
.. _pipeline docs: pipeline.html#email-validation
.. _transaction: https://pypi.python.org/pypi/transaction