Maison

2.0.2 · active · verified Sun Apr 12

Maison is a lightweight Python library designed to simplify reading settings from various configuration files (TOML, YAML, JSON). It automatically searches common system and user locations for configuration, providing a unified access interface. Current version is 2.0.2, with a moderate release cadence, focusing on stability and ease of use.

Warnings

breaking The `Config.default` method was removed in version 2.0.0. It was previously used to retrieve a setting with a fallback value.
Fix: Use the `Config.get(key, default_value)` method instead, which provides the same functionality.
breaking The `Config` class initializer's `project_name` argument was renamed to `name` in version 2.0.0. This argument specifies the base name for configuration files.
Fix: Update your `Config` initialization from `Config(project_name="my_app")` to `Config(name="my_app")`.
gotcha Maison searches for configuration files in a predefined order (script directory, current working directory, XDG config dir, /etc/). If multiple files with the same name exist in these locations, the one found first will be loaded, which might lead to unexpected settings being used.
Fix: Be explicit about your configuration file's location or name if you want to avoid ambiguity. You can use the `config_file` or `config_dir` arguments in the `Config` initializer to specify exact paths.
gotcha If `maison` does not find any configuration file for the given `name` in its search paths, the `Config` object will be initialized but will contain no settings. Accessing keys will return `None` (or your provided default) without raising an error.
Fix: Always provide default values when calling `config.get('key', default_value)` for critical settings to ensure your application behaves predictably even if no configuration is found.

Install

pip install maison Install stable version

Imports

Config
```
from maison import Config
```

Quickstart

This quickstart demonstrates how to create a simple TOML configuration file and load its settings using `maison.Config`. It shows accessing nested keys with dot notation and providing default values for missing keys.

import os
from maison import Config

# Create a temporary config file for the example
app_name = "my_app_quickstart"
config_file_name = f"{app_name}.toml"
config_content = """
[general]
api_key = "sk_example_123"
debug_mode = true
environment = "development"

[database]
host = "localhost"
port = 5432
username = "admin"
"""

# Place the config file in the current working directory
# where maison will look for it by default for the given name.
with open(config_file_name, "w") as f:
    f.write(config_content)

# Initialize Config. It will look for '{app_name}.toml' in common locations.
# Since we created it in CWD, it will find it.
config = Config(name=app_name)

print(f"--- Settings for '{app_name}' ---")
print(f"API Key: {config.get('general.api_key', 'N/A')}")
print(f"Debug Mode: {config.get('general.debug_mode', False)}")
print(f"Environment: {config.get('general.environment', 'production')}")
print(f"Database Host: {config.get('database.host', '127.0.0.1')}")
print(f"Database Port: {config.get('database.port', 3306)}")
print(f"Non-existent setting (with default): {config.get('general.timeout', 30)}")
print(f"Non-existent setting (no default): {config.get('general.unknown')}")

# Clean up the created config file
os.remove(config_file_name)

view raw JSON →