Migration Docs Package

migration_docs

migration_docs.bootstrap(msg=<function _pretty_msg>)[source]

Bootstrap migration docs with filler values when integrating docs with a project for the first time.

Parameters

msg (func) – A message printer for showing messages to the user.

Raises

RuntimeError – When migration docs have already been synced

migration_docs.check(msg=<function _pretty_msg>)[source]

Check migration notes. Return False if any of the conditions hold true: - There are migrations without docs. - There are documented migrations that no longer exist. - There are stale migration docs.

Parameters

msg (func) – A message printer for showing messages to the user.

Raises

bool – True when the migration docs are up to date, False otherwise.

migration_docs.show(app_labels=None, unapplied=False, style='default')[source]

Shows migration docs to the user

Parameters
  • app_labels (List[str]) – App labels to limit the shown migrations to.

  • unapplied (bool, default=False) – Only show unapplied migrations.

  • style (str, default='default') – The style to use when rendering. Corresponds to a Jinja template stored in .migration-docs/{style}_show.tpl.

Returns

The rendered migration list.

Return type

str

migration_docs.sync(msg=<function _pretty_msg>)[source]

Sync new migrations with the migration docs and prune migrations that no longer exist.

Parameters

msg (func) – A message printer for showing messages to the user.

migration_docs.update(migrations, msg=<function _pretty_msg>)[source]

Update migration docs for specific migrations.

Parameters
  • migrations (List[str]) – A list of migration labels to update (e.g. users.0001_initial).

  • msg (func) – A message printer for showing messages to the user.

class migration_docs.Migration(node, *, executor, loader, docs)[source]

A migration and its associated docs.

Migrations are typically loaded and accessed via the parent Migrations object. When loaded, the Migration has access to core migration attributes (e.g. atomic, sql, etc) and also has attributes for every attribute collected in the documentation schema. For example, if the user configured a type attribute to be collected in .migration-docs/migration.yaml, it would be accessible as a type attribute on this object.

property app_label

The Django app label of the migration

property applied

True if the migration has been applied

property atomic

True if the migration is executed in a transaction

hash

The MD5 hash of the migration file

property label

The unique identifying label of the migration

property name

The name of the migration (e.g. 0001_initial)

property operations

The raw list of migration operation objects

property operations_str

String representations of the migration operations

set_docs(prompt=True, defaults=None)[source]

Set docs about a migration

Parameters
  • prompt (boolean, default=False) – True if collecting data from a user.

  • defaults (dict, default=None) – When prompting, use these values as defaults.

sql

The raw SQL for the migration

class migration_docs.Migrations(using='default', loader=None, executor=None)[source]

A filterable and groupable list of migrations and their associated migration docs.

append(item)

S.append(value) – append value to the end of the sequence

bootstrap_docs()[source]

Bootstraps all migration docs to empty values.

clear() → None – remove all items from S
count(value) → integer – return number of occurrences of value
exclude(attr, value, match=False)

Exclude elements by an attribute.

Parameters
  • attr (str) – The name of the attribute.

  • value (str|bool) – The value to exclude by.

  • match (bool, default=False) – Treat value as a regex pattern and match against it.

Returns

A copy of the excluded list object.

Return type

self.__class__

extend(other)

S.extend(iterable) – extend sequence by appending elements from the iterable

filter(attr, value, match=False)

Filter elements by an attribute.

Parameters
  • attr (str) – The name of the attribute.

  • value (str|bool) – The value to filter by.

  • match (bool, default=False) – Treat value as a regex pattern and match against it.

Returns

A copy of the filtered list object.

Return type

self.__class__

group(attr, ascending_keys=False, descending_keys=False, none_key_first=False, none_key_last=False)

Group elements by an attribute.

Parameters
  • attr (str) – The attribute to group by.

  • ascending_keys (bool, default=False) – Sort the keys in ascending order.

  • descending_keys (bool, default=False) – Sort the keys in descending order.

  • none_key_first (bool, default=False) – Make the “None” key be first.

  • none_key_last (bool, default=False) – Make the “None” key be last.

Returns

A dictionary of self.__class__ keyed on groups.

Return type

collections.OrderedDict

index(value[, start[, stop]]) → integer – return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)

S.insert(index, value) – insert value before index

intersect(attr, values)

Return elements whose attributes intersects a set of values.

Parameters
  • attr (str) – The attribute to filter by.

  • values (Set[str]) – The values the attribute must be in.

Returns

A copy of the filtered list object.

Return type

self.__class__

pop([index]) → item – remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(item)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE