ConfigBuilder

Configuration builder pattern for Confii.

This module provides a fluent builder interface for creating Config instances, making it easier to configure complex setup scenarios with better readability.

class confii.config_builder.ConfigBuilder[source]

Bases: object

Fluent builder for creating Config instances.

This class provides a builder pattern for constructing Config instances with better readability and easier configuration management.

Example

>>> builder = ConfigBuilder()
>>> config = builder         ...     .with_env("production")         ...     .add_loader(YamlLoader("base.yaml"))         ...     .add_loader(YamlLoader("production.yaml"))         ...     .with_secrets(secret_resolver)         ...     .enable_debug()         ...     .enable_dynamic_reloading()         ...     .build()

__init__() → None[source]: Initialize a new ConfigBuilder with default values.

add_loader(loader: Loader) → ConfigBuilder[source]

Add a configuration loader.

Parameters:: loader – Configuration loader instance to add (e.g., YamlLoader, JsonLoader)
Returns:: Self for method chaining

Example

>>> builder.add_loader(YamlLoader("config.yaml"))

add_loaders(loaders: List[Loader]) → ConfigBuilder[source]

Add multiple configuration loaders at once.

Parameters:: loaders – List of Loader instances to add
Returns:: Self for method chaining

Example

>>> builder.add_loaders(
...     [
...         YamlLoader("base.yaml"),
...         JsonLoader("overrides.json"),
...     ]
... )

build() → Config[source]

Build and return the Config instance.

Returns:: Configured Config instance
Raises:: ConfiiError – If configuration is invalid

Example

>>> config = builder.build()

classmethod create() → ConfigBuilder[source]

Create a new ConfigBuilder instance.

This is a convenience method for creating a builder. You can also use ConfigBuilder() directly.

Returns:: New ConfigBuilder instance

Example

>>> builder = ConfigBuilder.create()

disable_debug() → ConfigBuilder[source]

Disable debug mode.

Returns:: Self for method chaining

Example

>>> builder.disable_debug()

disable_deep_merge() → ConfigBuilder[source]

Disable deep merging (use shallow merge instead).

Returns:: Self for method chaining

Example

>>> builder.disable_deep_merge()

disable_dynamic_reloading() → ConfigBuilder[source]

Disable dynamic configuration reloading.

Returns:: Self for method chaining

Example

>>> builder.disable_dynamic_reloading()

disable_env_expander() → ConfigBuilder[source]

Disable environment variable expansion.

Returns:: Self for method chaining

Example

>>> builder.disable_env_expander()

disable_ide_support() → ConfigBuilder[source]

Disable IDE support generation.

Returns:: Self for method chaining

Example

>>> builder.disable_ide_support()

disable_type_casting() → ConfigBuilder[source]

Disable automatic type casting.

Returns:: Self for method chaining

Example

>>> builder.disable_type_casting()

disable_validation() → ConfigBuilder[source]

Disable validation on load.

Returns:: Self for method chaining

Example

>>> builder.disable_validation()

enable_debug() → ConfigBuilder[source]

Enable debug mode (detailed source tracking).

Returns:: Self for method chaining

Example

>>> builder.enable_debug()

enable_deep_merge() → ConfigBuilder[source]

Enable deep merging of nested configurations.

Returns:: Self for method chaining

Example

>>> builder.enable_deep_merge()

enable_dynamic_reloading() → ConfigBuilder[source]

Enable dynamic configuration reloading (file watching).

Returns:: Self for method chaining

Example

>>> builder.enable_dynamic_reloading()

enable_env_expander() → ConfigBuilder[source]

Enable environment variable expansion in config values.

Returns:: Self for method chaining

Example

>>> builder.enable_env_expander()

enable_ide_support(stub_path: str | None = None) → ConfigBuilder[source]

Enable IDE support (type stub generation).

Parameters:: stub_path – Optional custom path for IDE stub file
Returns:: Self for method chaining

Example

>>> builder.enable_ide_support(".confii/stubs.pyi")

enable_type_casting() → ConfigBuilder[source]

Enable automatic type casting of config values.

Returns:: Self for method chaining

Example

>>> builder.enable_type_casting()

enable_validation(strict: bool = False) → ConfigBuilder[source]

Enable validation using the configured schema.

Parameters:: strict – If True, raise ConfigValidationError on failure (default: False)
Returns:: Self for method chaining

Example

>>> builder.enable_validation(strict=True)

with_env(env: str) → ConfigBuilder[source]

Set the environment name.

Parameters:: env – Environment name (e.g., ‘development’, ‘production’, ‘staging’)
Returns:: Self for method chaining

Example

>>> builder.with_env("production")

with_schema(schema: Any, validate_on_load: bool = True, strict: bool = False) → ConfigBuilder[source]

Configure schema validation for configuration.

Parameters:

schema – Pydantic model class or JSON Schema dictionary
validate_on_load – If True, validate immediately after loading (default: True)
strict – If True, raise ConfigValidationError on failure (default: False)

Returns:

Self for method chaining

Example

>>> from pydantic import BaseModel
>>> class AppConfig(BaseModel):
...     database_url: str
>>> builder.with_schema(AppConfig, validate_on_load=True)

with_secrets(secret_resolver: SecretResolver) → ConfigBuilder[source]

Configure secret resolver for secret store integration.

Parameters:: secret_resolver – SecretResolver instance for resolving secrets
Returns:: Self for method chaining

Example

>>> from confii.secret_stores import AWSSecretsManager, SecretResolver
>>> store = AWSSecretsManager(region_name="us-east-1")
>>> builder.with_secrets(SecretResolver(store))

confii.config_builder.builder() → ConfigBuilder[source]

Create a new ConfigBuilder instance.

This is a convenience function for creating a builder with a shorter syntax: builder().with_env(“prod”).build()

Returns:: New ConfigBuilder instance

Example

>>> from confii.config_builder import builder
>>> config = builder().with_env("prod").build()