Envier

Common errors

• ModuleNotFoundError: No module named 'envier'

  cause The 'envier' library has not been installed in the Python environment where the code is being run.
  fix Install the 'envier' library using pip: `pip install envier`

• envier.errors.MissingValueError: Required environment variable 'YOUR_VARIABLE_NAME' is not set.

  cause A configuration field defined in an `envier` dataclass is marked as required (by default, or explicitly with `default=...` not present) but the corresponding environment variable is not found.
  fix Set the environment variable `YOUR_VARIABLE_NAME` in your shell or `.env` file before running the application, or provide a default value in your `envier` configuration class, e.g., `YOUR_VARIABLE_NAME: str = 'default_value'` or `YOUR_VARIABLE_NAME: str = field(default='default_value')`.

• envier.errors.InvalidTypeError: Environment variable 'YOUR_NUMBER_VARIABLE' ('abc') cannot be converted to <class 'int'>.

  cause The value of an environment variable cannot be converted to the Python type specified in the `envier` dataclass (e.g., 'abc' cannot be converted to an integer).
  fix Ensure the environment variable `YOUR_NUMBER_VARIABLE` contains a value that can be successfully converted to the declared type. For example, if it's an `int`, provide a string like '123' instead of 'abc'.

• AttributeError: 'Settings' object has no attribute 'missing_attribute'

  cause You are trying to access an attribute on your `envier` settings object that was not defined in its corresponding dataclass or is misspelled.
  fix Verify that the attribute `missing_attribute` is correctly defined in your `envier` dataclass (e.g., `class Settings(Env): missing_attribute: str`) and that you are using the correct casing and spelling when accessing it.

Warnings

• breaking The internal structure and exposure of `HelpInfo` was refactored. Code directly importing `HelpInfo` or relying on its previous class-based implementation might break.
  Fix: Review the usage of `HelpInfo` and adapt to its new `namedtuple` structure. Consult the latest documentation for correct access.
• breaking The Sphinx plugin for auto-generating environment variable documentation was removed. Users who relied on this feature will need to find an alternative documentation generation method.
  Fix: Migrate to a different documentation generation approach or manually maintain environment variable documentation.
• gotcha There have been multiple bug fixes (v0.6.1, v0.2.1, v0.2.0) related to the handling of `include` with `namespace` and prefixes for sub-configuration items. Users should thoroughly test configurations involving nested structures and custom prefixes, as these areas have historically shown inconsistencies.
  Fix: Upgrade to the latest version to benefit from bug fixes. Carefully review and test configurations involving nested structures and prefixes.
• gotcha A bug affecting the proper handling of `Optional` types in configuration variables was fixed in version 0.5.2.
  Fix: Ensure you are using `envier` version 0.5.2 or newer when defining configuration variables with `Optional[Type]`.

Install

• pip install envier Install stable version

Imports

• Env

  from envier import Env

Quickstart

This example demonstrates how to define a configuration class using `envier.Env`, specify environment variable mappings with `Env.var`, and handle prefixes for nested configurations. It sets temporary environment variables to ensure the example is runnable.

import os
from envier import Env

# Set environment variables for the example
os.environ['MYAPP_DEBUG'] = os.environ.get('MYAPP_DEBUG', 'True')
os.environ['MYAPP_SERVICE_HOST'] = os.environ.get('MYAPP_SERVICE_HOST', 'example.com')
os.environ['MYAPP_SERVICE_PORT'] = os.environ.get('MYAPP_SERVICE_PORT', '8080')

class GlobalConfig(Env):
    __prefix__ = "myapp"

    debug_mode = Env.var(bool, "debug", default=False)

    service_host = Env.var(str, "service.host", default="localhost")
    service_port = Env.var(int, "service.port", default=3000)

# Instantiate the configuration
config = GlobalConfig()

print(f"Debug Mode: {config.debug_mode}")
print(f"Service Host: {config.service_host}")
print(f"Service Port: {config.service_port}")

# Expected output if env vars are not set:
# Debug Mode: True
# Service Host: example.com
# Service Port: 8080

# Clean up environment variables (optional, but good for isolated testing)
del os.environ['MYAPP_DEBUG']
del os.environ['MYAPP_SERVICE_HOST']
del os.environ['MYAPP_SERVICE_PORT']