django_evolution.mutations

Support for schema mutation operations and hint output.

Classes

AddField(model_name, field_name, field_type)

A mutation that adds a field to a model.

BaseModelFieldMutation(model_name, field_name)

Base class for any fields that mutate a model.

BaseModelMutation(model_name)

Base class for a mutation affecting a single model.

BaseMutation()

Base class for a schema mutation.

ChangeField(model_name, field_name[, initial])

A mutation that changes attributes on a field on a model.

ChangeMeta(model_name, prop_name, new_value)

A mutation that changes meta proeprties on a model.

DeleteApplication()

A mutation that deletes an application.

DeleteField(model_name, field_name)

A mutation that deletes a field from a model.

DeleteModel(model_name)

A mutation that deletes a model.

MoveToDjangoMigrations([mark_applied])

A mutation that uses Django migrations for an app’s future upgrades.

RenameAppLabel(old_app_label, new_app_label)

A mutation that renames the app label for an application.

RenameField(model_name, old_field_name, …)

A mutation that renames a field on a model.

RenameModel(old_model_name, new_model_name, …)

A mutation that renames a model.

SQLMutation(tag, sql[, update_func])

A mutation that executes SQL on the database.

Simulation(mutation, app_label, project_sig, …)

State for a database mutation simulation.

class django_evolution.mutations.Simulation(mutation, app_label, project_sig, database_state, legacy_app_label=None, database='default')

Bases: object

State for a database mutation simulation.

This provides state and utility functions for simulating a mutation on a database signature. This is provided to BaseMutation.simulate() functions, given them access to all simulation state and a consistent way of failing simulations.

__init__(mutation, app_label, project_sig, database_state, legacy_app_label=None, database='default')

Initialize the simulation state.

Parameters
  • mutation (BaseMutation) – The mutation this simulation applies to.

  • app_label (unicode) – The name of the application this simulation applies to.

  • project_sig (dict) – The project signature for the simulation to look up and modify.

  • database_state (django_evolution.db.state.DatabaseState) – The database state for the simulation to look up and modify.

  • legacy_app_label (unicode, optional) – The legacy label of the app this simulation applies to. This is based on the module name and is used in the transitioning of pre-Django 1.7 signatures.

  • database (unicode, optional) – The registered database name in Django to simulate operating on.

get_evolver()

Return an evolver for the database.

Returns

The database evolver for this type of database.

Return type

django_evolution.db.EvolutionOperationsMulti

get_app_sig()

Return the current application signature.

Returns

The application signature.

Return type

dict

Returns

The signature for the app.

Return type

django_evolution.signature.AppSignature

Raises

django_evolution.errors.SimulationFailure – A signature could not be found for the application.

get_model_sig(model_name)

Return the signature for a model with the given name.

Parameters

model_name (unicode) – The name of the model to fetch a signature for.

Returns

The signature for the model.

Return type

django_evolution.signature.ModelSignature

Raises

django_evolution.errors.SimulationFailure – A signature could not be found for the model or its parent application.

get_field_sig(model_name, field_name)

Return the signature for a field with the given name.

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

  • field_name (unicode) – The name of the field to fetch a signature for.

Returns

The signature for the field.

Return type

django_evolution.signature.FieldSignature

Raises

django_evolution.errors.SimulationFailure – A signature could not be found for the field, its parent model, or its parent application.

fail(error, **error_vars)

Fail the simulation.

This will end up raising a SimulationFailure with an error message based on the mutation’s simulation failed message an the provided message.

Parameters
  • error (unicode) – The error message for this particular failure.

  • **error_vars (dict) – Variables to include in the error message. These will override any defaults for the mutation’s error.

Raises

django_evolution.errors.SimulationFailure – The resulting simulation failure with the given error.

class django_evolution.mutations.BaseMutation

Bases: object

Base class for a schema mutation.

These are responsible for simulating schema mutations and applying actual mutations to a database signature.

simulation_failure_error = 'Cannot simulate the mutation.'
error_vars = {}
generate_hint()

Return a hinted evolution for the mutation.

This will generate a line that will be used in a hinted evolution file. This method generally should not be overridden. Instead, use get_hint_params().

Returns

A hinted evolution statement for this mutation.

Return type

unicode

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

run_simulation(**kwargs)

Run a simulation for a mutation.

This will prepare and execute a simulation on this mutation, constructing a Simulation and passing it to simulate(). The simulation will apply a mutation on the provided database signature, modifying it to match the state described to the mutation. This allows Django Evolution to test evolutions before they hit the database.

Parameters

simulation (Simulation) – The state for the simulation.

Raises
simulate(simulation)

Perform a simulation of a mutation.

This will attempt to perform a mutation on the database signature, modifying it to match the state described to the mutation. This allows Django Evolution to test evolutions before they hit the database.

Parameters

simulation (Simulation) – The state for the simulation.

Raises
mutate(mutator)

Schedule a database mutation on the mutator.

This will instruct the mutator to perform one or more database mutations for an app. Those will be scheduled and later executed on the database, if not optimized out.

Parameters

mutator (django_evolution.mutators.AppMutator) – The mutator to perform an operation on.

Raises

django_evolution.errors.EvolutionNotImplementedError – The configured mutation is not supported on this type of database.

is_mutable(app_label, project_sig, database_state, database)

Return whether the mutation can be applied to the database.

This should check if the database or parts of the signature matches the attributes provided to the mutation.

Parameters
  • app_label (unicode) – The label for the Django application to be mutated.

  • project_sig (dict) – The project’s schema signature.

  • database_state (django_evolution.db.state.DatabaseState) – The database’s schema signature.

  • database (unicode) – The name of the database the operation would be performed on.

Returns

True if the mutation can run. False if it cannot.

Return type

bool

serialize_value(value)

Serialize a value for use in a mutation statement.

This will attempt to represent the value as something Python can execute, across Python versions. The string representation of the value is used by default. If that representation is of a Unicode string, and that string include a u prefix, it will be stripped.

Parameters

value (object) – The value to serialize.

Returns

The serialized string.

Return type

unicode

serialize_attr(attr_name, attr_value)

Serialize an attribute for use in a mutation statement.

This will create a name=value string, with the value serialized using serialize_value().

Parameters
  • attr_name (unicode) – The attribute’s name.

  • attr_value (object) – The attribute’s value.

Returns

The serialized attribute string.

Return type

unicode

__str__()

Return a hinted evolution for the mutation.

Returns

The hinted evolution.

Return type

unicode

__repr__()

Return a string representation of the mutation.

Returns

A string representation of the mutation.

Return type

unicode

class django_evolution.mutations.BaseModelMutation(model_name)

Bases: django_evolution.mutations.BaseMutation

Base class for a mutation affecting a single model.

error_vars = {'model_name': 'model_name'}
__init__(model_name)

Initialize the mutation.

Parameters

model_name (unicode) – The name of the model being mutated.

evolver(model, database_state, database=None)
mutate(mutator, model)

Schedule a model mutation on the mutator.

This will instruct the mutator to perform one or more database mutations for a model. Those will be scheduled and later executed on the database, if not optimized out.

Parameters
Raises

django_evolution.errors.EvolutionNotImplementedError – The configured mutation is not supported on this type of database.

is_mutable(app_label, project_sig, database_state, database)

Return whether the mutation can be applied to the database.

This will if the database matches that of the model.

Parameters
  • app_label (unicode) – The label for the Django application to be mutated.

  • project_sig (dict, unused) – The project’s schema signature.

  • database_state (django_evolution.db.state.DatabaseState, unused) – The database state.

  • database (unicode) – The name of the database the operation would be performed on.

Returns

True if the mutation can run. False if it cannot.

Return type

bool

class django_evolution.mutations.BaseModelFieldMutation(model_name, field_name)

Bases: django_evolution.mutations.BaseModelMutation

Base class for any fields that mutate a model.

This is used for classes that perform any mutation on a model. Such mutations will be provided a model they can work with.

Operations added to the mutator by this field will be associated with that model. That will allow the operations backend to perform any optimizations to improve evolution time for the model.

error_vars = {'field_name': 'field_name', 'model_name': 'model_name'}
__init__(model_name, field_name)

Initialize the mutation.

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

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

class django_evolution.mutations.DeleteField(model_name, field_name)

Bases: django_evolution.mutations.BaseModelFieldMutation

A mutation that deletes a field from a model.

simulation_failure_error = 'Cannot delete the field "%(field_name)s" on model "%(app_label)s.%(model_name)s".'
get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to remove the specified field, modifying meta fields (unique_together) if necessary.

It will also check to make sure this is not a primary key and that the field exists.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a field deletion on the mutator.

This will instruct the mutator to perform a deletion of a field on a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.SQLMutation(tag, sql, update_func=None)

Bases: django_evolution.mutations.BaseMutation

A mutation that executes SQL on the database.

Unlike most mutations, this one is largely database-dependent. It allows arbitrary SQL to be executed. It’s recommended that the execution does not modify the schema of a table (unless it’s highly database-specific with no counterpart in Django Evolution), but rather is limited to things like populating data.

SQL statements cannot be optimized. Any scheduled database operations prior to the SQL statement will be executed without any further optimization. This can lead to longer database evolution times.

__init__(tag, sql, update_func=None)

Initialize the mutation.

Parameters
  • tag (unicode) – A unique tag identifying this SQL operation.

  • sql (unicode) – The SQL to execute.

  • update_func (callable, optional) – A function to call to simulate updating the database signature. This is required for simulate() to work.

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate a mutation for an application.

This will run the update_func provided when instantiating the mutation, passing it app_label and project_sig. It should then modify the signature to match what the SQL statement would do.

Parameters

simulation (Simulation) – The state for the simulation.

Raises
mutate(mutator)

Schedule a database mutation on the mutator.

This will instruct the mutator to execute the SQL for an app.

Parameters

mutator (django_evolution.mutators.AppMutator) – The mutator to perform an operation on.

Raises

django_evolution.errors.EvolutionNotImplementedError – The configured mutation is not supported on this type of database.

is_mutable(*args, **kwargs)

Return whether the mutation can be applied to the database.

Parameters
  • *args (tuple, unused) – Unused positional arguments.

  • **kwargs (tuple, unused) – Unused positional arguments.

Returns

True, always.

Return type

bool

class django_evolution.mutations.AddField(model_name, field_name, field_type, initial=None, **field_attrs)

Bases: django_evolution.mutations.BaseModelFieldMutation

A mutation that adds a field to a model.

simulation_failure_error = 'Cannot add the field "%(field_name)s" to model "%(app_label)s.%(model_name)s".'
__init__(model_name, field_name, field_type, initial=None, **field_attrs)

Initialize the mutation.

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

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

  • field_type (cls) – The field class to use. This must be a subclass of django.db.models.Field.

  • initial (object, optional) – The initial value for the field. This is required if non-null.

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

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to add the specified field.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a field addition on the mutator.

This will instruct the mutator to add a new field on a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
add_column(mutator, model)

Add a standard column to the model.

Parameters
add_m2m_table(mutator, model)

Add a ManyToMany column to the model and an accompanying table.

Parameters
class django_evolution.mutations.RenameField(model_name, old_field_name, new_field_name, db_column=None, db_table=None)

Bases: django_evolution.mutations.BaseModelFieldMutation

A mutation that renames a field on a model.

simulation_failure_error = 'Cannot rename the field "%(field_name)s" on model "%(app_label)s.%(model_name)s".'
__init__(model_name, old_field_name, new_field_name, db_column=None, db_table=None)

Initialize the mutation.

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

  • old_field_name (unicode) – The old (existing) name of the field.

  • new_field_name (unicode) – The new name for the field.

  • db_column (unicode, optional) – The explicit column name to set for the field.

  • db_table (object, optional) – The explicit table name to use, if specifying a ManyToManyField.

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to rename the specified field.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a field rename on the mutator.

This will instruct the mutator to rename a field on a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.ChangeField(model_name, field_name, initial=None, **field_attrs)

Bases: django_evolution.mutations.BaseModelFieldMutation

A mutation that changes attributes on a field on a model.

simulation_failure_error = 'Cannot change the field "%(field_name)s" on model "%(app_label)s.%(model_name)s".'
__init__(model_name, field_name, initial=None, **field_attrs)

Initialize the mutation.

Parameters
  • model_name (unicode) – The name of the model containing the field to change.

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

  • initial (object, optional) – The initial value for the field. This is required if non-null.

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

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to change attributes for the specified field.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a field change on the mutator.

This will instruct the mutator to change attributes on a field on a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.RenameModel(old_model_name, new_model_name, db_table)

Bases: django_evolution.mutations.BaseModelMutation

A mutation that renames a model.

simulation_failure_error = 'Cannot rename the model "%(app_label)s.%(model_name)s".'
__init__(old_model_name, new_model_name, db_table)

Initialize the mutation.

Parameters
  • old_model_name (unicode) – The old (existing) name of the model to rename.

  • new_model_name (unicode) – The new name for the model.

  • db_table (unicode) – The table name in the database for this model.

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to rename the specified model.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a model rename on the mutator.

This will instruct the mutator to rename a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.DeleteModel(model_name)

Bases: django_evolution.mutations.BaseModelMutation

A mutation that deletes a model.

simulation_failure_error = 'Cannot delete the model "%(app_label)s.%(model_name)s".'
get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to delete the specified model.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a model deletion on the mutator.

This will instruct the mutator to delete a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.DeleteApplication

Bases: django_evolution.mutations.BaseMutation

A mutation that deletes an application.

simulation_failure_error = 'Cannot delete the application "%(app_label)s".'
simulate(simulation)

Simulate the mutation.

This will alter the database schema to delete the specified application.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator)

Schedule an application deletion on the mutator.

This will instruct the mutator to delete an application, if it exists. It will be scheduled and later executed on the database, if not optimized out.

Parameters

mutator (django_evolution.mutators.AppMutator) – The mutator to perform an operation on.

is_mutable(*args, **kwargs)

Return whether the mutation can be applied to the database.

This will always return true. The mutation will safely handle the application no longer being around.

Parameters
  • *args (tuple, unused) – Positional arguments passed to the function.

  • **kwargs (dict, unused) – Keyword arguments passed to the function.

Returns

True, always.

Return type

bool

class django_evolution.mutations.ChangeMeta(model_name, prop_name, new_value)

Bases: django_evolution.mutations.BaseModelMutation

A mutation that changes meta proeprties on a model.

simulation_failure_error = 'Cannot change the "%(prop_name)s" meta property on model "%(app_label)s.%(model_name)s".'
error_vars = {'model_name': 'model_name', 'prop_name': 'prop_name'}
__init__(model_name, prop_name, new_value)

Initialize the mutation.

Parameters
  • model_name (unicode) – The name of the model to change meta properties on.

  • prop_name (unicode) – The name of the property to change.

  • new_value (object) – The new value for the property.

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

simulate(simulation)

Simulate the mutation.

This will alter the database schema to change metadata on the specified model.

Parameters

simulation (Simulation) – The state for the simulation.

Raises

django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

mutate(mutator, model)

Schedule a model meta property change on the mutator.

This will instruct the mutator to change a meta property on a model. It will be scheduled and later executed on the database, if not optimized out.

Parameters
class django_evolution.mutations.RenameAppLabel(old_app_label, new_app_label, legacy_app_label=None, model_names=None)

Bases: django_evolution.mutations.BaseMutation

A mutation that renames the app label for an application.

__init__(old_app_label, new_app_label, legacy_app_label=None, model_names=None)

Initialize self. See help(type(self)) for accurate signature.

get_hint_params()

Return parameters for the mutation’s hinted evolution.

Returns

A list of parameter strings to pass to the mutation’s constructor in a hinted evolution.

Return type

list of unicode

is_mutable(app_label, project_sig, database_state, database)

Return whether the mutation can be applied to the database.

Parameters
  • app_label (unicode) – The label for the Django application to be mutated.

  • project_sig (dict, unused) – The project’s schema signature.

  • database_state (django_evolution.db.state.DatabaseState, unused) – The database state.

  • database (unicode) – The name of the database the operation would be performed on.

Returns

True if the mutation can run. False if it cannot.

Return type

bool

simulate(simulation)

Simulate the mutation.

This will alter the signature to make any changes needed for the application’s evolution storage.

mutate(mutator)

Schedule an app mutation on the mutator.

This will inform the mutator of the new app label, for use in any future operations.

Parameters

mutator (django_evolution.mutators.AppMutator) – The mutator to perform an operation on.

class django_evolution.mutations.MoveToDjangoMigrations(mark_applied=['0001_initial'])

Bases: django_evolution.mutations.BaseMutation

A mutation that uses Django migrations for an app’s future upgrades.

This directs this app to evolve only up until this mutation, and to then hand any future schema changes over to Django’s migrations.

Once this mutation is used, no further mutations can be added for the app.

__init__(mark_applied=['0001_initial'])

Initialize the mutation.

Parameters

mark_applied (unicode, optional) – The list of migrations to mark as applied. Each of these should have been covered by the initial table or subsequent evolutions. By default, this covers the 0001_initial migration.

is_mutable(*args, **kwargs)

Return whether the mutation can be applied to the database.

Parameters
  • *args (tuple, unused) – Unused positional arguments.

  • **kwargs (tuple, unused) – Unused positional arguments.

Returns

True, always.

Return type

bool

simulate(simulation)

Simulate the mutation.

This will alter the app’s signature to mark it as being handled by Django migrations.

Parameters

simulation (Simulation) – The simulation being performed.

mutate(mutator)

Schedule an app mutation on the mutator.

As this mutation just modifies state on the signature, no actual database operations are performed.

Parameters

mutator (django_evolution.mutators.AppMutator, unused) – The mutator to perform an operation on.