django_evolution.signature

Classes for working with stored evolution state signatures.

These provide a way to work with the state of Django apps and their models in an abstract way, and to deserialize from or serialize to a string. Signatures can also be diffed, showing the changes between an older and a newer version in order to help see how the current database’s signature differs from an older stored version.

Serialized versions of signatures are versioned, and the signature classes handle loading and saving as any version. However, state may be lost when downgrading a signature.

The following versions are currently supported:

Version 1:

The original version of the signature, used up until Django Evolution 1.0. This is in the form of:

{
    '__version__': 1,
    '<legacy_app_label>': {
        '<model_name>': {
            'meta': {
                'db_table': '<table name>',
                'db_tablespace': '<tablespace>',
                'index_together': [
                    ('<colname>', ...),
                    ...
                ],
                'indexes': [
                    {
                        'name': '<name>',
                        'fields': ['<colname>', ...],
                    },
                    ...
                ],
                'pk_column': '<colname>',
                'unique_together': [
                    ('<colname>', ...),
                    ...
                ],
                '__unique_together_applied': True|False,
            },
            'fields': {
                'field_type': <class>,
                'related_model': '<app_label>.<class_name>',
                '<field_attr>': <value>,
                ...
            },
        },
        ...
    },
    ...
}
Version 2:

Introduced in Django Evolution 2.0. This differs from version 1 in that it’s deeper, with explicit namespaces for apps, models, and field attributes that can exist alongside metadata keys. This is in the form of:

{
    '__version__': 2,
    'apps': {
        '<app_label>': {
            'legacy_app_label': '<legacy app_label>',
            'upgrade_method': 'migrations'|'evolutions'|None,
            'applied_migrations' ['<migration name>', ...],
            'models': {
                '<model_name>': {
                    'meta': {
                        'constraints': [
                            {
                                'name': '<name>',
                                'type': '<class_path>',
                                'attrs': {
                                    '<attr_name>': <value>,
                                },
                            },
                            ...
                        ],
                        'db_table': '<table name>',
                        'db_tablespace': '<tablespace>',
                        'index_together': [
                            ('<colname>', ...),
                            ...
                        ],
                        'indexes': [
                            {
                                'name': '<name>',
                                'fields': ['<colname>', ...],
                            },
                            ...
                        ],
                        'pk_column': '<colname>',
                        'unique_together': [
                            ('<colname>', ...),
                            ...
                        ],
                        '__unique_together_applied': True|False,
                    },
                    'fields': {
                        'type': '<class_path>',
                        'related_model': '<app_label>.<class_name>',
                        'attrs': {
                            '<field_attr_name>': <value>,
                            ...
                        },
                    },
                },
                ...
            },
        },
        ...
    },
}

Module Attributes

LATEST_SIGNATURE_VERSION

The latest signature version.

Functions

validate_sig_version(sig_version)

Validate that a signature version is supported.

Classes

AppSignature(app_id[, legacy_app_label, …])

Signature information for an application.

BaseSignature()

Base class for a signature.

ConstraintSignature(name, constraint_type[, …])

Signature information for a explicit constraint.

FieldSignature(field_name, field_type[, …])

Signature information for a field.

IndexSignature(fields[, name])

Signature information for an explicit index.

ModelSignature(model_name, table_name[, …])

Signature information for a model.

ProjectSignature()

Signature information for a project.

django_evolution.signature.LATEST_SIGNATURE_VERSION = 2

The latest signature version.

class django_evolution.signature.BaseSignature

Bases: object

Base class for a signature.

classmethod deserialize(sig_dict, sig_version, database='default')

Deserialize the signature.

Parameters
  • sig_dict (dict) – The dictionary containing signature data.

  • sig_version (int) – The stored signature version.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature class.

Return type

BaseSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

diff(old_sig)

Diff against an older signature.

The resulting data is dependent on the type of signature.

Parameters

old_sig (BaseSignature) – The old signature to diff against.

Returns

The resulting diffed data.

Return type

object

clone()

Clone the signature.

Returns

The cloned signature.

Return type

BaseSignature

serialize(sig_version=2)

Serialize data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two signatures are equal.

Parameters

other (BaseSignature) – The other signature.

Returns

True if the project signatures are equal. False if they are not.

Return type

bool

__ne__(other)

Return whether two signatures are not equal.

Parameters

other (BaseSignature) – The other signature.

Returns

True if the project signatures are not equal. False if they are equal.

Return type

bool

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

__hash__ = None
class django_evolution.signature.ProjectSignature

Bases: django_evolution.signature.BaseSignature

Signature information for a project.

Projects are the top-level signature deserialized from and serialized to a Version model. They contain a signature version and information on all the applications tracked for the project.

classmethod from_database(database)

Create a project signature from the database.

This will look up all the applications registered in Django, turning each of them into a AppSignature stored in this project signature.

Parameters

database (unicode) – The name of the database.

Returns

The project signature based on the current application and database state.

Return type

ProjectSignature

classmethod deserialize(project_sig_dict, database='default')

Deserialize a serialized project signature.

Parameters
  • project_sig_dict (dict) – The dictionary containing project signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

ProjectSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version found in the dictionary is unsupported.

__init__()

Initialize the signature.

property app_sigs

The application signatures in the project signature.

add_app(app, database)

Add an application to the project signature.

This will construct an AppSignature and add it to the project signature.

Parameters
  • app (module) – The application module to create the signature from.

  • database (unicode) – The database name.

add_app_sig(app_sig)

Add an application signature to the project signature.

Parameters

app_sig (AppSignature) – The application signature to add.

remove_app_sig(app_id)

Remove an application signature from the project signature.

Parameters

app_id (unicode) – The ID of the application signature to remove.

Raises

django_evolution.errors.MissingSignatureError – The application ID does not represent a known application signature.

get_app_sig(app_id, required=False)

Return an application signature with the given ID.

Parameters
  • app_id (unicode) – The ID of the application signature. This may be a modern app label, or a legacy app label.

  • required (bool, optional) – Whether the app signature must be present. If True and the signature is missing, this will raise an exception.

Returns

The application signature, if found. If no application signature matches the ID, None will be returned.

Return type

AppSignature

Raises

django_evolution.errors.MissingSignatureError – The application signature was not found, and required was True.

diff(old_project_sig)

Diff against an older project signature.

This will return a dictionary of changes between two project signatures.

Parameters

old_project_sig (ProjectSignature) – The old project signature to diff against.

Returns

A dictionary in the following form:

{
    'changed': {
        <app ID>: <AppSignature diff>,
        ...
    },
    'deleted': [
        <app ID>: [
            <model name>,
            ...
        ],
        ...
    ],
}

Any key lacking a value will be ommitted from the diff.

Return type

collections.OrderedDict

Raises

TypeError – The old signature provided was not a ProjectSignature.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

ProjectSignature

serialize(sig_version=2)

Serialize project data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two project signatures are equal.

Parameters

other (ProjectSignature) – The other project signature.

Returns

True if the project signatures are equal. False if they are not.

Return type

bool

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

__hash__ = None
class django_evolution.signature.AppSignature(app_id, legacy_app_label=None, upgrade_method=None, applied_migrations=None)

Bases: django_evolution.signature.BaseSignature

Signature information for an application.

Application signatures store information on a Django application and all models registered under that application.

classmethod from_app(app, database)

Create an application signature from an application.

This will store data on the application and create a ModelSignature for each of the application’s models.

Parameters
  • app (module) – The application module to create the signature from.

  • database (unicode) – The name of the database.

Returns

The application signature based on the application.

Return type

AppSignature

classmethod deserialize(app_id, app_sig_dict, sig_version, database='default')

Deserialize a serialized application signature.

Parameters
  • app_id (unicode) – The application ID.

  • app_sig_dict (dict) – The dictionary containing application signature data.

  • sig_version (int) – The version of the serialized signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

AppSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__init__(app_id, legacy_app_label=None, upgrade_method=None, applied_migrations=None)

Initialize the signature.

Parameters
  • app_id (unicode) – The ID of the application. This will be the application label. On modern versions of Django, this may differ from the legacy app label.

  • legacy_app_label (unicode, optional) – The legacy label for the application. This is based on the module name.

  • upgrade_method (unicode, optional) – The upgrade method used for this application. This must be a value from UpgradeMethod, or None.

  • applied_migrations (set of unicode, optional) – The migration names that are applied as of this signature.

property model_sigs

The model signatures stored on the application signature.

property applied_migrations

The set of migration names applied to the app.

Type:

set of unicode

is_empty()

Return whether the application signature is empty.

An empty application signature contains no models.

Returns

True if the signature is empty. False if it still has models in it.

Return type

bool

add_model(model)

Add a model to the application signature.

This will construct a ModelSignature and add it to this application signature.

Parameters

model (django.db.models.Model) – The model to create the signature from.

add_model_sig(model_sig)

Add a model signature to the application signature.

Parameters

model_sig (ModelSignature) – The model signature to add.

remove_model_sig(model_name)

Remove a model signature from the application signature.

Parameters

model_name (unicode) – The name of the model.

Raises

django_evolution.errors.MissingSignatureError – The model name does not represent a known model signature.

clear_model_sigs()

Clear all model signatures from the application signature.

get_model_sig(model_name, required=False)

Return a model signature for the given model name.

Parameters
  • model_name (unicode) – The name of the model.

  • required (bool, optional) – Whether the model signature must be present. If True and the signature is missing, this will raise an exception.

Returns

The model signature, if found. If no model signature matches the model name, None will be returned.

Return type

ModelSignature

Raises

django_evolution.errors.MissingSignatureError – The model signature was not found, and required was True.

diff(old_app_sig)

Diff against an older application signature.

This will return a dictionary containing the differences between two application signatures.

Parameters

old_app_sig (AppSignature) – The old app signature to diff against.

Returns

A dictionary in the following form:

{
    'changed': {
        '<model_name>': <ModelSignature diff>,
        ...
    },
    'deleted': [ <list of deleted model names> ],
    'meta_changed': {
        '<prop_name>': {
            'old': <old value>,
            'new': <new value>,
        },
        ...
    }
}

Any key lacking a value will be ommitted from the diff.

Return type

collections.OrderedDict

Raises

TypeError – The old signature provided was not an AppSignature.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

AppSignature

serialize(sig_version=2)

Serialize application data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two application signatures are equal.

Parameters

other (AppSignature) – The other application signature.

Returns

True if the application signatures are equal. False if they are not.

Return type

bool

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

__hash__ = None
class django_evolution.signature.ModelSignature(model_name, table_name, db_tablespace=None, index_together=[], pk_column=None, unique_together=[])

Bases: django_evolution.signature.BaseSignature

Signature information for a model.

Model signatures store information on the model and include signatures for its fields and _meta attributes.

classmethod from_model(model)

Create a model signature from a model.

This will store data on the model and its _meta attributes, and create a FieldSignature for each field.

Parameters

model (django.db.models.Model) – The model to create a signature from.

Returns

The signature based on the model.

Return type

ModelSignature

classmethod deserialize(model_name, model_sig_dict, sig_version, database='default')

Deserialize a serialized model signature.

Parameters
  • model_name (unicode) – The model name.

  • model_sig_dict (dict) – The dictionary containing model signature data.

  • sig_version (int) – The version of the serialized signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

ModelSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__init__(model_name, table_name, db_tablespace=None, index_together=[], pk_column=None, unique_together=[])

Initialize the signature.

Parameters
  • model_name (unicode) – The name of the model.

  • table_name (unicode) – The name of the table in the database.

  • db_tablespace (unicode, optional) – The tablespace for the model. This is database-specific.

  • index_together (list of tuple, optional) – A list of fields that are indexed together.

  • pk_column (unicode, optional) – The column for the primary key.

  • unique_together (list of tuple, optional) – The list of fields that are unique together.

property field_sigs

The field signatures on the model signature.

add_field(field)

Add a field to the model signature.

This will construct a FieldSignature and add it to this model signature.

Parameters

field (django.db.models.Field) – The field to create the signature from.

add_field_sig(field_sig)

Add a field signature to the model signature.

Parameters

field_sig (FieldSignature) – The field signature to add.

remove_field_sig(field_name)

Remove a field signature from the model signature.

Parameters

field_name (unicode) – The name of the field.

Raises

django_evolution.errors.MissingSignatureError – The field name does not represent a known field signature.

get_field_sig(field_name, required=False)

Return a field signature for the given field name.

Parameters
  • field_name (unicode) – The name of the field.

  • required (bool, optional) – Whether the model signature must be present. If True and the signature is missing, this will raise an exception.

Returns

The field signature, if found. If no field signature matches the field name, None will be returned.

Return type

FieldSignature

Raises

django_evolution.errors.MissingSignatureError – The model signature was not found, and required was True.

add_constraint(constraint)

Add an explicit constraint to the models.

This is only used on Django 2.2 or higher. It corresponds to the model._meta.constraints <django.db.models.Options.constraints attribute.

Parameters

constraint (django.db.models.BaseConstraint) – The constraint to add.

add_constraint_sig(constraint_sig)

Add an explicit constraint signature to the models.

This is only used on Django 2.2 or higher. It corresponds to the model._meta.constraints <django.db.models.Options.constraints attribute.

Parameters

constraint_sig (ConstraintSignature) – The constraint signature to add.

add_index(index)

Add an explicit index to the models.

This is only used on Django 1.11 or higher. It corresponds to the model._meta.indexes <django.db.models.Options.indexes attribute.

Parameters

index (django.db.models.Index) – The index to add.

add_index_sig(index_sig)

Add an explicit index signature to the models.

This is only used on Django 1.11 or higher. It corresponds to the model._meta.indexes <django.db.models.Options.indexes attribute.

Parameters

index_sig (IndexSignature) – The index signature to add.

has_unique_together_changed(old_model_sig)

Return whether unique_together has changed between signatures.

unique_together is considered to have changed under the following conditions:

  • They are different in value.

  • Either the old or new is non-empty (even if equal) and evolving from an older signature from Django Evolution pre-0.7, where unique_together wasn’t applied to the database.

Parameters

old_model_sig (ModelSignature) – The old model signature to compare against.

Returns

True if the value has changed. False if they’re considered equal for the purposes of evolution.

Return type

bool

diff(old_model_sig)

Diff against an older model signature.

This will return a dictionary containing the differences in fields and meta information between two signatures.

Parameters

old_model_sig (ModelSignature) – The old model signature to diff against.

Returns

A dictionary in the following form:

{
    'added': [
        <field name>,
        ...
    ],
    'deleted': [
        <field name>,
        ...
    ],
    'changed': {
        <field name>: <FieldSignature diff>,
        ...
    },
    'meta_changed': [
        <'constraints'>,
        <'indexes'>,
        <'index_together'>,
        <'unique_together'>,
    ],
}

Any key lacking a value will be ommitted from the diff.

Return type

collections.OrderedDict

Raises

TypeError – The old signature provided was not a ModelSignature.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

ModelSignature

serialize(sig_version=2)

Serialize model data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two model signatures are equal.

Parameters

other (ModelSignature) – The other model signature.

Returns

True if the model signatures are equal. False if they are not.

Return type

bool

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

__hash__ = None
class django_evolution.signature.ConstraintSignature(name, constraint_type, attrs=None)

Bases: django_evolution.signature.BaseSignature

Signature information for a explicit constraint.

These indexes were introduced in Django 1.11. They correspond to entries in the model._meta.indexes <django.db.models.Options.indexes attribute.

Constraint signatures store information on a constraint on model, including the constraint name, type, and any attribute values needed for constructing the constraint.

classmethod from_constraint(constraint)

Create a constraint signature from a field.

Parameters

constraint (django.db.models.BaseConstraint) – The constraint to create a signature from.

Returns

The signature based on the constraint.

Return type

ConstraintSignature

classmethod deserialize(constraint_sig_dict, sig_version, database='default')

Deserialize a serialized constraint signature.

Parameters
  • constraint_sig_dict (dict) – The dictionary containing constraint signature data.

  • sig_version (int) – The version of the serialized signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

ConstraintSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__init__(name, constraint_type, attrs=None)

Initialize the signature.

Parameters
  • name (unicode) – The name of the constraint.

  • constraint_type (cls) – The class for the constraint. This would be a subclass of django.db.models.BaseConstraint.

  • attrs (dict, optional) – Attributes to pass when constructing the constraint.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

ConstraintSignature

serialize(sig_version=2)

Serialize constraint data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two constraint signatures are equal.

Parameters

other (ConstraintSignature) – The other constraint signature.

Returns

True if the constraint signatures are equal. False if they are not.

Return type

bool

__hash__()

Return a hash of the signature.

This is required for comparison within a set.

Returns

The hash of the signature.

Return type

int

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

class django_evolution.signature.IndexSignature(fields, name=None)

Bases: django_evolution.signature.BaseSignature

Signature information for an explicit index.

These indexes were introduced in Django 1.11. They correspond to entries in the model._meta.indexes <django.db.models.Options.indexes attribute.

classmethod from_index(index)

Create an index signature from an index.

Parameters

index (django.db.models.Index) – The index to create the signature from.

Returns

The signature based on the index.

Return type

IndexSignature

classmethod deserialize(index_sig_dict, sig_version, database='default')

Deserialize a serialized index signature.

Parameters
  • index_sig_dict (dict) – The dictionary containing index signature data.

  • sig_version (int) – The version of the serialized signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

IndexSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__init__(fields, name=None)

Initialize the signature.

Parameters
  • fields (list of unicode) – The list of field names the index is comprised of.

  • name (unicode, optional) – The optional name of the index.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

IndexSignature

serialize(sig_version=2)

Serialize index data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two index signatures are equal.

Parameters

other (IndexSignature) – The other index signature.

Returns

True if the index signatures are equal. False if they are not.

Return type

bool

__hash__()

Return a hash of the signature.

This is required for comparison within a set.

Returns

The hash of the signature.

Return type

int

__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

class django_evolution.signature.FieldSignature(field_name, field_type, field_attrs=None, related_model=None)

Bases: django_evolution.signature.BaseSignature

Signature information for a field.

Field signatures store information on a field on model, including the field name, type, and any attribute values needed for migrating the schema.

classmethod from_field(field)

Create a field signature from a field.

Parameters

field (django.db.models.Field) – The field to create a signature from.

Returns

The signature based on the field.

Return type

FieldSignature

classmethod deserialize(field_name, field_sig_dict, sig_version, database='default')

Deserialize a serialized field signature.

Parameters
  • field_name (unicode) – The name of the field.

  • field_sig_dict (dict) – The dictionary containing field signature data.

  • sig_version (int) – The version of the serialized signature data.

  • database (unicode, optional) – The name of the database.

Returns

The resulting signature instance.

Return type

FieldSignature

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__init__(field_name, field_type, field_attrs=None, related_model=None)

Initialize the signature.

Parameters
  • field_name (unicode) – The name of the field.

  • field_type (cls) – The class for the field. This would be a subclass of django.db.models.Field.

  • field_attrs (dict, optional) – Attributes to set on the field.

  • related_model (unicode, optional) – The full path to a related model.

get_attr_value(attr_name, use_default=True)

Return the value for an attribute.

By default, this will return the default value for the attribute if it’s not explicitly set.

Parameters
  • attr_name (unicode) – The name of the attribute.

  • use_default (bool, optional) – Whether to return the default value for the attribute if it’s not explicitly set.

Returns

The value for the attribute.

Return type

object

get_attr_default(attr_name)

Return the default value for an attribute.

Parameters

attr_name (unicode) – The attribute name.

Returns

The default value for the attribute, or None.

Return type

object

is_attr_value_default(attr_name)

Return whether an attribute is set to its default value.

Parameters

attr_name (unicode) – The attribute name.

Returns

True if the attribute’s value is set to its default value. False if it has a custom value.

Return type

bool

diff(old_field_sig)

Diff against an older field signature.

This will return a list of field names that have changed between this field signature and an older one.

Parameters

old_field_sig (FieldSignature) – The old field signature to diff against.

Returns

The list of field names.

Return type

list

Raises

TypeError – The old signature provided was not a FieldSignature.

clone()

Clone the signature.

Returns

The cloned signature.

Return type

FieldSignature

serialize(sig_version=2)

Serialize field data to a signature dictionary.

Parameters

sig_version (int, optional) – The signature version to serialize as. This always defaults to the latest.

Returns

The serialized data.

Return type

dict

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.

__eq__(other)

Return whether two field signatures are equal.

Parameters

other (FieldSignature) – The other field signature.

Returns

True if the field signatures are equal. False if they are not.

Return type

bool

__hash__ = None
__repr__()

Return a string representation of the signature.

Returns

A string representation of the signature.

Return type

unicode

django_evolution.signature.validate_sig_version(sig_version)

Validate that a signature version is supported.

Parameters

sig_version (int) – The version of the signature to validate.

Raises

django_evolution.errors.InvalidSignatureVersion – The signature version provided isn’t supported.