django_evolution.evolve.evolver

Main Evolver interface for performing evolutions and migrations.

New in version 2.2: This was previously located in django_evolution.evolve.

Classes

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

The main class for managing database evolutions.
class django_evolution.evolve.evolver.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:
sql_executor(**kwargs)

Return an SQLExecutor for executing SQL.

This is a convenience method for creating an SQLExecutor to operate using the evolver’s current database.

New in version 2.1.

Parameters:

**kwargs (dict) – Additional keyword arguments used to construct the executor.

Returns:

The new SQLExecutor.

Return type:

django_evolution.utils.sql.SQLExecutor

transaction()

Execute database operations in a transaction.

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

Deprecated since version 2.1: This has been replaced with manual calls to SQLExecutor.

Context:

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