{"id":1674,"library":"python-box","title":"Python Box","description":"python-box is an active library that provides an advanced Python dictionary with dot notation access, allowing dictionary keys to be accessed as attributes. It simplifies working with deeply nested data structures and offers various serialization methods (JSON, YAML, TOML, JSON5, TOON) and other utility classes. The current version is 7.4.1, and it maintains a regular release cadence with updates and bug fixes.","status":"active","version":"7.4.1","language":"en","source_language":"en","source_url":"https://github.com/cdgriffith/Box","tags":["dictionary","dot-notation","configuration","serialization","yaml","json","toml"],"install":[{"cmd":"pip install python-box","lang":"bash","label":"Base Installation"},{"cmd":"pip install python-box[all]","lang":"bash","label":"With all optional dependencies"},{"cmd":"pip install python-box[yaml,toml,json5,toon]","lang":"bash","label":"With specific optional dependencies"}],"dependencies":[{"reason":"For YAML serialization/deserialization with 'Box.from_yaml' and 'Box.to_yaml'.","package":"PyYAML","optional":true},{"reason":"For TOML serialization/deserialization with 'Box.from_toml' and 'Box.to_toml'.","package":"toml","optional":true},{"reason":"For JSON5 serialization/deserialization with 'Box.from_json5' and 'Box.to_json5'.","package":"json5","optional":true},{"reason":"For TOON serialization/deserialization with 'Box.from_toon' and 'Box.to_toon'.","package":"toonet","optional":true}],"imports":[{"symbol":"Box","correct":"from box import Box"},{"symbol":"ConfigBox","correct":"from box import ConfigBox"},{"symbol":"DefaultBox","correct":"from box import DefaultBox"},{"symbol":"BoxList","correct":"from box import BoxList"},{"symbol":"ShorthandBox","correct":"from box import ShorthandBox"},{"symbol":"BoxKeyError","correct":"from box import BoxKeyError"}],"quickstart":{"code":"from box import Box\n\n# Create a Box from a dictionary\nconfig = Box({\n    'application': {\n        'name': 'MyAwesomeApp',\n        'version': '1.0.0',\n        'settings': {\n            'debug_mode': True,\n            'log_level': 'INFO'\n        }\n    },\n    'database': {\n        'host': 'localhost',\n        'port': 5432\n    }\n})\n\n# Access items using dot notation\nprint(f\"App Name: {config.application.name}\")\nprint(f\"Debug Mode: {config.application.settings.debug_mode}\")\n\n# Modify items\nconfig.database.port = 5433\nprint(f\"New DB Port: {config.database.port}\")\n\n# Add new items\nconfig.application.author = 'AI Agent'\nprint(f\"App Author: {config.application.author}\")\n\n# Example with missing key (will raise AttributeError without default_box_create_on_get)\ntry:\n    print(config.non_existent_key)\nexcept AttributeError as e:\n    print(f\"Caught expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to create a `Box` object from a standard Python dictionary and access its elements using convenient dot notation. It also shows how to modify and add new attributes, and highlights the behavior when accessing non-existent keys (raising an AttributeError by default)."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or higher. For example, Python 3.9 was dropped in 7.4.0, and 3.8 in 7.3.0.","message":"Support for older Python versions (3.8, 3.9) has been removed in recent major versions. Ensure your project runs on Python 3.10 or newer.","severity":"breaking","affected_versions":">=7.3.0"},{"fix":"If you need keys with periods to be treated literally without nesting, use the `box_dots_filter` parameter to specify which keys should be excluded from dot notation parsing, or use `box_dots_exclude` (added in 7.4.0) to explicitly list keys to ignore.","message":"The `box_dots` functionality changed in v7.0.0. Keys containing periods (`.`) are now automatically treated as nested keys by default, potentially altering data structure interpretation for existing code.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Install the required dependencies for the serialization format you intend to use. For example, `pip install python-box[yaml]` or `pip install python-box[all]` for all optional features.","message":"Serialization methods like `Box.from_yaml`, `Box.to_toml`, etc., require specific optional dependencies (e.g., `PyYAML`, `toml`) to be installed separately. Failing to install them will result in `ImportError`.","severity":"gotcha","affected_versions":"All"},{"fix":"Update the signature of your `default_function` to accept `box_instance` and `key` as arguments, even if you don't use them, e.g., `def my_default_func(box_instance, key): ...`","message":"The signature for `default_function` when defining default behavior in `DefaultBox` was changed in v7.0.0, now including `box_instance` and `key` parameters.","severity":"breaking","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}