lazr-config

3.1 · active · verified Fri Apr 17

lazr.config is a Python library for defining configuration schemas, processing configuration data from various sources (like files or command-line arguments), and validating that data against the defined schema. It ensures that applications receive well-formed and valid configurations, reducing runtime errors. The current version is 3.1, and it typically follows an as-needed release cadence driven by Launchpad's requirements.

Common errors

```
ImportError: No module named 'lazr.config' or ImportError: cannot import name 'ConfigurationSchema' from 'lazr.config'
```
cause The `lazr.config` package is not installed or is installed incorrectly for your Python environment.

fix Ensure `lazr.config` is installed: `pip install lazr.config`. If using virtual environments, ensure it's installed in the correct one.
```
lazr.config.ConfigError: invalid type for field 'my_field_name': expected <class 'int'>, got 'some_string_value'
```
cause A value provided in the configuration data does not match the type specified for that field in the `ConfigurationSchema`.

fix Review your `ConfigurationSchema` and the input configuration data. Ensure that values passed for each field are of the correct Python type (e.g., an actual integer for an `int` field, a boolean for a `bool` field).
```
AttributeError: 'Config' object has no attribute 'my_undeclared_field'
```
cause You are attempting to access a configuration parameter through the `Config` object that was not explicitly defined as a `Field` in the `ConfigurationSchema`.

fix Add `my_undeclared_field = Field(...)` to your `ConfigurationSchema` definition. All accessible configuration parameters must be part of the schema.
```
lazr.config.SchemaError: Required Field 'missing_field' has no default value and was not provided.
```
cause A `Field` was defined in the schema as required (i.e., no `default` value was given), but no value was provided for it in the input configuration data.

fix Either provide a value for the 'missing_field' in your input configuration, or add a `default` value to the `Field` definition in your `ConfigurationSchema` if it's not always required.

Warnings

breaking Python 2 support was officially dropped in lazr.config version 3.0. Projects still relying on Python 2 will need to use an older version (e.g., 2.x) or migrate to Python 3.
Fix: Upgrade your Python environment to 3.8 or newer. If Python 2 is required, use lazr.config<3.0 and be aware it is no longer maintained.
gotcha Field types in lazr.config schemas are strictly enforced. Providing a value that does not match the declared type (e.g., a string for an integer field) will result in a `ConfigError`.
Fix: Ensure that the data provided to the `Config` object, regardless of its source, strictly conforms to the types defined in the `ConfigurationSchema`.
gotcha Attempting to access a configuration field that was not defined in the `ConfigurationSchema` will raise an `AttributeError` on the `Config` instance, similar to accessing an undeclared attribute on a regular Python object.
Fix: All configuration parameters you intend to use must be explicitly declared as `Field`s within your `ConfigurationSchema`. If you need dynamic access, consider using `Config.get_raw_data()` to access the underlying dictionary.
gotcha The `Config` class constructor directly takes a dictionary for configuration data. For loading from external sources like configuration files (e.g., INI, YAML) or command-line arguments, you must use helper classes like `ConfigFile` or `CommandLineArgumentParser`.
Fix: For file-based configuration, use `ConfigFile(schema, config_file_path)` and then `config_object.config` or similar. For command-line, use `CommandLineArgumentParser(schema)` to parse arguments into a `Config` instance.

Install

pip install lazr.config Install `lazr.config`

Imports

ConfigurationSchema

from lazr.config import ConfigurationSchema

Field
```
from lazr.config import Field
```
Config
```
from lazr.config import Config
```
ConfigError
```
from lazr.config import ConfigError
```
CommandLineArgumentParser
```
from lazr.config import CommandLineArgumentParser
```
Used for parsing command-line arguments into a Config object.
ConfigFile
```
from lazr.config import ConfigFile
```
Used for loading configurations from files.

Quickstart

This quickstart demonstrates how to define a configuration schema using `ConfigurationSchema` and `Field`, and then create a validated `Config` instance from a Python dictionary. It also shows how type mismatches lead to `ConfigError`.

from lazr.config import ConfigurationSchema, Field, Config, ConfigError

# 1. Define a configuration schema
class MySchema(ConfigurationSchema):
    db_host = Field(str, default='localhost', doc="Database hostname")
    db_port = Field(int, default=5432, doc="Database port")
    debug_mode = Field(bool, default=False, doc="Enable debug logging")

# 2. Create a configuration instance from a dictionary
config_data = {
    'db_host': 'prod.database.com',
    'db_port': 5432,
    # 'debug_mode' is omitted, will use default
}

try:
    config = Config(MySchema, config_data)
    print(f"DB Host: {config.db_host}")
    print(f"DB Port: {config.db_port}")
    print(f"Debug Mode: {config.debug_mode}")

    # Accessing an unknown field raises an AttributeError
    # print(config.unknown_field)

except ConfigError as e:
    print(f"Configuration error: {e}")

# Example of an invalid configuration
invalid_config_data = {
    'db_port': 'not_a_number', # This will fail validation
}
try:
    invalid_config = Config(MySchema, invalid_config_data)
except ConfigError as e:
    print(f"Caught expected error for invalid config: {e}")

view raw JSON →