django_evolution.mutations.base

Base support for mutations.

Added in version 2.2.

Classes

`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.
`BaseUpgradeMethodMutation`()	Base class for a mutation that changes an app's upgrade method.
`Simulation`(mutation, app_label, project_sig, ...)	State for a database mutation simulation.

class django_evolution.mutations.base.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.

Changed in version 2.2: Moved into the django_evolution.mutations.base module.

__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.base.BaseMutation

Bases: object

Base class for a schema mutation.

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

Changed in version 2.2: Moved into the django_evolution.mutations.base module.

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

generate_dependencies(app_label, **kwargs)

Return automatic dependencies for the parent evolution.

This allows a mutation to affect the order in which the parent evolution is applied, relative to other evolutions or migrations.

Changed in version 2.4.2:

Added support for replace_migrations as a result key.

Added in version 2.1.

Parameters:

app_label (unicode) – The label of the app containing this mutation.
**kwargs (dict) – Additional keyword arguments, for future use.

Returns:

A dictionary of dependencies. This may have zero or more of the following keys:

before_migrations
after_migrations
replace_migrations
before_evolutions
after_evolutions

Return type:

dict

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:

django_evolution.errors.CannotSimulate – The simulation cannot be executed for this mutation. The reason is in the exception’s message.
django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

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:

django_evolution.errors.CannotSimulate – The simulation cannot be executed for this mutation. The reason is in the exception’s message.
django_evolution.errors.SimulationFailure – The simulation failed. The reason is in the exception’s message.

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.

See django_evolution.serialization.serialize_to_python() for details.

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

__hash__()

Return a hash of this mutation.

Returns:: The mutation’s hash.
Return type:: int

__eq__(other)

Return whether this mutation equals another.

Two mutations are equal if they’re of the same type and generate the same hinted evolution.

Parameters:: other (BaseMutation) – The mutation to compare against.
Returns:: True if the mutations are equal. False if they are not.
Return type:: bool

__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

__annotations__ = {}

class django_evolution.mutations.base.BaseUpgradeMethodMutation

Bases: BaseMutation

Base class for a mutation that changes an app’s upgrade method.

Added in version 2.2.

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

generate_dependencies(app_label, **kwargs)

Return automatic dependencies for the parent evolution.

This allows a mutation to affect the order in which the parent evolution is applied, relative to other evolutions or migrations.

This must be implemented by subclasses.

Parameters:

app_label (unicode) – The label of the app containing this mutation.
**kwargs (dict) – Additional keyword arguments, for future use.

Returns:

A dictionary of dependencies. This may have zero or more of the following keys:

before_migrations
after_migrations
before_evolutions
after_evolutions

Return type:

dict

mutate(mutator)

Schedule an app mutation on the mutator.

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

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

__annotations__ = {}

class django_evolution.mutations.base.BaseModelMutation(model_name)

Bases: BaseMutation

Base class for a mutation affecting a single model.

Changed in version 2.2: Moved into the django_evolution.mutations.base module.

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:

mutator (django_evolution.mutators.ModelMutator) – The mutator to perform an operation on.
model (MockModel) – The model being mutated.

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

__annotations__ = {}

class django_evolution.mutations.base.BaseModelFieldMutation(model_name, field_name)

Bases: 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.

Changed in version 2.2: Moved into the django_evolution.mutations.base module.

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.

__annotations__ = {}