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

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

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:

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