API

Configuration

enum django_copyist.config.CopyActions(value)

Member Type:

str

Valid values are as follows:

TAKE_FROM_ORIGIN = <CopyActions.TAKE_FROM_ORIGIN: 'TAKE_FROM_ORIGIN'>

TAKE_FROM_INPUT = <CopyActions.TAKE_FROM_INPUT: 'TAKE_FROM_INPUT'>

MAKE_COPY = <CopyActions.MAKE_COPY: 'MAKE_COPY'>

UPDATE_TO_COPIED = <CopyActions.UPDATE_TO_COPIED: 'UPDATE_TO_COPIED'>

SET_TO_FILTER = <CopyActions.SET_TO_FILTER: 'SET_TO_FILTER'>

enum django_copyist.config.DataModificationActions(value)

Member Type:

str

Valid values are as follows:

DELETE_BY_FILTER = <DataModificationActions.DELETE_BY_FILTER: 'DELETE_BY_FILTER'>

EXECUTE_FUNC = <DataModificationActions.EXECUTE_FUNC: 'EXECUTE_FUNC'>

class django_copyist.config.DataModificationStep(action: django_copyist.config.DataModificationActions, filter_field_to_input_key: dict[str, str] | None = None)

protocol django_copyist.config.DataPreparationFunc

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

static __call__(model_config: ModelCopyConfig, input_data: dict[str, Any], set_to_filter_map: SetToFilterMap, output_map: OutputMap) → None

A protocol that defines a function to be used for preparing data before the copying process.

This function is expected to take several parameters including the model configuration, input data, set to filter map, and output map. It does not return any value.

Parameters:

• model_config (ModelCopyConfig) – The configuration for the model being copied.

• input_data (Dict[str, Any]) – The input data for the copy request.

• set_to_filter_map (SetToFilterMap) – The current global set to filter map.

• output_map (OutputMap) – The current global output map.

class django_copyist.config.DataPreparationStep(action: django_copyist.config.DataModificationActions, filter_field_to_input_key: dict[str, str] | None = None, func: django_copyist.config.DataPreparationFunc | None = None)

class django_copyist.config.FieldCopyConfig(action: CopyActions, copy_with_config: ModelCopyConfig | None = None, reference_to: type[Model] | None = None, filter_config: FilterConfig | None = None, input_key: str | None = None)

This class is a configuration that describes how a specific field should be copied.

Parameters:

• action (CopyAction) – The action to be executed.

• copy_with_config (ModelCopyConfig, optional) – A nested instance of ModelCopyConfig. This should be defined if the action is MAKE_COPY. It describes how a nested model should be copied, defaults to None.

• reference_to (Model, optional) – The model type to which the field should be updated. This should be defined if the action is UPDATE_TO_COPIED or SET_TO_FILTER, defaults to None.

• filter_config (FilterConfig, optional) – An instance of FilterConfig. This should be defined if the action is SET_TO_FILTER. It describes how the value for the field should be queried from existing data, defaults to None.

• input_key (str, optional) – The key in the input data from which the value for the field should be taken. This should be defined if the action is TAKE_FROM_INPUT, defaults to None.

Raises:

ValueError – If the action is MAKE_COPY and copy_with_config is not defined, or if the action is UPDATE_TO_COPIED and reference_to is not defined, or if the action is SET_TO_FILTER and either filter_config or reference_to is not defined, or if the action is TAKE_FROM_INPUT and input_key is not defined.

class django_copyist.config.FieldFilterConfig(source: FilterSource, key: str | None = None)

This configuration specifies the source from which the filter value is obtained.

If the source is FROM_ORIGIN, the filter value is derived from the original model. If the source is FROM_INPUT, the filter value is extracted from the input data.

Parameters:

• source (FilterSource) – A FilterSource enumeration value. It can be either FROM_INPUT or FROM_ORIGIN.

• key (str, optional) – An optional key in the input data that identifies the filter value. This should be specified if the source is FROM_INPUT, defaults to None.

class django_copyist.config.FilterConfig(filters: dict[str, FieldFilterConfig] | None = None, filter_func: SetToFilterFunc | None = None)

This class is a configuration that describes how a field’s value should be queried from existing data.

Parameters:

• filters (Dict[str, FieldFilterConfig], optional) – A dictionary storing information on how a field should be queried. The key is the field name, and the value is a FieldFilterConfig instance. If a field is not present in filters, it will be ignored and the default for the model will be used, defaults to None.

• filter_func (SetToFilterFunc, optional) – An optional instance of SetToFilterFunc. If present, it will be used for querying the field value from existing data, defaults to None.

enum django_copyist.config.FilterSource(value)

Member Type:

str

Valid values are as follows:

FROM_INPUT = <FilterSource.FROM_INPUT: 'FROM_INPUT'>

FROM_ORIGIN = <FilterSource.FROM_ORIGIN: 'FROM_ORIGIN'>

class django_copyist.config.IgnoreCondition(filter_conditions: list[IgnoreFilter] | None = None, ignore_func: IgnoreFunc | None = None)

This configuration describes the conditions under which the copying of a model should be disregarded.

Either ‘filter_conditions’ or ‘ignore_func’ must be specified.

Attributes:

filter_conditions: An optional list of IgnoreFilter instances.

If provided, these will be used to filter out models that should not be copied.

ignore_func: A function that, when provided, should return a

list of models that are to be excluded from copying.

class django_copyist.config.IgnoreFilter(filter_name: str, set_to_filter_origin_model: type[Model], set_to_filter_field_name: str, filter_source: IgnoreFilterSource = IgnoreFilterSource.UNMATCHED_SET_TO_FILTER_VALUES)

This configuration describes a filter for excluding certain models during the copying process.

It is applicable when you wish to exclude a model from being copied if some of its fields do not match any existing data. This is particularly useful when using the SET_TO_FILTER action.

Parameters:

• filter_name (str) – The name of the filter field that will be used to exclude all models that do not match any existing data. Usually is an __in filter, as it will be given list of unmatched ids to exclude. e.g. if you have hierarchy Parent -> Child <-M2M-> Tag and want to ignore all parents, where child didn’t match any of its tags, you can use child_set__tags__id__in

• filter_source (IgnoreFilterSource) – The value of the IgnoreFilterSource enum. It is always set to UNMATCHED_SET_TO_FILTER_VALUES.

• set_to_filter_origin_model (Type[Model]) – The type of the model in which unmatched fields for the SET_TO_FILTER action are expected.

• set_to_filter_field_name (str) – The name of the field for which unmatched values are expected.

enum django_copyist.config.IgnoreFilterSource(value)

Member Type:

str

Valid values are as follows:

UNMATCHED_SET_TO_FILTER_VALUES = <IgnoreFilterSource.UNMATCHED_SET_TO_FILTER_VALUES: 'UNMATCHED_SET_TO_FILTER_VALUES'>

protocol django_copyist.config.IgnoreFunc

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

static __call__(model_config: ModelCopyConfig, set_to_filter_map: SetToFilterMap, model_extra_filter: Q | None, ignored_map: IgnoredMap, input_data: dict[str, Any]) → list[Model]

A protocol that defines a function to be used for ignoring certain models during the copying process.

This function is expected to take several parameters including the model configuration, set to filter map, model extra filter, ignored map, and input data. It should return a list of models that are to be excluded from copying.

Parameters:

• model_config (ModelCopyConfig) – The configuration for the model being copied.

• set_to_filter_map (SetToFilterMap) – The current global set to filter map.

• model_extra_filter (Q, optional) – An optional Q instance, representing current filters for model. It is generated by copyist during copy process (e.g. to filter instance list by parent id). You should apply it to your query to narrow down the list of models you are working with.

• ignored_map (IgnoredMap) – The current global ignored map.

• input_data (Dict[str, Any]) – The input data for the copy request.

Returns:

The list of models that are to be excluded from copying.

Return type:

List[Model]

django_copyist.config.MakeCopy(config: ModelCopyConfig) → FieldCopyConfig

This function is a shortcut for creating a FieldCopyConfig instance with the MAKE_COPY action.

Parameters:

config (ModelCopyConfig) – A nested instance of ModelCopyConfig. This describes how a nested model should be copied.

Returns:

A FieldCopyConfig instance with the action set to MAKE_COPY and the copy_with_config set to the provided config.

Return type:

FieldCopyConfig

class django_copyist.config.ModelCopyConfig(model: type[~django.db.models.base.Model], field_copy_actions: dict[str, ~django_copyist.config.FieldCopyConfig], ignore_condition: ~django_copyist.config.IgnoreCondition | None = None, compound_copy_actions: list[~django_copyist.config.ModelCopyConfig] = <factory>, filter_field_to_input_key: dict[str, str] = <factory>, data_preparation_steps: list[~django_copyist.config.DataPreparationStep] = <factory>, postcopy_steps: list[~django_copyist.config.PostcopyStep] = <factory>, static_filters: ~django.db.models.query_utils.Q | None = None)

This class is a configuration that describes how a specific model should be copied.

Parameters:

• model (Type[Model]) – The root model class that should be copied.

• field_copy_actions (Dict[str, FieldCopyConfig]) – A dictionary storing information on copying each field. The key is the field name, and the value is a FieldCopyConfig instance. If a field is not present in field_copy_actions, it will be ignored and the default for the model will be used.

• ignore_condition (IgnoreCondition, optional) – An optional instance of IgnoreCondition. This describes the condition on which copying of the model should be ignored, defaults to None.

• compound_copy_actions (List[ModelCopyConfig], optional) – A list of ModelCopyConfig instances. The copying for these instances should be executed after copying the current model. This should be used if describing other models in a nested style in field_copy_actions is not appropriate (e.g., when copying another model depends on multiple fields), defaults to None.

• filter_field_to_input_key (Dict[str, str], optional) – A dictionary mapping of model field names, which are used for the initial querying of the model, to input data key (e.g., {“id”: “player_id”} if you want to query by Player.id and you have the field “player_id” in input_data), defaults to None.

• data_preparation_steps (List[DataPreparationStep], optional) – A list of DataPreparationStep instances. These can be used if special actions are needed to prepare the database state before copying, for example, if you need to delete some data in the target “location” before copying data from the origin, defaults to None.

• postcopy_steps (List[PostcopyStep], optional) – A list of PostcopyStep instances. These can be used if special actions are needed after the model data is copied, defaults to None.

• static_filters (Q, optional) – An optional Q instance. If present, this will be used as an additional filter for querying the given model, defaults to None.

protocol django_copyist.config.PostcopyFunc

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

static __call__(model_config: ModelCopyConfig, input_data: dict[str, Any], set_to_filter_map: SetToFilterMap, output_map: OutputMap, copy_intent_list: List[CopyIntent]) → None

A protocol that defines a function to be used for post-copy operations.

This function is expected to take several parameters including the model configuration, input data, set to filter map, output map, and a list of copy intents. It does not return any value.

Parameters:

• model_config (ModelCopyConfig) – The configuration for the model being copied.

• input_data (Dict[str, Any]) – The input data for the copy request.

• set_to_filter_map (SetToFilterMap) – The current global set to filter map.

• output_map (OutputMap) – The current global output map.

• copy_intent_list (List[CopyIntent]) – The list of copy intents. Copy intent stores information about original and copied model

class django_copyist.config.PostcopyStep(action: DataModificationActions, filter_field_to_input_key: dict[str, str] | None = None, func: PostcopyFunc | None = None)

This class represents a step to be executed after the copying of model data.

Parameters:

• action (Action) – The action to be executed.

• filter_field_to_input_key (dict, optional) – An optional mapping of model field names to input data keys. This is used for the DELETE_BY_FILTER action. If present, it will be used as an additional filter for querying the given model, defaults to None.

• func (PostcopyFunc, optional) – An optional instance of PostcopyFunc. If present, it will be executed after the copying of model data, defaults to None.

protocol django_copyist.config.SetToFilterFunc

typing.Protocol.

Classes that implement this protocol must have the following methods / attributes:

static __call__(model_config: ModelCopyConfig, input_data: dict[str, Any], field_name: str, field_copy_config: FieldCopyConfig, set_to_filter_map: SetToFilterMap, instance_list: list[Model], referenced_instance_list: list[Model]) → FieldSetToFilterMap

A protocol that defines a function to be used for setting the filter map for a field.

This function is expected to take several parameters including the model configuration, input data, field name, field copy configuration, set to filter map, instance list, and referenced instance list. It should return a FieldSetToFilterMap, which stores mapping of original object id string to substitute id or None.

Parameters:

• model_config (ModelCopyConfig) – The configuration for the model being copied.

• input_data (Dict[str, Any]) – The input data for the copy request.

• field_name (str) – The name of the field for which the filter map is being set.

• field_copy_config (FieldCopyConfig) – The copy configuration for the SET_TO_FILTER field.

• set_to_filter_map (SetToFilterMap) – The current global set to filter map.

• instance_list (List[Model]) – The list of instances of the model being copied.

• referenced_instance_list (List[Model]) – The list of instances that are referenced by the field.

Returns:

The updated set to filter map for the field.

Return type:

FieldSetToFilterMap

django_copyist.config.TAKE_FROM_ORIGIN = FieldCopyConfig(action=<CopyActions.TAKE_FROM_ORIGIN: 'TAKE_FROM_ORIGIN'>, copy_with_config=None, reference_to=None, filter_config=None, input_key=None)

Shortcut for creating FieldCopyConfig with TAKE_FROM_ORIGIN action

django_copyist.config.UpdateToCopied(reference: type[Model]) → FieldCopyConfig

This function is a shortcut for creating a FieldCopyConfig instance with the UPDATE_TO_COPIED action.

Parameters:

reference (Type[Model]) – The type of the model to which the field should be updated.

Returns:

A FieldCopyConfig instance with the action set to UPDATE_TO_COPIED and the reference set to the provided model type.

Return type:

FieldCopyConfig

Copy request and result

enum django_copyist.copy_request.AbortReason(value)

Member Type:

str

Valid values are as follows:

NOT_MATCHED = <AbortReason.NOT_MATCHED: 'NOT_MATCHED'>

IGNORED = <AbortReason.IGNORED: 'IGNORED'>

DATA_CHANGED_STF = <AbortReason.DATA_CHANGED_STF: 'DATA_CHANGED_STF'>

DATA_CHANGED_IGNORED = <AbortReason.DATA_CHANGED_IGNORED: 'DATA_CHANGED_IGNORED'>

class django_copyist.copy_request.CopyRequest(input_data: dict[str, Any], config: CopyistConfig, confirm_write: bool = False, set_to_filter_map: SetToFilterMap | None = None, ignored_map: IgnoredMap | None = None)

This is the base class for a copy request, which serves as the input for the Copyist.

Parameters:

• input_data (dict[str, Any]) – The input data used to determine which models should be copied. It can also contain additional data that will be utilized during the copying process.

• config (CopyistConfig) – An instance of CopyistConfig that holds all the necessary settings for the copying operation.

• confirm_write (bool, optional) – A flag indicating whether the copy operation should proceed even if there are unmatched values in the models or some models are ignored, defaults to False.

• set_to_filter_map (SetToFilterMap, optional) – A dictionary from the previous copy result that holds substitute data. If provided, the Copyist will compare it with the new set_to_filter_map to ensure that the data hasn’t changed since the last copy attempt. If the data has changed, the Copyist will return a CopyResult with ‘is_copy_successful’ set to False and an updated set_to_filter_map, even if ‘confirm_write’ is True, defaults to None.

• ignored_map (IgnoredMap, optional) – A dictionary from the previous copy result that holds data of ignored models. If provided, the Copyist will compare it with the new ignored_map to ensure that the data hasn’t changed since the last copy attempt. If the data has changed, the Copyist will return a CopyResult with ‘is_copy_successful’ set to False and an updated ignored_map, even if ‘confirm_write’ is True, defaults to None.

class django_copyist.copy_request.CopyResult(is_copy_successful: bool, output_map: OutputMap | None, ignored_map: IgnoredMap, set_to_filter_map: SetToFilterMap, reason: AbortReason | None = None)

This is the base class for a copy result, which serves as the output for the Copyist.

Variables:

• is_copy_successful – A flag indicating whether the copy operation was successful, defaults to False.

• output_map – A dictionary that contains a mapping of model names to mappings of primary keys in the source and destination databases, defaults to None.

• ignored_map – A dictionary that contains a mapping of model names to lists of primary keys of models that were ignored during the copying process, defaults to None.

• set_to_filter_map –

  A dictionary that contains data of substitutes matched by the SET_TO_FILTER action. The structure is as follows:

  {
      "model_name": {
          "field_name": {
              "original_value": "new_value" | None
          }
      }
  }
  

  Defaults to None.

• reason – The reason code, returned if is_copy_successful is False, defaults to None.

Copyist

class django_copyist.copyist.CopyIntent(origin: ~django.db.models.base.Model, copy_data: dict[str, ~typing.Any] = <factory>, m2m_copy_intent_list: list[~django_copyist.copyist.M2MCopyIntent] = <factory>, copied: ~django.db.models.base.Model | None = None)

Intermediate model storing intent for copying data for instance of model

class django_copyist.copyist.Copyist(copy_request: CopyRequest)

The main class responsible for copying Django model instances based on the provided configuration.

Parameters:

copy_request (CopyRequest) – The copy request object containing the configuration and input data for the copy operation.

Variables:

• request (CopyRequest) – The copy request object containing the configuration and input data for the copy operation.

• config (CopyistConfig) – The configuration for the copy operation.

• input_data (dict) – The input data for the copy operation.

class django_copyist.copyist.CopyistConfig(model_configs: list[ModelCopyConfig])

This is the root copy configuration that contains a list of ModelCopyConfig.

Variables:

model_configs (list[ModelCopyConfig]) – The list of model configurations.

class django_copyist.copyist.IgnoreEvaluation(model_config: ModelCopyConfig, original_extra_filter: Q | None)

Intermediate model storing intent after validation to resolve ignore conditions

class django_copyist.copyist.M2MCopyIntent(field_name: str, related_id_list: list[Any], backward_id_key: str, forward_id_key: str, through_model: type[Model], from_model: type[Model], to_model: type[Model], use_copied_related_instances: bool, use_set_to_filter_values: bool)

Intermediate model storing intent for copying data for many to many relation

class django_copyist.copyist.SubstituteCondition(filter_field_name: str, filter_field_value: Any)

Intermediate model storing single condition for matching origin and substitute instances