kaifario 0.3.1

Configuration providing library

Kaifario

Kaifario is a lightweight and flexible configuration builder library for Python, inspired by the builder-style configuration system from C#. It allows you to compose multiple configuration sources (memory, environment variables, files, etc.) into a single, unified configuration object.

🔧 Installation

pip install kaifario

🚀 Quick Start

from kaifario.builder import ConfigurationBuilder
from kaifario.providers.memory import MemoryProvider

config = ConfigurationBuilder().add_providers(
    MemoryProvider({"a": 1, "b": 2})
).build()

print(config.get_value("a", int))  # Output: 1

📦 Available Providers

Kaifario supports various configuration sources:

• MemoryProvider — Load configuration from a Python dictionary.

• EnviromentProvider — Load values from environment variables, with support for nested configuration structures using a prefix and separator. Environment variable keys are lowercased and split by the given separator (default is "__") to create nested dictionaries. For example:

  export APP_DATABASE__HOST=localhost
  export APP_DATABASE__PORT=5432
  

  With EnviromentProvider(prefix="APP_"), this would produce:

  {
      "database": {
          "host": "localhost",
          "port": "5432"
      }
  }
  

• IniProvider — Load from .ini files.

• JsonProvider — Load from JSON files.

• TomlProvider — Load from TOML files.

• YamlProvider — Load from YAML files.

Provider Merge Order

When using multiple providers, their configurations are merged into a single dictionary. Later providers override the values from earlier ones if keys conflict. This allows flexible layering of configuration sources, such as defaults overridden by environment variables.

Example with multiple providers

from kaifario.builder import ConfigurationBuilder
from kaifario.providers.env import EnviromentProvider
from kaifario.providers.json import JsonProvider
from kaifario.providers.memory import MemoryProvider

config = ConfigurationBuilder() \
    .add_providers(
        EnviromentProvider(prefix="APP"),
        JsonProvider("config.json"),
        MemoryProvider({"fallback": "value"})
    ) \
    .build()

print(config["database"].get_value("host", str))
# or config.get_section("database").get_value("host", str)

🧹 Custom Providers

You can define your own provider by implementing the ConfigurationProvider protocol:

from typing import Protocol, Any

class ConfigurationProvider(Protocol):
    def load(self) -> dict[str, Any]:
        ...

Example

class CustomProvider:
    def load(self) -> dict[str, Any]:
        return {"custom_key": "custom_value"}

Then use it just like any other provider:

config = ConfigurationBuilder().add_providers(CustomProvider()).build()
print(config.get_value("custom_key", str))

📊 Dataclass Mapping

Kaifario supports direct mapping of configuration data to Python dataclasses. Under the hood, it uses Retort, but you can also provide your own loader by implementing a custom Loader.

Usage Example

from dataclasses import dataclass

@dataclass
class DatabaseConfig:
    host: str
    port: int

config = ConfigurationBuilder().add_providers(...).build() # inner config data should contain {"host": ..., "port": ...}
db_config = config.get(DatabaseConfig)

# with nested data like {"database": {"host": ..., "port": ...}} you can use:
db_config = config['database'].get(DatabaseConfig)

Custom Loader Support

You can provide your own loader by implementing the following protocol:

class Loader(Protocol):
    def load(self, data: dict[str, Any], model: type[T]) -> T:
        ...

The Configuration class accepts an optional loader argument:

🤝 Contributing

Contributions, ideas, and bug reports are welcome! Feel free to open issues or submit pull requests.

📃 License

MIT License