Merge pull request #1 from lzjever/lzj/feature/filter_nonleaf_entries

Lzj/feature/filter nonleaf entries

Author: lzjever

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.1] - 2026-01-09
+
+### Added
+- **Configuration Export Functionality**: New methods to export current configuration to various file formats
+  - `Config.to_dict()` - Get current configuration as dictionary
+  - `Config.dump_json(file_path, ...)` - Export configuration to JSON file
+  - `Config.dump_yaml(file_path, ...)` - Export configuration to YAML file
+  - `Config.dump_toml(file_path, ...)` - Export configuration to TOML file
+  - `Config.dump_env(file_path, ...)` - Export configuration to .env file
+  - All export methods handle nested dataclass structures correctly
+  - Support for custom options (prefix, uppercase, nested separator for .env export)
+  - Clear error messages for missing optional dependencies (PyYAML, tomli-w)
+- **Enhanced Diagnostic Table**: Improved `--check-variables` output
+  - Now filters out non-leaf nodes (intermediate nested config objects)
+  - Only displays leaf-level configuration variables (e.g., `ai.completion.model` instead of `ai.completion`)
+  - Cleaner, more focused diagnostic output for nested configurations
+
+### Changed
+- `format_diagnostic_table()` now only shows leaf nodes in variable status table
+- Export methods use `asdict()` for proper nested dataclass conversion
+
 ## [0.7.0] - 2026-01-08
 
 ### Added

docs/source/api_reference/sources.rst

@@ -27,6 +27,5 @@ Etcd Source
 
 .. automodule:: varlord.sources.etcd
    :members:
-   :special-members: __init__
+   :special-members: \_\_init\_\_
    :exclude-members: _get_client, _model
-

docs/source/conf.py

@@ -108,8 +108,6 @@
 # The error occurs because Sphinx may interpret "etcd" in docstrings as a reference
 suppress_warnings = [
     'ref.docutils',  # Suppress docutils reference warnings (includes "Unknown target name" errors)
-    'ref.any',       # Suppress any reference warnings
-    'ref.python',    # Suppress Python reference warnings
 ]
 
 # Configure docutils to be less strict about unknown references

docs/source/user_guide/cli_commands.rst

@@ -107,11 +107,13 @@ The ``--check-variables`` (or ``-cv``) option displays comprehensive diagnostic
 about your configuration:
 
 1. **Variable Status Table**: Shows all configuration variables with:
-   - Variable name
+   - Variable name (only leaf nodes are shown - nested intermediate objects like `ai.completion` are filtered out)
    - Required/Optional status
    - Current status (Loaded, Using Default, Missing, etc.)
    - Source (which source provided the value)
    - Value (truncated if too long)
+   
+   **Note**: For nested configurations, only leaf-level variables are displayed. For example, if you have `ai.completion.model` and `ai.completion.api_key`, the table will show these two variables but not the intermediate `ai.completion` object.
 
 2. **Source Information Table**: Shows detailed diagnostics for each source:
    - Priority order (1 = lowest, higher numbers = higher priority)
@@ -131,7 +133,13 @@ Example diagnostic output:
    | host                                       | Required | Missing       | defaults | None   |
    | port                                       | Optional | Using Default | defaults | 8000   |
    | debug                                      | Optional | Using Default | defaults | False  |
+   | ai.completion.model                        | Required | Loaded        | yaml     | deepseek-chat |
+   | ai.completion.api_key                      | Required | Loaded        | yaml     | sk-... |
+   | ai.performance.max_tokens_input           | Optional | Loaded        | yaml     | 131072 |
    +--------------------------------------------+----------+---------------+----------+--------+
+   
+   Note: Intermediate nested objects (like `ai.completion` or `ai.performance`) are not shown,
+   only the leaf-level configuration variables are displayed.
 
    Configuration Source Priority and Details:
 

docs/source/user_guide/export.rst

@@ -0,0 +1,285 @@
+Configuration Export
+====================
+
+Varlord provides functionality to export the current configuration to various file formats,
+making it easy to save, share, or version control your configuration.
+
+Basic Usage
+-----------
+
+After loading your configuration, you can export it to different formats:
+
+.. code-block:: python
+   :linenos:
+
+   from varlord import Config, sources
+   from dataclasses import dataclass, field
+
+   @dataclass
+   class AppConfig:
+       api_key: str = field()
+       host: str = field(default="0.0.0.0")
+       port: int = field(default=8000)
+
+   # Create and load config
+   cfg = Config(
+       model=AppConfig,
+       sources=[sources.Env(), sources.CLI()],
+   )
+   cfg.handle_cli_commands()
+   config = cfg.load()
+
+   # Export to different formats
+   cfg.dump_json("config.json")
+   cfg.dump_yaml("config.yaml")
+   cfg.dump_toml("config.toml")
+   cfg.dump_env(".env", prefix="APP_")
+
+Export Methods
+--------------
+
+Get Configuration as Dictionary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``to_dict()`` to get the current configuration as a dictionary without writing to a file:
+
+.. code-block:: python
+
+   config_dict = cfg.to_dict()
+   print(config_dict["host"])
+   print(config_dict["port"])
+
+This is useful when you need to programmatically access configuration values or pass them to other functions.
+
+JSON Export
+~~~~~~~~~~~
+
+Export configuration to JSON format:
+
+.. code-block:: python
+
+   cfg.dump_json("config.json", indent=4)
+
+**Parameters:**
+- ``file_path``: Path to output JSON file (str or Path)
+- ``validate``: Whether to validate required fields before export (default: True)
+- ``indent``: JSON indentation level (default: 2)
+
+**Example output:**
+
+.. code-block:: json
+
+   {
+     "api_key": "sk-...",
+     "host": "0.0.0.0",
+     "port": 8000
+   }
+
+YAML Export
+~~~~~~~~~~~
+
+Export configuration to YAML format:
+
+.. code-block:: python
+
+   cfg.dump_yaml("config.yaml", default_flow_style=False)
+
+**Parameters:**
+- ``file_path``: Path to output YAML file (str or Path)
+- ``validate``: Whether to validate required fields before export (default: True)
+- ``default_flow_style``: Use flow style (default: False, uses block style)
+
+**Dependencies:** Requires ``pyyaml`` package. Install with: ``pip install pyyaml``
+
+**Example output:**
+
+.. code-block:: yaml
+
+   api_key: sk-...
+   host: 0.0.0.0
+   port: 8000
+
+TOML Export
+~~~~~~~~~~~
+
+Export configuration to TOML format:
+
+.. code-block:: python
+
+   cfg.dump_toml("config.toml")
+
+**Parameters:**
+- ``file_path``: Path to output TOML file (str or Path)
+- ``validate``: Whether to validate required fields before export (default: True)
+
+**Dependencies:** Requires ``tomli-w`` package. Install with: ``pip install tomli-w``
+
+**Example output:**
+
+.. code-block:: toml
+
+   api_key = "sk-..."
+   host = "0.0.0.0"
+   port = 8000
+
+.env Export
+~~~~~~~~~~~
+
+Export configuration to .env file format (for environment variables):
+
+.. code-block:: python
+
+   cfg.dump_env(
+       ".env",
+       prefix="APP_",
+       uppercase=True,
+       nested_separator="__"
+   )
+
+**Parameters:**
+- ``file_path``: Path to output .env file (str or Path)
+- ``validate``: Whether to validate required fields before export (default: True)
+- ``prefix``: Optional prefix for all environment variable names (e.g., ``APP_``)
+- ``uppercase``: Convert keys to uppercase (default: True)
+- ``nested_separator``: Separator for nested keys (default: "__")
+
+**Example output:**
+
+.. code-block:: text
+
+   APP_API_KEY=sk-...
+   APP_HOST=0.0.0.0
+   APP_PORT=8000
+
+Nested Configuration
+--------------------
+
+All export methods correctly handle nested dataclass structures:
+
+.. code-block:: python
+   :linenos:
+
+   @dataclass
+   class DBConfig:
+       host: str = field(default="localhost")
+       port: int = field(default=5432)
+
+   @dataclass
+   class AppConfig:
+       api_key: str = field()
+       db: DBConfig = field(default_factory=lambda: DBConfig())
+
+   cfg = Config(model=AppConfig, sources=[...])
+   cfg.dump_json("config.json")
+
+**JSON output:**
+
+.. code-block:: json
+
+   {
+     "api_key": "sk-...",
+     "db": {
+       "host": "localhost",
+       "port": 5432
+     }
+   }
+
+**YAML output:**
+
+.. code-block:: yaml
+
+   api_key: sk-...
+   db:
+     host: localhost
+     port: 5432
+
+**TOML output:**
+
+.. code-block:: toml
+
+   api_key = "sk-..."
+   [db]
+   host = "localhost"
+   port = 5432
+
+**.env output (with nested separator):**
+
+.. code-block:: text
+
+   API_KEY=sk-...
+   DB__HOST=localhost
+   DB__PORT=5432
+
+Use Cases
+---------
+
+Configuration Backup
+~~~~~~~~~~~~~~~~~~~~~
+
+Export your current configuration to save a snapshot:
+
+.. code-block:: python
+
+   # Save current config as backup
+   cfg.dump_yaml(f"config_backup_{datetime.now().isoformat()}.yaml")
+
+Configuration Templates
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Generate configuration templates for users:
+
+.. code-block:: python
+
+   # Create template with defaults
+   template_cfg = Config(model=AppConfig, sources=[])
+   template_cfg.dump_json("config.template.json")
+
+Environment Setup
+~~~~~~~~~~~~~~~~~
+
+Generate .env files for different environments:
+
+.. code-block:: python
+
+   # Development environment
+   cfg.dump_env(".env.development", prefix="APP_DEV_")
+
+   # Production environment
+   cfg.dump_env(".env.production", prefix="APP_PROD_")
+
+Configuration Sharing
+~~~~~~~~~~~~~~~~~~~~~
+
+Export configuration to share with team members or for documentation:
+
+.. code-block:: python
+
+   # Export to YAML for documentation
+   cfg.dump_yaml("docs/example_config.yaml")
+
+Dependencies
+------------
+
+- **JSON**: Built-in (no extra dependencies required)
+- **YAML**: Requires ``pyyaml`` (``pip install pyyaml``)
+- **TOML**: Requires ``tomli-w`` (``pip install tomli-w``)
+- **.env**: Built-in (no extra dependencies required)
+
+If a required dependency is missing, the export method will raise an ``ImportError`` with a clear message indicating which package needs to be installed.
+
+Best Practices
+--------------
+
+1. **Validate before export**: By default, all export methods validate required fields. Set ``validate=False`` only if you're intentionally exporting incomplete configurations.
+
+2. **Use appropriate formats**: 
+   - Use JSON for machine-readable configs and APIs
+   - Use YAML for human-readable configs and documentation
+   - Use TOML for Python projects (pyproject.toml style)
+   - Use .env for environment variable exports
+
+3. **Handle nested structures**: All export methods automatically handle nested dataclasses, so you don't need to manually flatten structures.
+
+4. **Use prefixes for .env**: When exporting to .env format, use prefixes to avoid conflicts with other environment variables.
+
+5. **Version control**: Consider adding exported config files to ``.gitignore`` if they contain sensitive information like API keys.

docs/source/user_guide/index.rst

@@ -13,6 +13,7 @@ This guide covers all aspects of using Varlord.
    key_mapping
    cli_commands
    subcommands
+   export
    custom_sources
    priority
    validation

docs/source/user_guide/key_mapping.rst

@@ -101,13 +101,21 @@ Env (Environment Variables)
 - ``K8S_POD_NAME`` → ``k8s_pod_name`` (single ``_`` preserved)
 - ``OTHER_VAR`` → ignored (not in model fields)
 
+**Prefix Filtering** (optional):
+
+- Use ``prefix`` parameter to filter environment variables by prefix
+- Example: ``sources.Env(prefix="APP__")`` only loads variables starting with ``APP__``
+- Case-insensitive matching (e.g., ``app__`` matches ``APP__``)
+- Prefix is automatically removed before key normalization
+- Useful for isolating application-specific environment variables in containerized deployments
+
 **Notes**:
 
 - Model is required and will be auto-injected by ``Config`` if not provided
 - All environment variables are checked against model fields
 - Only variables that map to model fields are loaded
-- No prefix filtering - use model fields to control which variables are loaded
-- If you want to use a prefix in environment variable names, ensure your model field names match after normalization
+- If ``prefix`` is not provided, all environment variables matching model fields are loaded
+- Prefix matching is case-insensitive for better compatibility
 
 CLI (Command-Line Arguments)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~