django_evolution.utils.evolutions

Utilities for working with evolutions and mutations.

Functions

get_app_mutations(app[, evolution_labels, ...])

Return the mutations on an app provided by the given evolution names.

get_app_pending_mutations(app[, ...])

Return an app's pending mutations provided by the given evolution names.

get_app_upgrade_info(app[, scan_evolutions, ...])

Return the upgrade information to use for a given app.

get_applied_evolutions(app[, database])

Return the list of labels for applied evolutions for a Django app.

get_evolution_app_dependencies(app)

Return dependencies governing all evolutions for an app.

get_evolution_dependencies(app, evolution_label)

Return dependencies for an evolution.

get_evolution_module(app, evolution_label)

Return the module for a given evolution for an app.

get_evolution_sequence(app)

Return the list of evolution labels for a Django app.

get_evolutions_module(app)

Return the evolutions module for an app.

get_evolutions_module_name(app)

Return the name of the evolutions module for an app.

get_evolutions_path(app)

Return the evolutions path for an app.

get_evolutions_source(app)

Return the source for evolutions.

get_unapplied_evolutions(app[, database])

Return the list of labels for unapplied evolutions for a Django app.

has_evolutions_module(app)

Return whether an app has an evolutions module.

django_evolution.utils.evolutions.has_evolutions_module(app)

Return whether an app has an evolutions module.

Parameters:

app (module) – The app module.

Returns:

True if the app has an evolutions module. False if it does not.

Return type:

bool

django_evolution.utils.evolutions.get_evolutions_source(app)

Return the source for evolutions.

This is used to determine where evolutions are coming from. They can be provided by the app, project, or built into Django Evolution.

Parameters:

app (module) – The app module.

Returns:

The evolution source. This is an entry from EvolutionsSource.

Return type:

unicode

django_evolution.utils.evolutions.get_evolutions_module_name(app)

Return the name of the evolutions module for an app.

New in version 2.1.

Parameters:

app (module) – The app.

Returns:

The name of the evolutions module for the app. This is not guaranteed to be importable.

Return type:

unicode

django_evolution.utils.evolutions.get_evolutions_module(app)

Return the evolutions module for an app.

Parameters:

app (module) – The app.

Returns:

The evolutions module for the app, or None if it could not be found.

Return type:

module

django_evolution.utils.evolutions.get_evolution_module(app, evolution_label)

Return the module for a given evolution for an app.

New in version 2.1.

Parameters:
  • app (module) – The app.

  • evolution_label (unicode) – The label of the evolution.

Returns:

The evolution module, or None if it could not be found.

Return type:

module

django_evolution.utils.evolutions.get_evolutions_path(app)

Return the evolutions path for an app.

Parameters:

app (module) – The app.

Returns:

The path to the evolutions module for the app, or None if it could not be found.

Return type:

str

django_evolution.utils.evolutions.get_evolution_sequence(app)

Return the list of evolution labels for a Django app.

Parameters:

app (module) – The app to return evolutions for.

Returns:

The list of evolution labels.

Return type:

list of unicode

django_evolution.utils.evolutions.get_evolution_dependencies(app, evolution_label, custom_evolutions=[])

Return dependencies for an evolution.

Evolutions can depend on other evolutions or migrations, and can be marked as being a dependency of them as well (forcing the evolution to apply before another evolution/migration).

Dependencies are generally specified as a tuple of (app_label, name), where name is either a migration name or an evolution label.

Dependencies on evolutions can also be specified as simply a string containing an app label, which will reference the sequence of evolutions as a whole for that app.

Changed in version 2.2: Added the custom_evolutions argument.

New in version 2.1.

Parameters:
  • app (module) – The app the evolution is for.

  • evolution_label (unicode) – The label identifying the evolution for the app.

  • custom_evolutions (list of dict, optional) –

    An optional list of custom evolutions pertaining to the app, which will be searched if a module for evolution_label could not be found.

    Each item is a dictionary containing:

    Keys:
    • label (unicode) – The evolution label (which evolution_label will be compared against).

    • after_evolutions (list, optional) – A list of evolutions that this would apply after. Each item can be a string (indicating an evolution label within this app) or a tuple in the form of:

      (‘app_label’, ‘evolution_label’)

    • after_migrations (list of tuple, optional) – A list of migrations that this would apply after. Each item must be a tuple in the form of:

      (‘app_label’, ‘migration_name’)

    • after_evolutions (list, optional) – A list of evolutions that this would apply before. Each item can be a string (indicating an evolution label within this app) or a tuple in the form of:

      (‘app_label’, ‘evolution_label’)

    • after_migrations (list of tuple, optional) – A list of migrations that this would apply before. Each item must be a tuple in the form of:

      (‘app_label’, ‘migration_name’)

    New in version 2.2.

Returns:

A dictionary of dependency information for the evolution. This has the following keys:

  • before_migrations

  • after_migrations

  • before_evolutions

  • after_evolutions

If the evolution module was not found, this will return None instead.

Return type:

dict

django_evolution.utils.evolutions.get_evolution_app_dependencies(app)

Return dependencies governing all evolutions for an app.

These dependencies are defined in an evolutions/__init__.py file, and will ensure that other evolutions or migrations apply either before or after the app’s evolutions.

Dependencies are generally specified as a tuple of (app_label, name), where name is either a migration name or an evolution label.

Dependencies on evolutions can also be specified as simply a string containing an app label, which will reference the sequence of evolutions as a whole for that app.

New in version 2.1.

Parameters:

app (module) – The app the evolution is for.

Returns:

A dictionary of dependency information for the app. This has the following keys:

  • before_migrations

  • after_migrations

  • before_evolutions

  • after_evolutions

If the evolutions module was not found, this will return None instead.

Return type:

dict

django_evolution.utils.evolutions.get_unapplied_evolutions(app, database='default')

Return the list of labels for unapplied evolutions for a Django app.

Parameters:
  • app (module) – The app to return evolutions for.

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

Returns:

The labels of evolutions that have not yet been applied.

Return type:

list of unicode

django_evolution.utils.evolutions.get_applied_evolutions(app, database='default')

Return the list of labels for applied evolutions for a Django app.

Parameters:
  • app (module) – The app to return evolutions for.

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

Returns:

The labels of evolutions that have been applied.

Return type:

list of unicode

django_evolution.utils.evolutions.get_app_mutations(app, evolution_labels=None, database='default')

Return the mutations on an app provided by the given evolution names.

Parameters:
  • app (module) – The app the evolutions belong to.

  • evolution_labels (list of unicode, optional) –

    The labels of the evolutions to return mutations for.

    If None, this will factor in all evolution labels for the app.

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

Returns:

The list of mutations provided by the evolutions.

Return type:

list of django_evolution.mutations.BaseMutation

Raises:

django_evolution.errors.EvolutionException – One or more evolutions are missing.

django_evolution.utils.evolutions.get_app_pending_mutations(app, evolution_labels=[], mutations=None, old_project_sig=None, project_sig=None, database='default')

Return an app’s pending mutations provided by the given evolution names.

This is similar to get_app_mutations(), but filters the list of mutations down to remove any that are unnecessary (ones that do not operate on changed parts of the project signature).

Parameters:
  • app (module) – The app the evolutions belong to.

  • evolution_labels (list of unicode, optional) –

    The labels of the evolutions to return mutations for.

    If None, this will factor in all evolution labels for the app.

  • mutations (list of django_evolution.mutations.BaseMutation, optional) – An explicit list of mutations to use. If provided, evolution_labels will be ignored.

  • old_project_sig (django_evolution.signature.ProjectSignature, optional) – A pre-fetched old project signature. If provided, this will be used instead of the latest one in the database.

  • project_sig (django_evolution.signature.ProjectSignature, optional) – A project signature representing the current state of the database. If provided, this will be used instead of generating a new one from the current database state.

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

Returns:

The list of mutations provided by the evolutions.

Return type:

list of django_evolution.mutations.BaseMutation

Raises:

django_evolution.errors.EvolutionException – One or more evolutions are missing.

django_evolution.utils.evolutions.get_app_upgrade_info(app, scan_evolutions=True, simulate_applied=False, database=None)

Return the upgrade information to use for a given app.

This will determine if the app should be using Django Evolution or Django Migrations for any schema upgrades.

If an evolutions module is found, then this will determine the method to be UpgradeMethod.EVOLUTIONS, unless the app has been moved over to using Migrations.

If instead there’s a migrations module, then this will determine the method to be UpgradeMethod.MIGRATIONS.

Otherwise, this will return None, indicating that no established method has been chosen. This allows a determination to be made later, based on the Django version or the consumer’s choice.

Note that this may return that migrations are the preferred method for an app even on versions of Django that do not support migrations. It’s up to the caller to handle this however it chooses.

Parameters:
  • app (module) – The app module to determine the upgrade method for.

  • scan_evolutions (bool, optional) – Whether to scan evolutions for the app to determine the current upgrade method.

  • simulate_applied (bool, optional) –

    Return the upgrade method based on the state of the app if all mutations had been applied. This is useful for generating end state signatures.

    This is ignored if passing scan_evolutions=False.

  • database (unicode, optional) – The database to use for accessing stored evolution and migration information.

Returns:

A dictionary of information containing the following keys:

applied_migrations (MigrationList):

A list of migrations that have been applied to this app through any mutations. This will only be present if the upgrade method is set to use migrations and if running on a version of Django that supports migrations.

has_evolutions (bool):

Whether there are any evolutions for this app. This may come from the app, project, or Django Evolution.

has_migrations (bool):

Whether there are any migrations for this app.

upgrade_method (unicode):

The upgrade method. This will be a value from UpgradeMethod, or None if a clear determination could not be made.

Return type:

dict