{"id":4371,"library":"maison","title":"Maison","description":"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.","status":"active","version":"2.0.2","language":"en","source_language":"en","source_url":"https://github.com/dbatten/maison","tags":["configuration","settings","config files","toml","yaml","json"],"install":[{"cmd":"pip install maison","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Config","correct":"from maison import Config"}],"quickstart":{"code":"import os\nfrom maison import Config\n\n# Create a temporary config file for the example\napp_name = \"my_app_quickstart\"\nconfig_file_name = f\"{app_name}.toml\"\nconfig_content = \"\"\"\n[general]\napi_key = \"sk_example_123\"\ndebug_mode = true\nenvironment = \"development\"\n\n[database]\nhost = \"localhost\"\nport = 5432\nusername = \"admin\"\n\"\"\"\n\n# Place the config file in the current working directory\n# where maison will look for it by default for the given name.\nwith open(config_file_name, \"w\") as f:\n    f.write(config_content)\n\n# Initialize Config. It will look for '{app_name}.toml' in common locations.\n# Since we created it in CWD, it will find it.\nconfig = Config(name=app_name)\n\nprint(f\"--- Settings for '{app_name}' ---\")\nprint(f\"API Key: {config.get('general.api_key', 'N/A')}\")\nprint(f\"Debug Mode: {config.get('general.debug_mode', False)}\")\nprint(f\"Environment: {config.get('general.environment', 'production')}\")\nprint(f\"Database Host: {config.get('database.host', '127.0.0.1')}\")\nprint(f\"Database Port: {config.get('database.port', 3306)}\")\nprint(f\"Non-existent setting (with default): {config.get('general.timeout', 30)}\")\nprint(f\"Non-existent setting (no default): {config.get('general.unknown')}\")\n\n# Clean up the created config file\nos.remove(config_file_name)","lang":"python","description":"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."},"warnings":[{"fix":"Use the `Config.get(key, default_value)` method instead, which provides the same functionality.","message":"The `Config.default` method was removed in version 2.0.0. It was previously used to retrieve a setting with a fallback value.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your `Config` initialization from `Config(project_name=\"my_app\")` to `Config(name=\"my_app\")`.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}