prefect.filesystems

Classes

ReadableFileSystem

Methods:

aload

aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling aload, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, aload must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# original class
class Custom(Block):
    message: str

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

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

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

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

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

annotation_refers_to_block_class

annotation_refers_to_block_class(annotation: Any) -> bool

block_initialization

block_initialization(self) -> None

delete

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

get_block_capabilities

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

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

get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
Retrieve the block class implementation given a schema.

get_block_placeholder

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

get_block_schema_version(cls) -> str

get_block_type_name

get_block_type_name(cls) -> str

get_block_type_slug

get_block_type_slug(cls) -> str

get_code_example

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

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

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

load

load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# 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

load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
Retrieves data from the block document by given reference for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. Provided reference can be a block document ID, or a reference data in dictionary format. Supported dictionary reference formats are:
  • {"block_document_id": <block_document_id>}
  • {"block_document_slug": <block_document_slug>}
If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • ref: The reference to the block document. This can be a block document ID, or one of supported dictionary reference formats.
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If invalid reference format is provided.
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.

model_dump

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

model_json_schema

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

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

read_path

read_path(self, path: str) -> bytes

register_type_and_schema

register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent. Args:
  • client: Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.

save

save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
Saves the values of a block as a block document. Args:
  • name: User specified name to give saved block document which can later be used to load the block document.
  • overwrite: Boolean value specifying if values should be overwritten if a block document with the specified name already exists.

ser_model

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

WritableFileSystem

Methods:

aload

aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling aload, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, aload must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# original class
class Custom(Block):
    message: str

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

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

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

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

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

annotation_refers_to_block_class

annotation_refers_to_block_class(annotation: Any) -> bool

block_initialization

block_initialization(self) -> None

delete

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

get_block_capabilities

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

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

get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
Retrieve the block class implementation given a schema.

get_block_placeholder

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

get_block_schema_version(cls) -> str

get_block_type_name

get_block_type_name(cls) -> str

get_block_type_slug

get_block_type_slug(cls) -> str

get_code_example

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

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

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

load

load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# 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

load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
Retrieves data from the block document by given reference for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. Provided reference can be a block document ID, or a reference data in dictionary format. Supported dictionary reference formats are:
  • {"block_document_id": <block_document_id>}
  • {"block_document_slug": <block_document_slug>}
If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • ref: The reference to the block document. This can be a block document ID, or one of supported dictionary reference formats.
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If invalid reference format is provided.
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.

model_dump

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

model_json_schema

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

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

read_path

read_path(self, path: str) -> bytes

register_type_and_schema

register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent. Args:
  • client: Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.

save

save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
Saves the values of a block as a block document. Args:
  • name: User specified name to give saved block document which can later be used to load the block document.
  • overwrite: Boolean value specifying if values should be overwritten if a block document with the specified name already exists.

ser_model

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

write_path

write_path(self, path: str, content: bytes) -> None

ReadableDeploymentStorage

Methods:

aload

aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling aload, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, aload must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# original class
class Custom(Block):
    message: str

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

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

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

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

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

annotation_refers_to_block_class

annotation_refers_to_block_class(annotation: Any) -> bool

block_initialization

block_initialization(self) -> None

delete

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

get_block_capabilities

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

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

get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
Retrieve the block class implementation given a schema.

get_block_placeholder

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

get_block_schema_version(cls) -> str

get_block_type_name

get_block_type_name(cls) -> str

get_block_type_slug

get_block_type_slug(cls) -> str

get_code_example

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

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.

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

is_block_class

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

load

load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# 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

load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
Retrieves data from the block document by given reference for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. Provided reference can be a block document ID, or a reference data in dictionary format. Supported dictionary reference formats are:
  • {"block_document_id": <block_document_id>}
  • {"block_document_slug": <block_document_slug>}
If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • ref: The reference to the block document. This can be a block document ID, or one of supported dictionary reference formats.
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If invalid reference format is provided.
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.

model_dump

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

model_json_schema

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

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

register_type_and_schema

register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent. Args:
  • client: Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.

save

save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
Saves the values of a block as a block document. Args:
  • name: User specified name to give saved block document which can later be used to load the block document.
  • overwrite: Boolean value specifying if values should be overwritten if a block document with the specified name already exists.

ser_model

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

WritableDeploymentStorage

Methods:

aload

aload(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling aload, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, aload must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# original class
class Custom(Block):
    message: str

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

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

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

# Prints UserWarning about schema mismatch

loaded_block.number_of_ducks = 42

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

annotation_refers_to_block_class

annotation_refers_to_block_class(annotation: Any) -> bool

block_initialization

block_initialization(self) -> None

delete

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

get_block_capabilities

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

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

get_block_class_from_schema(cls: type[Self], schema: BlockSchema) -> type[Self]
Retrieve the block class implementation given a schema.

get_block_placeholder

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

get_block_schema_version(cls) -> str

get_block_type_name

get_block_type_name(cls) -> str

get_block_type_slug

get_block_type_slug(cls) -> str

get_code_example

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

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.

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

is_block_class

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

load

load(cls, name: str, validate: bool = True, client: Optional['PrefectClient'] = None) -> 'Self'
Retrieves data from the block document with the given name for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • name: The name or slug of the block document. A block document slug is a string with the format <block_type_slug>/<block_document_name>
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.
Examples: Load from a Block subclass with a block document name:
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:
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:
# 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

load_from_ref(cls, ref: Union[str, UUID, dict[str, Any]], validate: bool = True, client: 'PrefectClient | None' = None) -> Self
Retrieves data from the block document by given reference for the block type that corresponds with the current class and returns an instantiated version of the current class with the data stored in the block document. Provided reference can be a block document ID, or a reference data in dictionary format. Supported dictionary reference formats are:
  • {"block_document_id": <block_document_id>}
  • {"block_document_slug": <block_document_slug>}
If a block document for a given block type is saved with a different schema than the current class calling load, a warning will be raised. If the current class schema is a subset of the block document schema, the block can be loaded as normal using the default validate = True. If the current class schema is a superset of the block document schema, load must be called with validate set to False to prevent a validation error. In this case, the block attributes will default to None and must be set manually and saved to a new block document before the block can be used as expected. Args:
  • ref: The reference to the block document. This can be a block document ID, or one of supported dictionary reference formats.
  • validate: If False, the block document will be loaded without Pydantic validating the block schema. This is useful if the block schema has changed client-side since the block document referred to by name was saved.
  • client: The client to use to load the block document. If not provided, the default client will be injected.
Raises:
  • ValueError: If invalid reference format is provided.
  • ValueError: If the requested block document is not found.
Returns:
  • An instance of the current class hydrated with the data stored in the
  • block document with the specified name.

model_dump

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

model_json_schema

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

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

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None

register_type_and_schema

register_type_and_schema(cls, client: Optional['PrefectClient'] = None)
Makes block available for configuration with current Prefect API. Recursively registers all nested blocks. Registration is idempotent. Args:
  • client: Optional client to use for registering type and schema with the Prefect API. A new client will be created and used if one is not provided.

save

save(self, name: Optional[str] = None, overwrite: bool = False, client: Optional['PrefectClient'] = None)
Saves the values of a block as a block document. Args:
  • name: User specified name to give saved block document which can later be used to load the block document.
  • overwrite: Boolean value specifying if values should be overwritten if a block document with the specified name already exists.

ser_model

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

LocalFileSystem

Store data as a file on a local file system. Methods:

aget_directory

aget_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
Copies a directory from one place to another on the local filesystem. Defaults to copying the entire contents of the block’s basepath to the current working directory.

aput_directory

aput_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
Copies a directory from one place to another on the local filesystem. Defaults to copying the entire contents of the current working directory to the block’s basepath. An ignore_file path may be provided that can include gitignore style expressions for filepaths to ignore.

aread_path

aread_path(self, path: str) -> bytes

awrite_path

awrite_path(self, path: str, content: bytes) -> str

cast_pathlib

cast_pathlib(cls, value: str | Path | None) -> str | None

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
Copies a directory from one place to another on the local filesystem. Defaults to copying the entire contents of the block’s basepath to the current working directory.

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None
Copies a directory from one place to another on the local filesystem. Defaults to copying the entire contents of the current working directory to the block’s basepath. An ignore_file path may be provided that can include gitignore style expressions for filepaths to ignore.

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None

read_path

read_path(self, path: str) -> bytes

read_path

read_path(self, path: str) -> bytes

write_path

write_path(self, path: str, content: bytes) -> str

write_path

write_path(self, path: str, content: bytes) -> None

RemoteFileSystem

Store data as a file on a remote file system. Supports any remote file system supported by fsspec. The file system is specified using a protocol. For example, “s3://my-bucket/my-folder/” will use S3. Methods:

check_basepath

check_basepath(cls, value: str) -> str

filesystem

filesystem(self) -> fsspec.AbstractFileSystem

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None
Downloads a directory from a given remote path to a local directory. Defaults to downloading the entire contents of the block’s basepath to the current working directory.

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None, overwrite: bool = True) -> int
Uploads a directory from a given local path to a remote directory. Defaults to uploading the entire contents of the current working directory to the block’s basepath.

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None

read_path

read_path(self, path: str) -> bytes

read_path

read_path(self, path: str) -> bytes

write_path

write_path(self, path: str, content: bytes) -> str

write_path

write_path(self, path: str, content: bytes) -> None

SMB

Store data as a file on a SMB share. Methods:

basepath

basepath(self) -> str

filesystem

filesystem(self) -> RemoteFileSystem

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> bytes
Downloads a directory from a given remote path to a local directory. Defaults to downloading the entire contents of the block’s basepath to the current working directory.

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> int
Uploads a directory from a given local path to a remote directory. Defaults to uploading the entire contents of the current working directory to the block’s basepath.

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None

read_path

read_path(self, path: str) -> bytes

read_path

read_path(self, path: str) -> bytes

write_path

write_path(self, path: str, content: bytes) -> str

write_path

write_path(self, path: str, content: bytes) -> None

NullFileSystem

A file system that does not store any data. Methods:

get_directory

get_directory(self, from_path: Optional[str] = None, local_path: Optional[str] = None) -> None

put_directory

put_directory(self, local_path: Optional[str] = None, to_path: Optional[str] = None, ignore_file: Optional[str] = None) -> None

read_path

read_path(self, path: str) -> None

write_path

write_path(self, path: str, content: bytes) -> None