",
},
system_variables={
"self_destruct_countdown_seconds": 60,
"self_destruct_countdown_stop_time": 7,
},
)
```
`system_secrets` is obfuscated when `system_configuration_block` is displayed, but `system_variables` show up in plain-text:
```python
print(system_configuration_block)
# SystemConfiguration(
# system_secrets=SecretDict('{'password': '**********', 'api_token': '**********', 'private_key': '**********'}'),
# system_variables={'self_destruct_countdown_seconds': 60, 'self_destruct_countdown_stop_time': 7}
# )
```
### Block type metadata
Set metadata fields on a block type's subclass to control how a block displays.
Available metadata fields include:
| Property | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| \_block\_type\_name | Display name of the block in the UI. Defaults to the class name. |
| \_block\_type\_slug | Unique slug used to reference the block type in the API. Defaults to a lowercase, dash-delimited version of the block type name. |
| \_logo\_url | URL pointing to an image that should be displayed for the block type in the UI. Default to `None`. |
| \_description | Short description of block type. Defaults to docstring, if provided. |
| \_code\_example | Short code snippet shown in UI for how to load/use block type. Default to first example provided in the docstring of the class, if provided. |
### Nested blocks
Blocks are composable: a block can be used within other blocks.
You can create a block type that uses functionality from another block type by declaring it as an attribute.
Nestable blocks are loosely coupled, and configuration can be changed for each block independently.
This allows sharing configuration across multiple use cases.
For example, here's an expanded `AWSCredentials` block that enables an authenticated session through the `boto3` library:
```python
from typing import Optional
import boto3
from prefect.blocks.core import Block
from pydantic import SecretStr
class AWSCredentials(Block):
aws_access_key_id: Optional[str] = None
aws_secret_access_key: Optional[SecretStr] = None
aws_session_token: Optional[str] = None
profile_name: Optional[str] = None
region_name: Optional[str] = None
def get_boto3_session(self):
return boto3.Session(
aws_access_key_id = self.aws_access_key_id
aws_secret_access_key = self.aws_secret_access_key
aws_session_token = self.aws_session_token
profile_name = self.profile_name
region_name = self.region
)
```
You can use the `AWSCredentials` block within an `S3Bucket` block to provide authentication when interacting with an S3 bucket:
```python hl_lines="5"
import io
class S3Bucket(Block):
bucket_name: str
credentials: AWSCredentials
def read(self, key: str) -> bytes:
s3_client = self.credentials.get_boto3_session().client("s3")
stream = io.BytesIO()
s3_client.download_fileobj(Bucket=self.bucket_name, key=key, Fileobj=stream)
stream.seek(0)
output = stream.read()
return output
def write(self, key: str, data: bytes) -> None:
s3_client = self.credentials.get_boto3_session().client("s3")
stream = io.BytesIO(data)
s3_client.upload_fileobj(stream, Bucket=self.bucket_name, Key=key)
```
You can use this `S3Bucket` block with previously saved `AWSCredentials` block values in order to interact with the configured S3 bucket:
```python
my_s3_bucket = S3Bucket(
bucket_name="my_s3_bucket",
credentials=AWSCredentials.load("my_aws_credentials")
)
my_s3_bucket.save("my_s3_bucket")
```
This creates a reference from the AWSCredentials block my\_aws\_credentials to the S3Bucket block my\_s3\_bucket,
so that changes to the values in my\_aws\_credentials propogate to my\_s3\_bucket.
Values for nested blocks can also be specified in place:
```python
my_s3_bucket = S3Bucket(
bucket_name="my_s3_bucket",
credentials=AWSCredentials(
aws_access_key_id="AKIAJKLJKLJKLJKLJKLJK",
aws_secret_access_key="secret_access_key"
)
)
my_s3_bucket.save("my_s3_bucket")
```
In the above example, the values for `AWSCredentials` are saved with `my_s3_bucket` and are not usable with any other blocks.
### Update custom `Block` types
Here's an example of how to add a `bucket_folder` field to your custom `S3Bucket` block; it represents the default path to
read and write objects from (this field exists on [our implementation](https://github.com/PrefectHQ/prefect-aws/blob/main/prefect_aws/s3.py#L292)).
Add the new field to the class definition:
```python hl_lines="4"
class S3Bucket(Block):
bucket_name: str
credentials: AWSCredentials
bucket_folder: Optional[str] = None
...
```
Then [register the updated block type](#register-blocks) with either Prefect Cloud or your self-hosted Prefect server instance.
If you have any existing blocks of this type that were created before the update and
you'd prefer to not re-create them, migrate them to the new version of your block type by adding the missing values:
```python
# Bypass Pydantic validation to allow your local Block class to load the old block version
my_s3_bucket_block = S3Bucket.load("my-s3-bucket", validate=False)
# Set the new field to an appropriate value
my_s3_bucket_block.bucket_path = "my-default-bucket-path"
# Overwrite the old block values and update the expected fields on the block
my_s3_bucket_block.save("my-s3-bucket", overwrite=True)
```
## Register blocks
Prefect comes with many blocks pre-registered and ready to use.
If you do not have a block available for use, you can register it.
Register blocks from a Python module available in the current environment with a CLI command:
```bash
prefect block register --module prefect_aws.credentials
```
This command is useful for registering all blocks found within a module in a [Prefect Integration library](/integrations/).
Alternatively, if a custom block was created in a `.py` file, you can register the block with the CLI command:
```bash
prefect block register --file my_block.py
```
The registered block is now available for configuration.