Configurator - py-bc-configs 0.3.0 documentation

Skip to content
Back to top
View this page

# Configurator

## About

Module with BaseConfig. That config is the main element of bc_configs. It provides to receive values from the environment variables on the validation step of pydantic model. For use, create child class of BaseConfig and declare needed fields with typehint.

    class MyConfig(BaseConfig):
        my_field: str

    my_config = MyConfig()  # type: ignore[call-arg]

Note

my_config.my_field will contain the value of the environment variable MY_MY_FIELD.

### Building the environment variable name

- First part of the environment variable name is the class name in SCREAMING_SNAKE_CASE without the Config suffix.

- Second part of the environment variable name is the field name in SCREAMING_SNAKE_CASE.

Note

If class name is FooBarConfig and field name is del_bar then the environment variable name will be FOO_BAR_DEL_BAR.

### Customizing the environment variable name

If you want to customize the environment variable name, you can define it in field→json_schema_extra→env_name.

    from pydantic import Field

    class FooConfig(BaseConfig):
        bar: str = Field(json_schema_extra={"env_name": "CUSTOM_ENV_NAME"})

### Casting the environment variable value

If you want to cast the environment variable value, you can define field typehint.

    class FooConfig(BaseConfig):
        bar: str
        baz: int
        foo: bool

    foo_config = FooConfig()

    assert isinstance(foo_config.bar, str)  # True
    assert isinstance(foo_config.baz, int)  # True
    assert isinstance(foo_config.foo, bool)  # True

### Optional fields

If you want to make the field optional, you can define field typehint with | None.

    import os

    class FooConfig(BaseConfig):
        bar: str | None

    foo_config = FooConfig()

    assert os.getenv("FOO_BAR") is None  # True
    assert foo_config.bar is None  # True

Warning

By default, all fields are required. If the environment variable is missing an exception will follow.

### Default values

If you want to define default values for the fields, you can define Field with default value argument.

    import os
    from pydantic import Field

    class FooConfig(BaseConfig):
        bar: str = Field(default="default value")

    assert os.getenv("FOO_BAR") is None  # True
    assert foo_config.bar == "default value"  # True

pydantic model bc_configs.configurator.BaseConfig

  Bases: `BaseModel`, `ABC`

  Provides to receive values from the environment variables on the validation step of pydantic model.

  When a required field is missing, the error message will include the environment variable name that should be set, making it easier to debug configuration issues.

  Example:

      class MyConfig(BaseConfig):
          db_host: str
          db_port: int

      # If MY_DB_HOST or MY_DB_PORT are not set, the error will show:
      # db_host: Field required  →  env var: 'MY_DB_HOST'
      # db_port: Field required  →  env var: 'MY_DB_PORT'

  Show JSON schema

      {
         "title": "BaseConfig",
         "description": "Provides to receive values from the environment variables on the validation step of\npydantic model.\n\nWhen a required field is missing, the error message will include the environment\nvariable name that should be set, making it easier to debug configuration issues.\n\nExample:\n\n.. code:: python\n\n    class MyConfig(BaseConfig):\n        db_host: str\n        db_port: int\n\n    # If MY_DB_HOST or MY_DB_PORT are not set, the error will show:\n    # db_host: Field required  \u2192  env var: 'MY_DB_HOST'\n    # db_port: Field required  \u2192  env var: 'MY_DB_PORT'",
         "type": "object",
         "properties": {}
      }

  Validators:

    - `_enrich_errors` » `all fields`

    - `_populate_from_env` » `all fields`

## BaseConfig

Provides to receive values from the environment variables on the validation step of pydantic model.

When a required field is missing, the error message will include the environment variable name that should be set, making it easier to debug configuration issues.

Example:

    class MyConfig(BaseConfig):
        db_host: str
        db_port: int

    # If MY_DB_HOST or MY_DB_PORT are not set, the error will show:
    # db_host: Field required  →  env var: 'MY_DB_HOST'
    # db_port: Field required  →  env var: 'MY_DB_PORT'