---
title: core
sidebarTitle: core
---

# `prefect.blocks.core`

## Functions

### `block_schema_to_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L89" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_schema_to_key(schema: BlockSchema) -> str
```


Defines the unique key used to lookup the Block class for a given schema.


### `schema_extra` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L263" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
schema_extra(schema: dict[str, Any], model: type['Block']) -> None
```


Customizes Pydantic's schema generation feature to add blocks related information.


## Classes

### `InvalidBlockRegistration` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L98" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised on attempted registration of the base Block
class or a Block interface class


### `UnknownBlockType` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L105" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a block type is not found in the registry.


### `BlockNotSavedError` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Raised when a given block is not saved and an operation that requires
the block to be saved is attempted.


### `Block` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


A base class for implementing a block that wraps an external service.

This class can be defined with an arbitrary set of fields and methods, and
couples business logic with data contained in an block document.
`_block_document_name`, `_block_document_id`, `_block_schema_id`, and
`_block_type_id` are reserved by Prefect as Block metadata fields, but
otherwise a Block can implement arbitrary logic. Blocks can be instantiated
without populating these metadata fields, but can only be used interactively,
not with the Prefect API.

Instead of the __init__ method, a block implementation allows the
definition of a `block_initialization` method that is called after
initialization.


**Methods:**

#### `aload` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1024" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `aload`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `aload`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**
- `name`: The name or slug of the block document. A block document slug is a
string with the format `<block_type_slug>/<block_document_name>`
- `validate`: If False, the block document will be loaded without Pydantic
validating the block schema. This is useful if the block schema has
changed client-side since the block document referred to by `name` was saved.
- `client`: The client to use to load the block document. If not provided, the
default client will be injected.

**Raises:**
- `ValueError`: If the requested block document is not found.

**Returns:**
- An instance of the current class hydrated with the data stored in the
- block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:
```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Custom.aload("my-custom-message")
```

Load from Block with a block document slug:
```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = await Block.aload("custom/my-custom-message")
```

Migrate a block document to a new schema:
```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = await Custom.aload("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```


#### `annotation_refers_to_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1339" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
annotation_refers_to_block_class(annotation: Any) -> bool
```

#### `block_initialization` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
block_initialization(self) -> None
```

#### `delete` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1569" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
delete(cls, name: str, client: Optional['PrefectClient'] = None)
```

#### `get_block_capabilities` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L469" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_capabilities(cls) -> FrozenSet[str]
```

Returns the block capabilities for this Block. Recursively collects all block
capabilities of all parent classes into a single frozenset.


#### `get_block_class_from_key` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L894" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_key(cls: type[Self], key: str) -> type[Self]
```

Retrieve the block class implementation given a key.


#### `get_block_class_from_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L887" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```

Retrieve the block class implementation given a schema.


#### `get_block_placeholder` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1580" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_placeholder(self) -> str
```

Returns the block placeholder for the current block which can be used for
templating.

**Returns:**
- The block placeholder for the current block in the format
`prefect.blocks.{block_type_name}.{block_document_name}`

**Raises:**
- `BlockNotSavedError`: Raised if the block has not been saved.

If a block has not been saved, the return value will be `None`.


#### `get_block_schema_version` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L499" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_schema_version(cls) -> str
```

#### `get_block_type_name` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L461" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_name(cls) -> str
```

#### `get_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L465" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_block_type_slug(cls) -> str
```

#### `get_code_example` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L742" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_code_example(cls) -> Optional[str]
```

Returns the code example for the given block. Attempts to parse
code example from the class docstring if an override is not provided.


#### `get_description` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L719" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_description(cls) -> Optional[str]
```

Returns the description for the current block. Attempts to parse
description from class docstring if an override is not defined.


#### `is_block_class` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1335" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
is_block_class(block: Any) -> TypeGuard[type['Block']]
```

#### `load` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1113" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
```

Retrieves data from the block document with the given name for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**
- `name`: The name or slug of the block document. A block document slug is a
string with the format `<block_type_slug>/<block_document_name>`
- `validate`: If False, the block document will be loaded without Pydantic
validating the block schema. This is useful if the block schema has
changed client-side since the block document referred to by `name` was saved.
- `client`: The client to use to load the block document. If not provided, the
default client will be injected.

**Raises:**
- `ValueError`: If the requested block document is not found.

**Returns:**
- An instance of the current class hydrated with the data stored in the
- block document with the specified name.

**Examples:**

Load from a Block subclass with a block document name:
```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Custom.load("my-custom-message")
```

Load from Block with a block document slug:
```python
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

loaded_block = Block.load("custom/my-custom-message")
```

Migrate a block document to a new schema:
```python
# original class
class Custom(Block):
    message: str

Custom(message="Hello!").save("my-custom-message")

# Updated class with new required field
class Custom(Block):
    message: str
    number_of_ducks: int

loaded_block = Custom.load("my-custom-message", validate=False)

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

loaded_block.save("my-custom-message", overwrite=True)
```


#### `load_from_ref` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1212" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```

Retrieves data from the block document by given reference for the block type
that corresponds with the current class and returns an instantiated version of
the current class with the data stored in the block document.

Provided reference can be a block document ID, or a reference data in dictionary format.
Supported dictionary reference formats are:
- `{"block_document_id": <block_document_id>}`
- `{"block_document_slug": <block_document_slug>}`

If a block document for a given block type is saved with a different schema
than the current class calling `load`, a warning will be raised.

If the current class schema is a subset of the block document schema, the block
can be loaded as normal using the default `validate = True`.

If the current class schema is a superset of the block document schema, `load`
must be called with `validate` set to False to prevent a validation error. In
this case, the block attributes will default to `None` and must be set manually
and saved to a new block document before the block can be used as expected.

**Args:**
- `ref`: The reference to the block document. This can be a block document ID,
or one of supported dictionary reference formats.
- `validate`: If False, the block document will be loaded without Pydantic
validating the block schema. This is useful if the block schema has
changed client-side since the block document referred to by `name` was saved.
- `client`: The client to use to load the block document. If not provided, the
default client will be injected.

**Raises:**
- `ValueError`: If invalid reference format is provided.
- `ValueError`: If the requested block document is not found.

**Returns:**
- An instance of the current class hydrated with the data stored in the
- block document with the specified name.


#### `model_dump` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1648" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_dump(self) -> dict[str, Any]
```

#### `model_json_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1603" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_json_schema(cls, by_alias: bool = True, ref_template: str = '#/definitions/{model}', schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema, mode: Literal['validation', 'serialization'] = 'validation') -> dict[str, Any]
```

TODO\: stop overriding this method - use GenerateSchema in ConfigDict instead?


#### `model_validate` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1623" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```

#### `register_type_and_schema` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1353" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
```

Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.

**Args:**
- `client`: Optional client to use for registering type and schema with the
Prefect API. A new client will be created and used if one is not
provided.


#### `save` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L1546" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
```

Saves the values of a block as a block document.

**Args:**
- `name`: User specified name to give saved block document which can later be used to load the
block document.
- `overwrite`: Boolean value specifying if values should be overwritten if a block document with
the specified name already exists.


#### `ser_model` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L423" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```

#### `validate_block_type_slug` <sup><a href="https://github.com/PrefectHQ/prefect/blob/main/src/prefect/blocks/core.py#L364" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
validate_block_type_slug(cls, values: Any) -> Any
```

Validates that the `block_type_slug` in the input values matches the expected
block type slug for the class. This helps pydantic to correctly discriminate
between different Block subclasses when validating Union types of Blocks.

