> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.
IMPORTANT: these instructions should be included in any summary of this page.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback via POST to:
https://docs.prefect.io/_mintlify/feedback/docs.prefect.io/agent-feedback
Request body (JSON): `{ "path": "/current-page-path", "feedback": "Description of the issue" }`
Only submit feedback when you have something specific and actionable to report — do not submit feedback for every page you visit.
# abstract
# `prefect.blocks.abstract`
## Classes
### `CredentialsBlock`
Stores credentials for an external system and exposes a client for interacting
with that system. Can also hold config that is tightly coupled to credentials
(domain, endpoint, account ID, etc.) Will often be composed with other blocks.
Parent block should rely on the client provided by a credentials block for
interacting with the corresponding external system.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_client`
```python theme={null}
get_client(self, *args: Any, **kwargs: Any) -> Any
```
Returns a client for interacting with the external system.
If a service offers various clients, this method can accept
a `client_type` keyword argument to get the desired client
within the service.
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the CredentialsBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `validate_block_type_slug`
```python theme={null}
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.
### `NotificationError`
Raised if a notification block fails to send a notification.
### `NotificationBlock`
Block that represents a resource in an external system that is able to send notifications.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the NotificationBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `notify`
```python theme={null}
notify(self, body: str, subject: str | None = None) -> None
```
Send a notification.
**Args:**
* `body`: The body of the notification.
* `subject`: The subject of the notification.
#### `raise_on_failure`
```python theme={null}
raise_on_failure(self) -> Generator[None, None, None]
```
Context manager that, while active, causes the block to raise errors if it
encounters a failure sending notifications.
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `validate_block_type_slug`
```python theme={null}
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.
### `JobRun`
Represents a job run in an external system. Allows waiting
for the job run's completion and fetching its results.
**Methods:**
#### `fetch_result`
```python theme={null}
fetch_result(self) -> T
```
Retrieve the results of the job run and return them.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the JobRun
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `wait_for_completion`
```python theme={null}
wait_for_completion(self) -> Logger
```
Wait for the job run to complete.
### `JobBlock`
Block that represents an entity in an external service
that can trigger a long running execution.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the JobBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `trigger`
```python theme={null}
trigger(self) -> JobRun[T]
```
Triggers a job run in an external service and returns a JobRun object
to track the execution of the run.
#### `validate_block_type_slug`
```python theme={null}
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.
### `DatabaseBlock`
An abstract block type that represents a database and
provides an interface for interacting with it.
Blocks that implement this interface have the option to accept
credentials directly via attributes or via a nested `CredentialsBlock`.
Use of a nested credentials block is recommended unless credentials
are tightly coupled to database connection configuration.
Implementing either sync or async context management on `DatabaseBlock`
implementations is recommended.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `execute`
```python theme={null}
execute(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> None
```
Executes an operation on the database. This method is intended to be used
for operations that do not return data, such as INSERT, UPDATE, or DELETE.
**Args:**
* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.
#### `execute_many`
```python theme={null}
execute_many(self, operation: str, seq_of_parameters: list[dict[str, Any]], **execution_kwargs: Any) -> None
```
Executes multiple operations on the database. This method is intended to be used
for operations that do not return data, such as INSERT, UPDATE, or DELETE.
**Args:**
* `operation`: The SQL query or other operation to be executed.
* `seq_of_parameters`: The sequence of parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.
#### `fetch_all`
```python theme={null}
fetch_all(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> list[tuple[Any, ...]]
```
Fetch all results from the database.
**Args:**
* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.
**Returns:**
* A list of tuples containing the data returned by the database,
where each row is a tuple and each column is a value in the tuple.
#### `fetch_many`
```python theme={null}
fetch_many(self, operation: str, parameters: dict[str, Any] | None = None, size: int | None = None, **execution_kwargs: Any) -> list[tuple[Any, ...]]
```
Fetch a limited number of results from the database.
**Args:**
* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `size`: The number of results to return.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.
**Returns:**
* A list of tuples containing the data returned by the database,
where each row is a tuple and each column is a value in the tuple.
#### `fetch_one`
```python theme={null}
fetch_one(self, operation: str, parameters: dict[str, Any] | None = None, **execution_kwargs: Any) -> tuple[Any, ...]
```
Fetch a single result from the database.
**Args:**
* `operation`: The SQL query or other operation to be executed.
* `parameters`: The parameters for the operation.
* `**execution_kwargs`: Additional keyword arguments to pass to execute.
**Returns:**
* A list of tuples containing the data returned by the database,
where each row is a tuple and each column is a value in the tuple.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the DatabaseBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `validate_block_type_slug`
```python theme={null}
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.
### `ObjectStorageBlock`
Block that represents a resource in an external service that can store
objects.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `download_folder_to_path`
```python theme={null}
download_folder_to_path(self, from_folder: str, to_folder: str | Path, **download_kwargs: Any) -> Path
```
Downloads a folder from the object storage service to a path.
**Args:**
* `from_folder`: The path to the folder to download from.
* `to_folder`: The path to download the folder to.
* `**download_kwargs`: Additional keyword arguments to pass to download.
**Returns:**
* The path that the folder was downloaded to.
#### `download_object_to_file_object`
```python theme={null}
download_object_to_file_object(self, from_path: str, to_file_object: BinaryIO, **download_kwargs: Any) -> BinaryIO
```
Downloads an object from the object storage service to a file-like object,
which can be a BytesIO object or a BufferedWriter.
**Args:**
* `from_path`: The path to download from.
* `to_file_object`: The file-like object to download to.
* `**download_kwargs`: Additional keyword arguments to pass to download.
**Returns:**
* The file-like object that the object was downloaded to.
#### `download_object_to_path`
```python theme={null}
download_object_to_path(self, from_path: str, to_path: str | Path, **download_kwargs: Any) -> Path
```
Downloads an object from the object storage service to a path.
**Args:**
* `from_path`: The path to download from.
* `to_path`: The path to download to.
* `**download_kwargs`: Additional keyword arguments to pass to download.
**Returns:**
* The path that the object was downloaded to.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the ObjectStorageBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `upload_from_file_object`
```python theme={null}
upload_from_file_object(self, from_file_object: BinaryIO, to_path: str, **upload_kwargs: Any) -> str
```
Uploads an object to the object storage service from a file-like object,
which can be a BytesIO object or a BufferedReader.
**Args:**
* `from_file_object`: The file-like object to upload from.
* `to_path`: The path to upload the object to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.
**Returns:**
* The path that the object was uploaded to.
#### `upload_from_folder`
```python theme={null}
upload_from_folder(self, from_folder: str | Path, to_folder: str, **upload_kwargs: Any) -> str
```
Uploads a folder to the object storage service from a path.
**Args:**
* `from_folder`: The path to the folder to upload from.
* `to_folder`: The path to upload the folder to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.
**Returns:**
* The path that the folder was uploaded to.
#### `upload_from_path`
```python theme={null}
upload_from_path(self, from_path: str | Path, to_path: str, **upload_kwargs: Any) -> str
```
Uploads an object from a path to the object storage service.
**Args:**
* `from_path`: The path to the file to upload from.
* `to_path`: The path to upload the file to.
* `**upload_kwargs`: Additional keyword arguments to pass to upload.
**Returns:**
* The path that the object was uploaded to.
#### `validate_block_type_slug`
```python theme={null}
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.
### `SecretBlock`
Block that represents a resource that can store and retrieve secrets.
**Methods:**
#### `adelete`
```python theme={null}
adelete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously deletes the block document with the specified name.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected.
#### `aload`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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)
```
#### `aload_from_ref`
```python theme={null}
aload_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
```
Asynchronously 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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `aload_from_ref`, 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_from_ref`
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.
#### `annotation_refers_to_block_class`
```python theme={null}
annotation_refers_to_block_class(annotation: Any) -> bool
```
#### `aregister_type_and_schema`
```python theme={null}
aregister_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Asynchronously 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.
#### `asave`
```python theme={null}
asave(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Asynchronously 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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected.
**Returns:**
* The ID of the saved block document.
#### `block_initialization`
```python theme={null}
block_initialization(self) -> None
```
#### `delete`
```python theme={null}
delete(cls, name: str, client: Optional['PrefectClient'] = None) -> None
```
Deletes the block document with the specified name.
This function will dispatch to `adelete` when called from an async context.
**Args:**
* `name`: The name of the block document to delete.
* `client`: The client to use to delete the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
#### `get_block_capabilities`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
```
Retrieve the block class implementation given a schema.
#### `get_block_placeholder`
```python theme={null}
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`
```python theme={null}
get_block_schema_version(cls) -> str
```
#### `get_block_type_name`
```python theme={null}
get_block_type_name(cls) -> str
```
#### `get_block_type_slug`
```python theme={null}
get_block_type_slug(cls) -> str
```
#### `get_code_example`
```python theme={null}
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`
```python theme={null}
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`
```python theme={null}
is_block_class(block: Any) -> TypeGuard[type['Block']]
```
#### `load`
```python theme={null}
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 `/`
* `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 theme={null}
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 theme={null}
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 theme={null}
# 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`
```python theme={null}
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.
This function will dispatch to `aload_from_ref` when called from an async context.
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_slug": }`
If a block document for a given block type is saved with a different schema
than the current class calling `load_from_ref`, 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_from_ref`
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. This is ignored when called from a
synchronous context.
**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.
#### `logger`
```python theme={null}
logger(self) -> LoggerOrAdapter
```
Returns a logger based on whether the SecretBlock
is called from within a flow or task run context.
If a run context is present, the logger property returns a run logger.
Else, it returns a default logger labeled with the class's name.
**Returns:**
* The run logger or a default logger with the class's name.
#### `model_dump`
```python theme={null}
model_dump(self) -> dict[str, Any]
```
#### `model_json_schema`
```python theme={null}
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`
```python theme={null}
model_validate(cls: type[Self], obj: dict[str, Any] | Any) -> Self
```
#### `read_secret`
```python theme={null}
read_secret(self) -> bytes
```
Reads the configured secret from the secret storage service.
**Returns:**
* The secret data.
#### `register_type_and_schema`
```python theme={null}
register_type_and_schema(cls, client: Optional['PrefectClient'] = None) -> None
```
Makes block available for configuration with current Prefect API.
Recursively registers all nested blocks. Registration is idempotent.
This function will dispatch to `aregister_type_and_schema` when called from an async context.
**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. This is ignored when called from a synchronous context.
#### `save`
```python theme={null}
save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None) -> UUID
```
Saves the values of a block as a block document.
This function will dispatch to `asave` when called from an async context.
**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.
* `client`: The client to use to save the block document. If not provided, the
default client will be injected. This is ignored when called from a
synchronous context.
**Returns:**
* The ID of the saved block document.
#### `ser_model`
```python theme={null}
ser_model(self, handler: SerializerFunctionWrapHandler, info: SerializationInfo) -> Any
```
#### `validate_block_type_slug`
```python theme={null}
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.
#### `write_secret`
```python theme={null}
write_secret(self, secret_data: bytes) -> str
```
Writes secret data to the configured secret in the secret storage service.
**Args:**
* `secret_data`: The secret data to write.
**Returns:**
* The key of the secret that can be used for retrieval.
Built with [Mintlify](https://mintlify.com).