Registry / serialization / maison

maison

JSON →
library2.0.2pypypi✓ verified 23d ago

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.

pip install maison
INSTALL
IMPORT
SIG · MAISON
M
maison
serializationpythonv2.0.2
Install
3.1s avg
Import
52ms
Disk
31MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.054s · 32.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.1s · import 0.050s · 33MB
31MB installed
● package 31MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

UserConfig
from maison import UserConfig
from maison import Config

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)
Debug
Known issues
breakingThe `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.
affects: >=2.0.0
breakingThe `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")`.
affects: >=2.0.0
gotchaMaison 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.
affects: all
gotchaIf `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.
affects: all
Upgrade
Version history
2.0.2latest on PyPI · released Oct 9, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
Amazon
1
Resources
maison — pip install maison · libregistry