wagtail/docs/reference/streamfield/data_migrations.md

(streamfield_data_migration_reference)=

# StreamField data migration reference

## wagtail.blocks.migrations.migrate_operation

### MigrateStreamData

```python
class MigrateStreamData(RunPython)
```

Subclass of RunPython for `StreamField` data migration operations

#### \_\_init\_\_

```python
def __init__(app_name,
             model_name,
             field_name,
             operations_and_block_paths,
             revisions_from=None,
             chunk_size=1024,
             **kwargs)
```

MigrateStreamData constructor

**Arguments**:

-   `app_name` _str_ - Name of the app.
-   `model_name` _str_ - Name of the model.
-   `field_name` _str_ - Name of the `StreamField`.
-   `operations_and_block_paths` _List[Tuple[operation, str]]_ - List of operations and the block paths to apply them to.
-   `revisions_from` _datetime, optional_ - Only revisions created from this date onwards will be updated. Passing `None` updates all revisions. Defaults to `None`. Note that live and latest revisions will be updated regardless of what value this takes.
-   `chunk_size` _int, optional_ - chunk size for `queryset.iterator` and `bulk_update`.
    Defaults to 1024.
-   `**kwargs` - atomic, elidable, hints for superclass `RunPython` can be given

**Example**:

Renaming a block named `field1` to `block1`:

```python
MigrateStreamData(
    app_name="blog",
    model_name="BlogPage",
    field_name="content",
    operations_and_block_paths=[
        (RenameStreamChildrenOperation(old_name="field1", new_name="block1"), ""),
    ],
    revisions_from=datetime.datetime(2022, 7, 25)
)
```

## wagtail.blocks.migrations.operations

(rename_stream_children_operation)=

### RenameStreamChildrenOperation

```python
class RenameStreamChildrenOperation(BaseBlockOperation)
```

Renames all `StreamBlock` children of the given type

**Notes**:

The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be renamed, not the block being renamed.

**Attributes**:

-   `old_name` _str_ - name of the child block type to be renamed
-   `new_name` _str_ - new name to rename to

(rename_struct_children_operation)=

### RenameStructChildrenOperation

```python
class RenameStructChildrenOperation(BaseBlockOperation)
```

Renames all `StructBlock` children of the given type

**Notes**:

The `block_path_str` when using this operation should point to the parent `StructBlock` which contains the blocks to be renamed, not the block being renamed.

**Attributes**:

-   `old_name` _str_ - name of the child block type to be renamed
-   `new_name` _str_ - new name to rename to

(remove_stream_children_operation)=

### RemoveStreamChildrenOperation

```python
class RemoveStreamChildrenOperation(BaseBlockOperation)
```

Removes all `StreamBlock` children of the given type

**Notes**:

The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be removed, not the block being removed.

**Attributes**:

-   `name` _str_ - name of the child block type to be removed

(remove_struct_children_operation)=

### RemoveStructChildrenOperation

```python
class RemoveStructChildrenOperation(BaseBlockOperation)
```

Removes all `StructBlock` children of the given type

**Notes**:

The `block_path_str` when using this operation should point to the parent `StructBlock` which contains the blocks to be removed, not the block being removed.

**Attributes**:

-   `name` _str_ - name of the child block type to be removed

(stream_children_to_list_block_operation)=

### StreamChildrenToListBlockOperation

```python
class StreamChildrenToListBlockOperation(BaseBlockOperation)
```

Combines `StreamBlock` children of the given type into a new `ListBlock`

**Notes**:

The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.

**Attributes**:

-   `block_name` _str_ - name of the child block type to be combined
-   `list_block_name` _str_ - name of the new `ListBlock` type

(stream_children_to_stream_block_operation)=

### StreamChildrenToStreamBlockOperation

```python
class StreamChildrenToStreamBlockOperation(BaseBlockOperation)
```

Combines `StreamBlock` children of the given types into a new `StreamBlock`

**Notes**:

The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.

**Attributes**:

-   `block_names` _[str]_ - names of the child block types to be combined
-   `stream_block_name` _str_ - name of the new `StreamBlock` type

(alter_block_value_operation)=

### AlterBlockValueOperation

```python
class AlterBlockValueOperation(BaseBlockOperation)
```

Alters the value of each block to the given value

**Attributes**:

-   `new_value`: new value to change to

(stream_children_to_struct_block_operation)=

### StreamChildrenToStructBlockOperation

```python
class StreamChildrenToStructBlockOperation(BaseBlockOperation)
```

Move each `StreamBlock` child of the given type inside a new `StructBlock`

A new `StructBlock` will be created as a child of the parent `StreamBlock` for each child block of the given type, and then that child block will be moved from the parent StreamBlocks children inside the new `StructBlock` as a child of that `StructBlock`.

**Example**:

Consider the following `StreamField` definition:

```python
mystream = StreamField([("char1", CharBlock()), ...], ...)
```

Then the stream data would look like the following:

```python
[
    ...,
    { "type": "char1", "value": "Value1", ... },
    { "type": "char1", "value": "Value2", ... },
    ...
]
```

And if we define the operation like this:

```python
StreamChildrenToStructBlockOperation("char1", "struct1")
```

Our altered stream data would look like this:

```python
[
    ...,
    { "type": "struct1", "value": { "char1": "Value1" } },
    { "type": "struct1", "value": { "char1": "Value2" } },
    ...,
]
```

**Notes**:

-   The `block_path_str` when using this operation should point to the parent `StreamBlock` which contains the blocks to be combined, not the child block itself.
-   Block ids are not preserved here since the new blocks are structurally different than the previous blocks.

**Attributes**:

-   `block_names` _str_ - names of the child block types to be combined
-   `struct_block_name` _str_ - name of the new `StructBlock` type

## wagtail.blocks.migrations.utils

### InvalidBlockDefError

```python
class InvalidBlockDefError(Exception)
```

Exception for invalid block definitions

#### map_block_value

```python
def map_block_value(block_value, block_def, block_path, operation, **kwargs)
```

Maps the value of a block.

**Arguments**:

-   `block_value`: The value of the block. This would be a list or dict of children for structural blocks.
-   `block_def`: The definition of the block.
-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.
-   `operation`: An Operation class instance (extends `BaseBlockOperation`), which has an `apply` method for mapping values.

**Returns**:

Transformed value

#### map_struct_block_value

```python
def map_struct_block_value(struct_block_value, block_def, block_path,
                           **kwargs)
```

Maps each child block in a `StructBlock` value.

**Arguments**:

-   `stream_block_value`: The value of the `StructBlock`, a dict of child blocks
-   `block_def`: The definition of the `StructBlock`
-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.

**Returns**:

-   mapped_value: The value of the `StructBlock` after transforming its children.

#### map_list_block_value

```python
def map_list_block_value(list_block_value, block_def, block_path, **kwargs)
```

Maps each child block in a `ListBlock` value.

**Arguments**:

-   `stream_block_value`: The value of the `ListBlock`, a list of child blocks
-   `block_def`: The definition of the `ListBlock`
-   `block_path`: A `"."` separated list of names of the blocks from the current block (not included) to the nested block of which the value will be passed to the operation.

**Returns**:

-   mapped_value: The value of the `ListBlock` after transforming all the children.

#### apply_changes_to_raw_data

```python
def apply_changes_to_raw_data(raw_data, block_path_str, operation, streamfield,
                              **kwargs)
```

Applies changes to raw stream data

**Arguments**:

-   `raw_data`: The current stream data (a list of top level blocks)
-   `block_path_str`: A `"."` separated list of names of the blocks from the top level block to the nested block of which the value will be passed to the operation.
-   `operation`: A subclass of `operations.BaseBlockOperation`. It will have the `apply` method for applying changes to the matching block values.
-   `streamfield`: The `StreamField` for which data is being migrated. This is used to get the definitions of the blocks.

**Returns**:

altered_raw_data:

## Block paths

Operations for `StreamField` data migrations defined in `wagtail.blocks.migrations` require a "block path" to determine which blocks they should be applied to.

```
block_path = "" | block_name ("." block_name)*
block_name = str
```

A block path is either:

-   the empty string, in which case the operation should be applied to the top-level stream; or
-   a `"."` (period) separated sequence of block names, where block names are the names given to the blocks in the `StreamField` definition.

Block names are the values associated with the `"type"` keys in the stream data's dictionary structures. As such, traversing or selecting `ListBlock` members requires the use of the `"item"` block name.

The value that an operation's `apply` method receives is the `"value"` member of the dict associated with the terminal block name in the block path.

For examples see [the tutorial](using_streamfield_migration_block_paths).