django_evolution.evolve

Main interface for evolving applications.

Classes

BaseEvolutionTask(task_id, evolver)

Base class for a task to perform during evolution.

EvolveAppTask(evolver, app[, evolutions, …])

A task for evolving models in an application.

Evolver([hinted, verbosity, interactive, …])

The main class for managing database evolutions.

PurgeAppTask(evolver, app_label)

A task for purging an application’s tables from the database.

class django_evolution.evolve.BaseEvolutionTask(task_id, evolver)

Bases: object

Base class for a task to perform during evolution.

can_simulate

Whether the task can be simulated without requiring additional information.

This is set after calling prepare().

Type

bool

evolution_required

Whether an evolution is required by this task.

This is set after calling prepare().

Type

bool

evolver

The evolver that will execute the task.

Type

Evolver

id

The unique ID for the task.

Type

unicode

new_evolutions

A list of evolution model entries this task would create.

This is set after calling prepare().

Type

list of django_evolution.models.Evolution

sql

A list of SQL statements to perform for the task. Each entry can be a string or tuple accepted by execute_sql().

Type

list

classmethod prepare_tasks(evolver, tasks, **kwargs)

Prepare a list of tasks.

This is responsible for calling prepare() on each of the provided tasks. It can augment this by calculating any other state needed in order to influence the tasks or react to them.

If this applies state to the class, it should always be careful to completely reset the state on each run, in case there are multiple Evolver instances at work within a process.

Parameters
  • evolver (Evolver) – The evolver that’s handling the tasks.

  • tasks (list of BaseEvolutionTask) – The list of tasks to prepare. These will match the current class.

  • **kwargs (dict) – Keyword arguments to pass to the tasks’ :py:meth:`prepare methods.

classmethod execute_tasks(evolver, tasks, **kwargs)

Execute a list of tasks.

This is responsible for calling execute() on each of the provided tasks. It can augment this by executing any steps before or after the tasks.

If this applies state to the class, it should always be careful to completely reset the state on each run, in case there are multiple Evolver instances at work within a process.

This may depend on state from prepare_tasks().

Parameters
  • evolver (Evolver) – The evolver that’s handling the tasks.

  • tasks (list of BaseEvolutionTask) – The list of tasks to execute. These will match the current class.

  • **kwargs (dict) – Keyword arguments to pass to the tasks’ :py:meth:`execute methods.

__init__(task_id, evolver)

Initialize the task.

Parameters
  • task_id (unicode) – The unique ID for the task.

  • evolver (Evolver) – The evolver that will execute the task.

is_mutation_mutable(mutation, **kwargs)

Return whether a mutation is mutable.

This is a handy wrapper around BaseMutation.is_mutable that passes standard arguments based on evolver state. Callers should pass any additional arguments that are required as keyword arguments.

Parameters
Returns

True if the mutation is mutable. False if it is not.

Return type

bool

prepare(hinted, **kwargs)

Prepare state for this task.

This is responsible for determining whether the task applies to the database. It must set evolution_required, new_evolutions, and sql.

This must be called before execute() or get_evolution_content().

Parameters
  • hinted (bool) – Whether to prepare the task for hinted evolutions.

  • **kwargs (dict, unused) – Additional keyword arguments passed for task preparation. This is provide for future expansion purposes.

execute(cursor)

Execute the task.

This will make any changes necessary to the database.

Parameters

cursor (django.db.backends.util.CursorWrapper) – The database cursor used to execute queries.

Raises

django_evolution.errors.EvolutionExecutionError – The evolution task failed. Details are in the error.

get_evolution_content()

Return the content for an evolution file for this task.

Returns

The evolution content.

Return type

unicode

__str__()

Return a string description of the task.

Returns

The string description.

Return type

unicode

class django_evolution.evolve.PurgeAppTask(evolver, app_label)

Bases: django_evolution.evolve.BaseEvolutionTask

A task for purging an application’s tables from the database.

app_label

The app label for the app to purge.

Type

unicode

__init__(evolver, app_label)

Initialize the task.

Parameters
  • evolver (Evolver) – The evolver that will execute the task.

  • app_label (unicode) – The app label for the app to purge.

prepare(**kwargs)

Prepare state for this task.

This will determine if the app’s tables need to be deleted from the database, and prepare the SQL for doing so.

Parameters

**kwargs (dict, unused) – Keyword arguments passed for task preparation.

execute(cursor)

Execute the task.

This will delete any tables owned by the application.

Parameters

cursor (django.db.backends.util.CursorWrapper) – The database cursor used to execute queries.

Raises

django_evolution.errors.EvolutionExecutionError – The evolution task failed. Details are in the error.

__str__()

Return a string description of the task.

Returns

The string description.

Return type

unicode

class django_evolution.evolve.EvolveAppTask(evolver, app, evolutions=None, migrations=None)

Bases: django_evolution.evolve.BaseEvolutionTask

A task for evolving models in an application.

This task will run through any evolutions in the provided application and handle applying each of those evolutions that haven’t yet been applied.

app

The app module to evolve.

Type

module

app_label

The app label for the app to evolve.

Type

unicode

classmethod prepare_tasks(evolver, tasks, **kwargs)

Prepare a list of tasks.

If migrations are supported, then before preparing any of the tasks, this will begin setting up state needed to apply any migrations for apps that use them (or will use them after any evolutions are applied).

After tasks are prepared, this will apply any migrations that need to be applied, updating the app’s signature appropriately and recording all applied migrations.

Parameters
  • evolver (Evolver) – The evolver that’s handling the tasks.

  • tasks (list of BaseEvolutionTask) – The list of tasks to prepare. These will match the current class.

  • **kwargs (dict) – Keyword arguments to pass to the tasks’ :py:meth:`prepare methods.

Raises

django_evolution.errors.BaseMigrationError – There was an error with the setup or validation of migrations. A subclass containing additional details will be raised.

classmethod execute_tasks(evolver, tasks, **kwargs)

Execute a list of tasks.

This is responsible for calling execute() on each of the provided tasks. It can augment this by executing any steps before or after the tasks.

Parameters
  • evolver (Evolver) – The evolver that’s handling the tasks.

  • tasks (list of BaseEvolutionTask) – The list of tasks to execute. These will match the current class.

  • cursor (django.db.backends.util.CursorWrapper) – The database cursor used to execute queries.

  • **kwargs (dict) – Keyword arguments to pass to the tasks’ :py:meth:`execute methods.

__init__(evolver, app, evolutions=None, migrations=None)

Initialize the task.

Parameters
  • evolver (Evolver) – The evolver that will execute the task.

  • app (module) – The app module to evolve.

  • evolutions (list of dict, optional) –

    Optional evolutions to use for the app instead of loading from a file. This is intended for testing purposes.

    Each dictionary needs a label key for the evolution label and a mutations key for a list of BaseMutation instances.

  • migrations (list of django.db.migrations.Migration, optional) – Optional migrations to use for the app instead of loading from files. This is intended for testing purposes.

prepare(hinted=False, **kwargs)

Prepare state for this task.

This will determine if there are any unapplied evolutions in the app, and record that state and the SQL needed to apply the evolutions.

Parameters
  • hinted (bool, optional) – Whether to prepare the task for hinted evolutions.

  • **kwargs (dict, unused) – Additional keyword arguments passed for task preparation.

execute(cursor, create_models_now=False)

Execute the task.

This will apply any evolutions queued up for the app.

Before the evolutions are applied for the app, the applying_evolution signal will be emitted. After, applied_evolution will be emitted.

Parameters
  • cursor (django.db.backends.util.CursorWrapper) – The database cursor used to execute queries.

  • create_models_now (bool, optional) – Whether to create models as part of this execution. Normally, this is handled in execute_tasks(), but this flag allows for more fine-grained control of table creation in limited circumstances (intended only by Evolver).

Raises

django_evolution.errors.EvolutionExecutionError – The evolution task failed. Details are in the error.

get_evolution_content()

Return the content for an evolution file for this task.

Returns

The evolution content.

Return type

unicode

__str__()

Return a string description of the task.

Returns

The string description.

Return type

unicode

class django_evolution.evolve.Evolver(hinted=False, verbosity=0, interactive=False, database_name='default')

Bases: object

The main class for managing database evolutions.

The evolver is used to queue up tasks that modify the database. These allow for evolving database models and purging applications across an entire Django project or only for specific applications. Custom tasks can even be written by an application if very specific database operations need to be made outside of what’s available in an evolution.

Tasks are executed in order, but batched by the task type. That is, if two instances of TaskType1 are queued, followed by an instance of TaskType2, and another of TaskType1, all 3 tasks of TaskType1 will be executed at once, with the TaskType2 task following.

Callers are expected to create an instance and queue up one or more tasks. Once all tasks are queued, the changes can be made using evolve(). Alternatively, evolution hints can be generated using generate_hints().

Projects will generally utilize this through the existing evolve Django management command.

connection

The database connection object being used for the evolver.

Type

django.db.backends.base.base.BaseDatabaseWrapper

database_name

The name of the database being evolved.

Type

unicode

database_state

The state of the database, for evolution purposes.

Type

django_evolution.db.state.DatabaseState

evolved

Whether the evolver has already performed its evolutions. These can only be done once per evolver.

Type

bool

hinted

Whether the evolver is operating against hinted evolutions. This may result in changes to the database without there being any accompanying evolution files backing those changes.

Type

bool

interactive

Whether the evolution operations are being performed in a way that allows interactivity on the command line. This is passed along to signal emissions.

Type

bool

initial_diff

The initial diff between the stored project signature and the current project signature.

Type

django_evolution.diff.Diff

project_sig

The project signature. This will start off as the previous signature stored in the database, but will be modified when mutations are simulated.

Type

django_evolution.signature.ProjectSignature

verbosity

The verbosity level for any output. This is passed along to signal emissions.

Type

int

version

The project version entry saved as the result of any evolution operations. This contains the current version of the project signature. It may be None until evolve() is called.

Type

django_evolution.models.Version

__init__(hinted=False, verbosity=0, interactive=False, database_name='default')

Initialize the evolver.

Parameters
  • hinted (bool, optional) – Whether to operate against hinted evolutions. This may result in changes to the database without there being any accompanying evolution files backing those changes.

  • verbosity (int, optional) – The verbosity level for any output. This is passed along to signal emissions.

  • interactive (bool, optional) – Whether the evolution operations are being performed in a way that allows interactivity on the command line. This is passed along to signal emissions.

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

Raises

django_evolution.errors.EvolutionBaselineMissingError – An initial baseline for the project was not yet installed. This is due to syncdb/migrate not having been run.

property tasks

A list of all tasks that will be performed.

This can only be accessed after all necessary tasks have been queued.

can_simulate()

Return whether all queued tasks can be simulated.

If any tasks cannot be simulated (for instance, a hinted evolution requiring manually-entered values), then this will return False.

This can only be called after all tasks have been queued.

Returns

True if all queued tasks can be simulated. False if any cannot.

Return type

bool

get_evolution_required()

Return whether there are any evolutions required.

This can only be called after all tasks have been queued.

Returns

True if any tasks require evolution. False if none do.

Return type

bool

diff_evolutions()

Return a diff between stored and post-evolution project signatures.

This will run through all queued tasks, preparing them and simulating their changes. The returned diff will represent the changes made in those tasks.

This can only be called after all tasks have been queued.

Returns

The diff between the stored signature and the queued changes.

Return type

django_evolution.diff.Diff

iter_evolution_content()

Generate the evolution content for all queued tasks.

This will loop through each tasks and yield any evolution content provided.

This can only be called after all tasks have been queued.

Yields

tuple – A tuple of (task, evolution_content).

queue_evolve_all_apps()

Queue an evolution of all registered Django apps.

This cannot be used if queue_evolve_app() is also being used.

Raises
queue_evolve_app(app)

Queue an evolution of a registered Django app.

Parameters

app (module) – The Django app to queue an evolution for.

Raises
queue_purge_old_apps()

Queue the purging of all old, stale Django apps.

This will purge any apps that exist in the stored project signature but that are no longer registered in Django.

This generally should not be used if queue_purge_app() is also being used.

Raises
queue_purge_app(app_label)

Queue the purging of a Django app.

Parameters

app_label (unicode) – The label of the app to purge.

Raises
queue_task(task)

Queue a task to run during evolution.

This should only be directly called if working with custom tasks. Otherwise, use a more specific queue method.

Parameters

task (BaseEvolutionTask) – The task to queue.

Raises
evolve()

Perform the evolution.

This will run through all queued tasks and attempt to apply them in a database transaction, tracking each new batch of evolutions as the tasks finish.

This can only be called once per evolver instance.

Raises
transaction()

Execute database operations in a transaction.

This is a convenience method for executing in a transaction using the evolver’s current database.

Context:

django.db.backends.util.CursorWrapper: The cursor used to execute statements.