Initial commit

2025-11-29 18:49:58 +08:00
commit 5007abf04b
89 changed files with 44129 additions and 0 deletions
--- a/skills/python3-development/references/modern-modules/box.md
+++ b/skills/python3-development/references/modern-modules/box.md
@@ -0,0 +1,683 @@
+---
+title: "python-box: Advanced Python Dictionaries with Dot Notation Access"
+library_name: python-box
+pypi_package: python-box
+category: data_structures
+python_compatibility: "3.9+"
+last_updated: "2025-11-02"
+official_docs: "https://github.com/cdgriffith/Box/wiki"
+official_repository: "https://github.com/cdgriffith/Box"
+maintenance_status: "active"
+---
+
+# python-box: Advanced Python Dictionaries with Dot Notation Access
+
+## Overview
+
+python-box extends Python's built-in dictionary with dot notation access and powerful configuration management features. It provides a transparent drop-in replacement for standard dicts while adding recursive dot notation, automatic type conversion, and seamless serialization to/from JSON, YAML, TOML, and msgpack formats.
+
+**Official Repository:** @<https://github.com/cdgriffith/Box> **Documentation:** @<https://github.com/cdgriffith/Box/wiki> **PyPI Package:** `python-box` **License:** MIT **Maintained By:** Chris Griffith (@cdgriffith)
+
+## Core Purpose
+
+### Problem Box Solves
+
+Without python-box, working with nested dictionaries requires verbose bracket notation:
+
+```python
+# Standard dict - verbose and error-prone
+config = {
+    "database": {
+        "host": "localhost",
+        "port": 5432,
+        "credentials": {
+            "username": "admin",
+            "password": "secret"
+        }
+    }
+}
+
+# Accessing nested values - clunky syntax
+db_host = config["database"]["host"]
+db_user = config["database"]["credentials"]["username"]
+
+# KeyError if key doesn't exist
+try:
+    timeout = config["database"]["timeout"]  # KeyError!
+except KeyError:
+    timeout = 30
+```
+
+With python-box, you get clean dot notation and safe defaults:
+
+```python
+from box import Box
+
+config = Box({
+    "database": {
+        "host": "localhost",
+        "port": 5432,
+        "credentials": {
+            "username": "admin",
+            "password": "secret"
+        }
+    }
+})
+
+# Clean dot notation access
+db_host = config.database.host
+db_user = config.database.credentials.username
+
+# Safe access with defaults (using DefaultBox)
+from box import DefaultBox
+config = DefaultBox(config, default_box=True)
+timeout = config.database.timeout or 30  # No KeyError
+```
+
+### When You're Reinventing the Wheel
+
+You should use python-box when you find yourself:
+
+1. **Writing custom attribute access wrappers** for dictionaries
+2. **Implementing recursive dictionary-to-object converters**
+3. **Manually sanitizing dictionary keys** to make them Python-safe
+4. **Writing boilerplate** for JSON/YAML configuration loading
+5. **Creating frozen/immutable configuration objects** from dicts
+6. **Implementing safe nested dictionary access** with try/except blocks
+
+## Installation
+
+```bash
+# Basic installation (no serialization dependencies)
+pip install python-box~=7.0
+
+# With all dependencies (YAML, TOML, msgpack)
+pip install python-box[all]~=7.0
+
+# With specific dependencies
+pip install python-box[yaml]~=7.0        # PyYAML or ruamel.yaml
+pip install python-box[toml]~=7.0        # tomli/tomli-w
+pip install python-box[msgpack]~=7.0     # msgpack
+
+# Optimized version with Cython (requires build tools)
+pip install Cython wheel
+pip install python-box[all]~=7.0 --force
+```
+
+**Version Pinning:** Always use compatible release matching (`~=7.0`) as Box follows semantic versioning. Check @<https://github.com/cdgriffith/Box/wiki/Major-Version-Breaking-Changes> before upgrading major versions.
+
+## Python Version Compatibility
+
+- **Minimum:** Python 3.9
+- **Supported:** Python 3.9, 3.10, 3.11, 3.12, 3.13
+- **Dropped Support:** Python 3.8 (removed in v7.3.0, EOL)
+- **Python 3.14:** Expected compatibility (based on current trajectory)
+
+**Cython Optimization:** Available for x86_64 platforms. Loading large datasets can be up to 10x faster with Cython-compiled version.
+
+## Core Features & Usage Examples
+
+### 1. Basic Box Usage
+
+```python
+from box import Box
+
+# Create from dict
+movie_box = Box({
+    "Robin Hood: Men in Tights": {
+        "imdb_stars": 6.7,
+        "length": 104
+    }
+})
+
+# Automatic key conversion for dot notation
+# Spaces become underscores, special chars removed
+movie_box.Robin_Hood_Men_in_Tights.imdb_stars  # 6.7
+
+# Standard dict access still works
+movie_box["Robin Hood: Men in Tights"]["length"]  # 104
+
+# Both are equivalent
+assert movie_box.Robin_Hood_Men_in_Tights.imdb_stars == \
+       movie_box["Robin Hood: Men in Tights"]["imdb_stars"]
+```
+
+### 2. Configuration Management with ConfigBox
+
+```python
+from box import ConfigBox
+import os
+
+# Load environment-specific configuration
+config_data = {
+    "development": {
+        "database": {
+            "host": "localhost",
+            "port": 5432,
+            "pool_size": 5
+        },
+        "debug": True
+    },
+    "production": {
+        "database": {
+            "host": "prod-db.server.com",
+            "port": 5432,
+            "pool_size": 20
+        },
+        "debug": False
+    }
+}
+
+# Select environment
+env = os.getenv("APP_ENV", "development")
+config = ConfigBox(config_data[env])
+
+print(f"Database Host for {env}: {config.database.host}")
+print(f"Pool Size: {config.database.pool_size}")
+print(f"Debug Mode: {config.debug}")
+```
+
+### 3. JSON/YAML/TOML Serialization
+
+```python
+from box import Box
+
+# From JSON
+config = Box.from_json(filename="config.json")
+
+# From YAML
+config = Box.from_yaml(filename="config.yaml")
+
+# From TOML
+config = Box.from_toml(filename="config.toml")
+
+# To JSON
+config.to_json(filename="output.json", indent=2)
+
+# To YAML
+config.to_yaml(filename="output.yaml")
+
+# To dict (for standard JSON serialization)
+import json
+json.dumps(config.to_dict())
+```
+
+### 4. DefaultBox for Safe Access
+
+```python
+from box import DefaultBox
+
+# Create with default values
+config = DefaultBox(default_box=True, default_box_attr={})
+
+# Access non-existent nested keys safely
+# Instead of KeyError, creates empty Box objects
+config.api.endpoints.users = "/api/v1/users"
+config.api.endpoints.posts = "/api/v1/posts"
+
+# Check existence
+if config.cache.enabled:
+    print("Cache is enabled")
+else:
+    print("Cache not configured")  # This prints
+```
+
+### 5. FrozenBox for Immutability
+
+```python
+from box import Box
+
+# Create mutable box
+config = Box({"debug": True, "timeout": 30})
+config.debug = False  # Allowed
+
+# Freeze it
+frozen_config = config.freeze()
+# or
+frozen_config = Box({"debug": True}, frozen_box=True)
+
+# Attempts to modify raise BoxError
+try:
+    frozen_config.debug = False
+except Exception as e:
+    print(f"Error: {e}")  # BoxError: Box is frozen
+```
+
+### 6. Box Variants
+
+```python
+from box import Box, BoxList
+
+# CamelKillerBox - converts camelCase to snake_case
+from box import Box
+config = Box({"apiEndpoint": "https://api.example.com"}, camel_killer_box=True)
+config.api_endpoint  # Works!
+
+# BoxList - list of Box objects
+from box import BoxList
+users = BoxList([
+    {"name": "Alice", "age": 30},
+    {"name": "Bob", "age": 25}
+])
+users[0].name  # "Alice"
+users[1].age   # 25
+
+# Box with dots in keys
+from box import Box
+config = Box({"api.version": "v2"}, box_dots=True)
+config["api.version"]  # Access with dots in key
+```
+
+## Real-World Usage Patterns
+
+### Pattern 1: Application Configuration
+
+```python
+# config/settings.py
+from box import ConfigBox
+from pathlib import Path
+
+def load_config(env: str = "development") -> ConfigBox:
+    """Load environment-specific configuration."""
+    config_path = Path(__file__).parent / f"{env}.yaml"
+    return ConfigBox.from_yaml(filename=config_path)
+
+# usage
+config = load_config(os.getenv("ENVIRONMENT", "development"))
+db_url = f"postgresql://{config.database.host}:{config.database.port}"
+```
+
+### Pattern 2: API Response Handling
+
+```python
+# Instead of dealing with nested dicts from API responses
+import requests
+from box import Box
+
+response = requests.get("https://api.example.com/user/123")
+user_data = Box(response.json())
+
+# Clean access to nested data
+print(f"User: {user_data.profile.name}")
+print(f"Email: {user_data.contact.email}")
+print(f"Company: {user_data.employment.company.name}")
+
+# vs traditional dict access:
+# print(f"User: {response.json()['profile']['name']}")
+```
+
+### Pattern 3: Argparse Integration
+
+```python
+import argparse
+from box import Box
+
+parser = argparse.ArgumentParser()
+parser.add_argument('floats', metavar='N', type=float, nargs='+')
+parser.add_argument("-v", "--verbosity", action="count", default=0)
+
+# Parse into Box instead of Namespace
+args = parser.parse_args(['1', '2', '3', '-vv'], namespace=Box())
+
+# Can now use as dict or object
+print(args.floats)      # [1.0, 2.0, 3.0]
+print(args.verbosity)   # 2
+
+# Easy to pass as kwargs
+def process(**kwargs):
+    print(kwargs)
+
+process(**args.to_dict())
+```
+
+## Integration Patterns
+
+### JSON Configuration Files
+
+```python
+from box import Box
+
+# config.json
+# {
+#   "app": {
+#     "name": "MyApp",
+#     "version": "1.0.0"
+#   },
+#   "features": {
+#     "auth": true,
+#     "cache": false
+#   }
+# }
+
+config = Box.from_json(filename="config.json")
+if config.features.auth:
+    setup_authentication()
+```
+
+### YAML Configuration Files
+
+```python
+from box import Box
+
+# config.yaml
+# database:
+#   host: localhost
+#   port: 5432
+#   credentials:
+#     username: admin
+#     password: secret
+
+config = Box.from_yaml(filename="config.yaml")
+db_conn = connect(
+    host=config.database.host,
+    port=config.database.port,
+    user=config.database.credentials.username,
+    password=config.database.credentials.password
+)
+```
+
+### TOML Configuration Files
+
+```python
+from box import Box
+
+# pyproject.toml or config.toml
+# [tool.myapp]
+# name = "MyApp"
+# version = "1.0.0"
+#
+# [tool.myapp.database]
+# host = "localhost"
+# port = 5432
+
+config = Box.from_toml(filename="pyproject.toml")
+app_name = config.tool.myapp.name
+db_host = config.tool.myapp.database.host
+```
+
+## When NOT to Use python-box
+
+### 1. Performance-Critical Code
+
+```python
+# DON'T use Box in tight loops or performance hotspots
+# Box has overhead for attribute access and conversion
+
+# Bad: Hot loop with Box
+results = Box()
+for i in range(1_000_000):
+    results[f"key_{i}"] = compute_value(i)  # Overhead!
+
+# Good: Use regular dict, convert after if needed
+results = {}
+for i in range(1_000_000):
+    results[f"key_{i}"] = compute_value(i)
+results = Box(results)  # Convert once
+```
+
+### 2. When Dict Protocol is Required
+
+```python
+# Some libraries expect strict dict instances
+import json
+from box import Box
+
+config = Box({"key": "value"})
+
+# This might fail with some JSON encoders expecting dict
+# Use .to_dict() to convert back
+json.dumps(config.to_dict())  # Safe
+```
+
+### 3. Simple, Flat Dictionaries
+
+```python
+# DON'T use Box for simple flat dicts without nesting
+# Regular dict is simpler and faster
+
+# Overkill
+simple = Box({"name": "Alice", "age": 30})
+print(simple.name)
+
+# Better
+simple = {"name": "Alice", "age": 30}
+print(simple["name"])
+```
+
+### 4. When Key Names Match Python Keywords
+
+```python
+# Be careful with Python keywords as attributes
+from box import Box
+
+# This works but is awkward
+data = Box({"class": "A", "type": "object"})
+data["class"]  # Must use bracket notation
+# data.class  # SyntaxError!
+
+# Better: Use regular dict or rename keys
+data = {"class_name": "A", "type_name": "object"}
+```
+
+## Decision Matrix: Box vs dict vs dataclass
+
+| Scenario                            | Use Box         | Use dict             | Use dataclass        |
+| ----------------------------------- | --------------- | -------------------- | -------------------- |
+| **Configuration files** (JSON/YAML) | ✅ Excellent    | ❌ Verbose           | ⚠️ Needs validation  |
+| **API response handling**           | ✅ Excellent    | ❌ Verbose           | ❌ Schema unknown    |
+| **Nested data structures**          | ✅ Excellent    | ⚠️ Works but verbose | ✅ Good with nesting |
+| **Type checking/IDE support**       | ❌ Dynamic only | ❌ Dynamic only      | ✅ Full typing       |
+| **Performance critical code**       | ❌ Overhead     | ✅ Fastest           | ✅ Fast              |
+| **Immutable configuration**         | ✅ FrozenBox    | ❌ No built-in       | ✅ frozen=True       |
+| **Dynamic key names**               | ✅ Flexible     | ✅ Flexible          | ❌ Fixed attrs       |
+| **Need serialization helpers**      | ✅ Built-in     | ⚠️ Manual            | ⚠️ Manual            |
+| **Simple flat structures**          | ⚠️ Overkill     | ✅ Perfect           | ✅ Good              |
+| **Unknown data structure**          | ✅ Flexible     | ✅ Flexible          | ❌ Needs schema      |
+
+## Decision Guidance
+
+### Use Box When
+
+1. **Working with configuration files** (YAML, JSON, TOML)
+2. **Handling nested API responses** with deep structures
+3. **You want cleaner dot notation** instead of brackets
+4. **Converting between dict and JSON/YAML frequently**
+5. **Need automatic nested dict conversion**
+6. **Working with data from external sources** (APIs, config files)
+7. **Prototyping or rapid development** where flexibility matters
+
+### Use dict When
+
+1. **Performance is critical** (tight loops, hot paths)
+2. **Simple, flat data structures**
+3. **Working with libraries expecting strict dict protocol**
+4. **You need maximum compatibility** with standard library
+5. **Memory efficiency is paramount** (minimal overhead)
+
+### Use dataclass When
+
+1. **Type safety and IDE autocomplete** are critical
+2. **Data structure is well-defined and stable**
+3. **You want validation** (with pydantic or attrs)
+4. **Building APIs or libraries** with clear contracts
+5. **Need immutability** with frozen=True
+6. **Working in type-checked codebases** (mypy, pyright)
+
+## Example Projects Using python-box
+
+Based on GitHub code search @<https://github.com/search?q=%22from+box+import+Box%22&type=code>, python-box is commonly used in:
+
+1. **Machine Learning/AI Projects**
+   - Configuration management for model training
+   - Hyperparameter storage
+   - Experiment tracking configurations
+
+2. **Web Applications**
+   - Flask/FastAPI configuration handling
+   - API response processing
+   - Environment-specific settings
+
+3. **Data Science**
+   - Notebook configuration management
+   - Dataset metadata handling
+   - Pipeline configurations
+
+4. **DevOps/Infrastructure**
+   - Terraform/Ansible configuration processing
+   - CI/CD pipeline configurations
+   - Container orchestration configs
+
+## Performance Considerations
+
+### Cython Optimization
+
+```bash
+# For x86_64 platforms, install with Cython for ~10x faster loading
+pip install Cython wheel
+pip install python-box[all]~=7.0 --upgrade --force
+
+# For non-x86_64, you'll need:
+# - Python development files (python3-dev/python3-devel)
+# - System compiler (gcc, clang)
+# - Cython and wheel packages
+```
+
+### Memory vs Convenience Trade-off
+
+```python
+# Box adds ~3-5x memory overhead vs dict for large structures
+import sys
+from box import Box
+
+# Regular dict
+data = {"key": "value"}
+print(sys.getsizeof(data))  # ~240 bytes
+
+# Box wrapper
+box_data = Box({"key": "value"})
+print(sys.getsizeof(box_data))  # ~240 bytes (similar, but internal overhead for methods)
+
+# For large datasets, convert to Box after processing
+large_data = {}
+for i in range(10000):
+    large_data[f"key_{i}"] = process_data(i)
+# Convert once after collection
+config = Box(large_data)
+```
+
+## Common Pitfalls & Solutions
+
+### Pitfall 1: Attribute vs Key Confusion
+
+```python
+from box import Box
+
+config = Box({"class": "A", "type": "B"})
+
+# Problem: Python keywords can't be attributes
+# config.class  # SyntaxError!
+
+# Solution: Use bracket notation
+config["class"]  # Works
+
+# Or rename keys during creation
+config = Box({"class_name": "A", "type_name": "B"})
+config.class_name  # Works
+```
+
+### Pitfall 2: Modification of Frozen Box
+
+```python
+from box import Box
+
+# Frozen box prevents all modifications
+config = Box({"debug": True}, frozen_box=True)
+
+# These all fail with BoxError
+# config.debug = False
+# config.new_key = "value"
+# config["debug"] = False
+
+# Solution: Create unfrozen copy
+mutable_config = Box(config.to_dict())
+mutable_config.debug = False  # Works
+```
+
+### Pitfall 3: Conversion Overhead
+
+```python
+from box import Box
+
+# Problem: Creating Box in tight loops
+def process_items(items):
+    results = []
+    for item in items:
+        item_box = Box(item)  # Overhead per iteration!
+        results.append(item_box.process())
+    return results
+
+# Solution: Convert once, or avoid Box in hot path
+def process_items_better(items):
+    items_box = Box({"items": items})
+    return [item["process"] for item in items_box.items]
+```
+
+## Version History & Breaking Changes
+
+- **v7.3.2** (2025-01-16): Latest stable release
+  - Bug fixes for box_dots and default_box_create_on_get
+- **v7.3.0** (2024-12-10): Python 3.13 support added
+  - Dropped Python 3.8 support (EOL)
+- **v7.2.0** (2024-06-12): Python 3.12 support
+  - Numpy-style tuple indexing for BoxList
+- **v7.0.0**: Major version with breaking changes
+
+**Breaking Changes:** @<https://github.com/cdgriffith/Box/wiki/Major-Version-Breaking-Changes>
+
+Always check release notes before upgrading major versions.
+
+## Related Libraries & Alternatives
+
+| Library                   | Use Case                      | vs python-box                       |
+| ------------------------- | ----------------------------- | ----------------------------------- |
+| **types.SimpleNamespace** | Simple attribute access       | Built-in, but no dict methods       |
+| **munch**                 | Dot notation dict             | Less features, unmaintained         |
+| **addict**                | Dict subclass with dot access | Similar, less popular               |
+| **pydantic**              | Validated data structures     | Type-safe, validation, more complex |
+| **attrs/dataclasses**     | Structured data               | Type-safe, but not for dynamic data |
+| **DynaBox**               | Similar to Box                | Less mature                         |
+
+**When to use Box over alternatives:**
+
+- Need dict compatibility + dot notation
+- Working with JSON/YAML config files
+- Don't need static type checking
+- Want automatic nested conversion
+
+## Additional Resources
+
+- **Official Wiki:** @<https://github.com/cdgriffith/Box/wiki>
+- **Quick Start:** @<https://github.com/cdgriffith/Box/wiki/Quick-Start>
+- **Types of Boxes:** @<https://github.com/cdgriffith/Box/wiki/Types-of-Boxes>
+- **Converters:** @<https://github.com/cdgriffith/Box/wiki/Converters>
+- **Installation Guide:** @<https://github.com/cdgriffith/Box/wiki/Installation>
+- **PyPI Package:** @<https://pypi.org/project/python-box/>
+- **GitHub Issues:** @<https://github.com/cdgriffith/Box/issues>
+
+## Contributing & Support
+
+**Maintainer:** Chris Griffith (@cdgriffith) **Contributors:** @<https://github.com/cdgriffith/Box/blob/master/AUTHORS.rst> **Issues/Questions:** @<https://github.com/cdgriffith/Box/issues>
+
+The library is actively maintained with regular releases and responsive issue handling.
+
+---
+
+**Research Sources:**
+
+- @<https://github.com/cdgriffith/Box> (Official Repository)
+- @<https://github.com/cdgriffith/Box/wiki> (Official Documentation)
+- @<https://pypi.org/project/python-box/> (Package Registry)
+- @<https://medium.com/@post.gourang/simplifying-configuration-management-in-python-with-configbox-90df67d26bce> (Tutorial)
+- GitHub Code Search for real-world usage examples
+
+**Last Updated:** 2025-10-21 **Research Quality:** High - Based on official documentation, source code analysis, and real-world usage patterns