ecological 2.0.0

Getting Started

Ecological automatically gets and converts environment variables according to the configuration class definition.

For example, imagine your application has a configurable (integer) Port and (boolean) Debug flag and a (string) Log Level, that is INFO by default, you could simply declare your configuration as:

class Configuration(ecological.Config):
    port: int
    debug: bool
    log_level: str = "INFO"

And then set the environment variables PORT, DEBUG and LOG_LEVEL. Ecological will automatically set the class properties from the environment variables with the same (but upper cased) name.

By default the values are set at the class definition type and assigned to the class itself (i.e. the class doesn’t need to be instantiated). If needed this behavior can be changed (see the Autoloading section).

Typing Support

Ecological also supports some of the types defined in PEP484, for example:

class Configuration(ecological.Config):
    list_of_values: List[str]

Will automatically parse the environment variable value as a list.

Prefixed Configuration

You can also decide to prefix your application configuration, for example, to avoid collisions:

class Configuration(ecological.Config, prefix='myapp'):
    home: str

In this case the home property will be fetched from the MYAPP_HOME environment property.

Nested Configuration

Ecological.Config also supports nested configurations, for example:

class Configuration(ecological.Config):
    integer: int

    class Nested(ecological.Config, prefix='nested'):
        boolean: bool

This way you can group related configuration properties hierarchically.

Advanced

my_source = {"KEY1": "VALUE1"}

class Configuration(ecological.Config, transform=lambda v, wt: v, wanted_type=int, ...):
    my_var1: WantedType = ecological.Variable(transform=lambda v, wt: wt(v), source=my_source, ...)
    my_var2: str
    # ...

class Configuration(ecological.Config):
    port: int
# Values already read and set at this point.
# assert Configuration.port == <value-of-PORT-env-var>

class Configuration(ecological.Config, autoload=ecological.Autoload.NEVER):
    port: int
# Values not set at this point.
# Accessing Configuration.port would throw AttributeError.

Configuration.load()
# Values read and set at this point.
# assert Configuration.port == <value-of-PORT-env-var>

class Configuration(ecological.Config, autoload=ecological.Autoload.OBJECT):
    port: int
# Values not set at this point.

config = Configuration()
# Values read and set at this point on ``config``.
# assert config.port == <value-of-PORT-env-var>
# Accessing ``Configuration.port`` would throw AttributeError.

Caveats and Known Limitations

• Ecological doesn’t support (public) methods in Config classes