> ## 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. # system # `prefect.blocks.system` ## Classes ### `Secret` A block that represents a secret value. The value stored in this block will be obfuscated when this block is viewed or edited in the UI. **Attributes:** * `value`: A value that should be kept secret. **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` ```python theme={null} get(self) -> T | str ``` #### `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. #### `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. #### `validate_value` ```python theme={null} validate_value(cls, value: Union[T, SecretStr, PydanticSecret[T]]) -> Union[SecretStr, PydanticSecret[T]] ```