dataclass-args 1.2.0__tar.gz → 1.2.2__tar.gz

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataclass-args
-Version: 1.2.0
+Version: 1.2.2
 Summary: Zero-boilerplate CLI generation from Python dataclasses with advanced type support and file loading
 Author-email: Martin Bartlett <martin.j.bartlett@gmail.com>
 License: MIT

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/dataclass_args/__init__.py

@@ -65,7 +65,7 @@ from .exceptions import ConfigBuilderError, ConfigurationError, FileLoadingError
 from .file_loading import is_file_loadable_value, load_file_content
 from .utils import load_structured_file
 
-__version__ = "1.2.0"
+__version__ = "1.2.2"
 
 __all__ = [
     # Main API

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/dataclass_args/builder.py

@@ -55,12 +55,15 @@ class GenericConfigBuilder:
     def __init__(
         self,
         config_class: Type,
+        description: Optional[str] = None,
     ):
         """
         Initialize builder for a specific dataclass type.
 
         Args:
             config_class: Dataclass type to build configurations for
+            description: Optional description for ArgumentParser help text.
+                        If not provided, uses "Build {ClassName} from CLI"
 
         Raises:
             ConfigBuilderError: If config_class is not a dataclass
@@ -71,6 +74,7 @@ class GenericConfigBuilder:
             )
 
         self.config_class = config_class
+        self.description = description
         self._config_fields = self._analyze_config_fields()
 
     def _should_include_field(
@@ -387,14 +391,12 @@ class GenericConfigBuilder:
         # Get default value
         default_value = info.get("default", False)
 
-        # Set parser default to the field's default value
-        parser.set_defaults(**{dest_name: default_value})
-
         # Add positive form (--flag or -f)
         parser.add_argument(
             *positive_args,
             action="store_true",
             dest=dest_name,
+            default=argparse.SUPPRESS,
             help=f"{help_text} (default: {default_value})",
         )
 
@@ -404,6 +406,7 @@ class GenericConfigBuilder:
             negative_name,
             action="store_false",
             dest=dest_name,
+            default=argparse.SUPPRESS,
             help=f"Disable {help_text}",
         )
 
@@ -722,6 +725,7 @@ def build_config_from_cli(
     args: Optional[List[str]] = None,
     base_config_name: str = "config",
     base_configs: Optional[BaseConfigInput] = None,
+    description: Optional[str] = None,
 ) -> Any:
     """
     Build dataclass instance from CLI arguments with optional base configs.
@@ -739,6 +743,8 @@ def build_config_from_cli(
                      - str: Path to a single config file
                      - dict: A single configuration dictionary
                      - List[Union[str, dict]]: Multiple configs applied in order
+        description: Optional description for ArgumentParser help text.
+                    If not provided, uses "Build {ClassName} from CLI"
 
     Returns:
         Instance of config_class built from merged configurations
@@ -750,6 +756,12 @@ def build_config_from_cli(
         # Single dict
         config = build_config_from_cli(MyConfig, base_configs={'debug': True})
 
+        # With custom description
+        config = build_config_from_cli(
+            MyConfig,
+            description="Configure the application server"
+        )
+
         # Mixed list
         config = build_config_from_cli(
             MyConfig,
@@ -764,10 +776,14 @@ def build_config_from_cli(
     if args is None:
         args = sys.argv[1:]
 
-    builder = GenericConfigBuilder(config_class)
-    parser = argparse.ArgumentParser(
-        description=f"Build {config_class.__name__} from CLI"
+    builder = GenericConfigBuilder(config_class, description=description)
+
+    desc = (
+        builder.description
+        if builder.description is not None
+        else f"Build {config_class.__name__} from CLI"
     )
+    parser = argparse.ArgumentParser(description=desc)
     builder.add_arguments(parser, base_config_name)
 
     parsed_args = parser.parse_args(args)
@@ -778,6 +794,7 @@ def build_config(
     config_class: Type,
     args: Optional[List[str]] = None,
     base_configs: Optional[BaseConfigInput] = None,
+    description: Optional[str] = None,
 ) -> Any:
     """
     Simplified convenience function to build dataclass from CLI arguments.
@@ -794,6 +811,8 @@ def build_config(
                      - str: Path to a single config file
                      - dict: A single configuration dictionary
                      - List[Union[str, dict]]: Multiple configs applied in order
+        description: Optional description for ArgumentParser help text.
+                    If not provided, uses "Build {ClassName} from CLI"
 
     Returns:
         Instance of config_class built from merged configurations
@@ -805,6 +824,12 @@ def build_config(
         # With base config file
         config = build_config(Config, base_configs='defaults.yaml')
 
+        # With custom description
+        config = build_config(
+            Config,
+            description="My application configuration tool"
+        )
+
         # With mixed sources
         config = build_config(
             Config,
@@ -815,4 +840,6 @@ def build_config(
             ]
         )
     """
-    return build_config_from_cli(config_class, args, base_configs=base_configs)
+    return build_config_from_cli(
+        config_class, args, base_configs=base_configs, description=description
+    )

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/dataclass_args/utils.py

@@ -3,6 +3,7 @@ Utility functions for dataclass CLI configuration.
 """
 
 import json
+import sys
 from pathlib import Path
 from typing import Any, Dict, Union
 
@@ -13,15 +14,14 @@ try:
 except ImportError:
     HAS_YAML = False
 
-try:
-    # Python 3.11+
+# Handle TOML imports for different Python versions
+if sys.version_info >= (3, 11):
     import tomllib
 
     HAS_TOML = True
-except ImportError:
+else:
     try:
-        # Python < 3.11
-        import tomli as tomllib
+        import tomli as tomllib  # type: ignore[no-redef]
 
         HAS_TOML = True
     except ImportError:

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/dataclass_args.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataclass-args
-Version: 1.2.0
+Version: 1.2.2
 Summary: Zero-boilerplate CLI generation from Python dataclasses with advanced type support and file loading
 Author-email: Martin Bartlett <martin.j.bartlett@gmail.com>
 License: MIT

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/dataclass_args.egg-info/SOURCES.txt

@@ -14,12 +14,14 @@ dataclass_args.egg-info/requires.txt
 dataclass_args.egg-info/top_level.txt
 tests/test_annotations.py
 tests/test_basic.py
+tests/test_boolean_base_configs.py
 tests/test_boolean_flags.py
 tests/test_builder_advanced.py
 tests/test_cli_choices.py
 tests/test_cli_short.py
 tests/test_combine_annotations.py
 tests/test_config_merging_simple.py
+tests/test_description.py
 tests/test_file_loading.py
 tests/test_positional.py
 tests/test_utils.py

{dataclass_args-1.2.0 → dataclass_args-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dataclass-args"
-version = "1.2.0"
+version = "1.2.2"
 description = "Zero-boilerplate CLI generation from Python dataclasses with advanced type support and file loading"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -153,7 +153,6 @@ line_length = 88
 known_first_party = ["dataclass_args"]
 
 [tool.mypy]
-python_version = "3.9"
 warn_return_any = false
 warn_unused_configs = true
 disallow_untyped_defs = false

dataclass_args-1.2.2/tests/test_boolean_base_configs.py

@@ -0,0 +1,326 @@
+"""
+Tests for boolean field handling with base_configs.
+
+This module tests that boolean fields from base_configs are preserved correctly
+when not overridden by CLI flags.
+"""
+
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+import pytest
+
+from dataclass_args import build_config
+
+
+@dataclass
+class BoolConfig:
+    """Test config with various boolean fields."""
+
+    debug: bool = False
+    verbose: bool = True
+    enabled: bool = False
+    disabled: bool = True
+
+
+class TestBooleanFromDict:
+    """Test boolean values from base_configs dict."""
+
+    def test_bool_true_overrides_false_default(self):
+        """Boolean True from dict overrides False default."""
+        config = build_config(BoolConfig, args=[], base_configs={"debug": True})
+        assert config.debug is True
+
+    def test_bool_false_overrides_true_default(self):
+        """Boolean False from dict overrides True default."""
+        config = build_config(BoolConfig, args=[], base_configs={"verbose": False})
+        assert config.verbose is False
+
+    def test_multiple_bool_overrides(self):
+        """Multiple boolean overrides from dict."""
+        config = build_config(
+            BoolConfig,
+            args=[],
+            base_configs={
+                "debug": True,
+                "verbose": False,
+                "enabled": True,
+                "disabled": False,
+            },
+        )
+        assert config.debug is True
+        assert config.verbose is False
+        assert config.enabled is True
+        assert config.disabled is False
+
+    def test_partial_bool_overrides(self):
+        """Some fields from dict, others use defaults."""
+        config = build_config(
+            BoolConfig, args=[], base_configs={"debug": True, "enabled": True}
+        )
+        assert config.debug is True  # from dict
+        assert config.verbose is True  # default
+        assert config.enabled is True  # from dict
+        assert config.disabled is True  # default
+
+
+class TestBooleanFromFile:
+    """Test boolean values from base_configs file."""
+
+    def test_bool_from_json_file(self):
+        """Boolean values from JSON file."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write('{"debug": true, "verbose": false}')
+            config_file = f.name
+
+        try:
+            config = build_config(BoolConfig, args=[], base_configs=config_file)
+            assert config.debug is True
+            assert config.verbose is False
+        finally:
+            Path(config_file).unlink()
+
+    def test_bool_from_yaml_file(self):
+        """Boolean values from YAML file."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".yaml", delete=False) as f:
+            f.write("debug: true\nverbose: false\n")
+            config_file = f.name
+
+        try:
+            config = build_config(BoolConfig, args=[], base_configs=config_file)
+            assert config.debug is True
+            assert config.verbose is False
+        finally:
+            Path(config_file).unlink()
+
+
+class TestBooleanCLIOverride:
+    """Test that CLI arguments override base_configs."""
+
+    def test_cli_flag_overrides_dict(self):
+        """CLI --flag overrides dict value."""
+        config = build_config(
+            BoolConfig, args=["--debug"], base_configs={"debug": False}
+        )
+        assert config.debug is True
+
+    def test_cli_no_flag_overrides_dict(self):
+        """CLI --no-flag overrides dict value."""
+        config = build_config(
+            BoolConfig, args=["--no-verbose"], base_configs={"verbose": True}
+        )
+        assert config.verbose is False
+
+    def test_multiple_cli_overrides(self):
+        """Multiple CLI flags override dict values."""
+        config = build_config(
+            BoolConfig,
+            args=["--debug", "--no-verbose", "--enabled"],
+            base_configs={"debug": False, "verbose": True, "enabled": False},
+        )
+        assert config.debug is True
+        assert config.verbose is False
+        assert config.enabled is True
+
+
+class TestBooleanMixed:
+    """Test mixed scenarios: some CLI, some base_configs, some defaults."""
+
+    def test_cli_partial_dict_rest(self):
+        """Some from CLI, some from dict, some defaults."""
+        config = build_config(
+            BoolConfig,
+            args=["--debug"],  # Only debug from CLI
+            base_configs={
+                "verbose": False,
+                "enabled": True,
+            },  # verbose and enabled from dict
+        )
+        assert config.debug is True  # from CLI
+        assert config.verbose is False  # from dict
+        assert config.enabled is True  # from dict
+        assert config.disabled is True  # default
+
+    def test_dict_without_cli_preserves_values(self):
+        """Dict values preserved when no CLI flag for that field."""
+        config = build_config(
+            BoolConfig,
+            args=["--enabled"],  # Only set enabled via CLI
+            base_configs={
+                "debug": True,  # Should be preserved
+                "verbose": False,  # Should be preserved
+            },
+        )
+        assert config.debug is True  # from dict (no CLI override)
+        assert config.verbose is False  # from dict (no CLI override)
+        assert config.enabled is True  # from CLI
+        assert config.disabled is True  # default
+
+    def test_cli_overrides_one_dict_preserves_others(self):
+        """CLI overrides one field, dict values preserved for others."""
+        config = build_config(
+            BoolConfig,
+            args=["--no-verbose"],  # Override only verbose
+            base_configs={
+                "debug": True,
+                "verbose": True,  # Will be overridden
+                "enabled": True,
+            },
+        )
+        assert config.debug is True  # from dict
+        assert config.verbose is False  # from CLI (overrides dict)
+        assert config.enabled is True  # from dict
+
+
+class TestBooleanDefaultBehavior:
+    """Test that defaults work correctly without base_configs or CLI."""
+
+    def test_no_args_no_config_uses_defaults(self):
+        """No args, no config uses dataclass defaults."""
+        config = build_config(BoolConfig, args=[])
+        assert config.debug is False
+        assert config.verbose is True
+        assert config.enabled is False
+        assert config.disabled is True
+
+    def test_empty_dict_uses_defaults(self):
+        """Empty dict uses dataclass defaults."""
+        config = build_config(BoolConfig, args=[], base_configs={})
+        assert config.debug is False
+        assert config.verbose is True
+
+
+class TestBooleanConfigFilePlusCLI:
+    """Test --config file argument combined with CLI flags."""
+
+    def test_config_file_plus_cli_override(self):
+        """--config file combined with CLI override."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write('{"debug": true, "verbose": false}')
+            config_file = f.name
+
+        try:
+            config = build_config(
+                BoolConfig,
+                args=["--config", config_file, "--debug"],  # CLI overrides
+            )
+            # CLI explicitly set debug=True (same as file, but from CLI)
+            assert config.debug is True
+            # File set verbose=False
+            assert config.verbose is False
+        finally:
+            Path(config_file).unlink()
+
+    def test_base_configs_plus_config_file_plus_cli(self):
+        """Hierarchy: base_configs < --config file < CLI."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write('{"verbose": false}')
+            config_file = f.name
+
+        try:
+            config = build_config(
+                BoolConfig,
+                args=["--config", config_file, "--enabled"],
+                base_configs={"debug": True},  # Lowest priority
+            )
+            assert config.debug is True  # from base_configs
+            assert config.verbose is False  # from --config file
+            assert config.enabled is True  # from CLI
+        finally:
+            Path(config_file).unlink()
+
+
+class TestBooleanEdgeCases:
+    """Test edge cases for boolean handling."""
+
+    def test_bool_explicitly_set_to_default_via_cli(self):
+        """CLI flag explicitly sets value to match default."""
+        # Default is debug=False, explicitly set --no-debug
+        config = build_config(
+            BoolConfig,
+            args=["--no-debug"],  # Explicitly False
+            base_configs={"debug": True},  # Try to override
+        )
+        # CLI should win even though it matches default
+        assert config.debug is False
+
+    def test_bool_both_positive_and_negative_flags(self):
+        """Last flag wins if both positive and negative specified."""
+        config = build_config(
+            BoolConfig,
+            args=["--debug", "--no-debug"],  # Conflicting flags
+        )
+        # argparse behavior: last one wins
+        assert config.debug is False
+
+    def test_all_false_values(self):
+        """All booleans set to False."""
+        config = build_config(
+            BoolConfig,
+            args=[],
+            base_configs={
+                "debug": False,
+                "verbose": False,
+                "enabled": False,
+                "disabled": False,
+            },
+        )
+        assert config.debug is False
+        assert config.verbose is False
+        assert config.enabled is False
+        assert config.disabled is False
+
+    def test_all_true_values(self):
+        """All booleans set to True."""
+        config = build_config(
+            BoolConfig,
+            args=[],
+            base_configs={
+                "debug": True,
+                "verbose": True,
+                "enabled": True,
+                "disabled": True,
+            },
+        )
+        assert config.debug is True
+        assert config.verbose is True
+        assert config.enabled is True
+        assert config.disabled is True
+
+
+class TestBooleanMultipleBasConfigs:
+    """Test boolean handling with multiple base_configs."""
+
+    def test_list_of_dicts_later_overrides_earlier(self):
+        """Later dict in list overrides earlier dict."""
+        config = build_config(
+            BoolConfig,
+            args=[],
+            base_configs=[
+                {"debug": True, "verbose": False},
+                {"debug": False},  # Overrides debug only
+            ],
+        )
+        assert config.debug is False  # from second dict
+        assert config.verbose is False  # from first dict
+
+    def test_file_and_dict_combination(self):
+        """Mix files and dicts in base_configs list."""
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+            f.write('{"debug": true}')
+            config_file = f.name
+
+        try:
+            config = build_config(
+                BoolConfig,
+                args=[],
+                base_configs=[
+                    config_file,  # File first
+                    {"verbose": False},  # Dict second
+                ],
+            )
+            assert config.debug is True  # from file
+            assert config.verbose is False  # from dict
+        finally:
+            Path(config_file).unlink()

dataclass_args-1.2.2/tests/test_description.py

@@ -0,0 +1,243 @@
+"""Tests for custom description parameter."""
+
+import sys
+from dataclasses import dataclass
+from io import StringIO
+from typing import List, Optional
+
+import pytest
+
+from dataclass_args import GenericConfigBuilder, build_config, build_config_from_cli
+
+
+@dataclass
+class SimpleConfig:
+    """Simple config for testing."""
+
+    name: str = "default"
+    count: int = 10
+
+
+class TestCustomDescription:
+    """Test custom description parameter functionality."""
+
+    def test_builder_with_custom_description(self):
+        """Test GenericConfigBuilder with custom description."""
+        custom_desc = "My custom application configuration"
+        builder = GenericConfigBuilder(SimpleConfig, description=custom_desc)
+
+        assert builder.description == custom_desc
+        assert builder.config_class == SimpleConfig
+
+    def test_builder_with_no_description(self):
+        """Test GenericConfigBuilder without description defaults to None."""
+        builder = GenericConfigBuilder(SimpleConfig)
+
+        assert builder.description is None
+        assert builder.config_class == SimpleConfig
+
+    def test_build_config_with_custom_description(self, capsys):
+        """Test build_config with custom description in help."""
+        custom_desc = "Configure the application server"
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description=custom_desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert custom_desc in captured.out
+
+    def test_build_config_with_default_description(self, capsys):
+        """Test build_config without description uses default format."""
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"])
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert "Build SimpleConfig from CLI" in captured.out
+
+    def test_build_config_from_cli_with_custom_description(self, capsys):
+        """Test build_config_from_cli with custom description."""
+        custom_desc = "Server configuration utility"
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config_from_cli(
+                SimpleConfig, args=["--help"], description=custom_desc
+            )
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert custom_desc in captured.out
+
+    def test_build_config_from_cli_with_default_description(self, capsys):
+        """Test build_config_from_cli without description uses default."""
+        with pytest.raises(SystemExit) as exc_info:
+            build_config_from_cli(SimpleConfig, args=["--help"])
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert "Build SimpleConfig from CLI" in captured.out
+
+    def test_custom_description_does_not_affect_functionality(self):
+        """Test that custom description doesn't change parsing behavior."""
+        # Without description
+        config1 = build_config(SimpleConfig, args=["--name", "test1", "--count", "100"])
+
+        # With description
+        config2 = build_config(
+            SimpleConfig,
+            args=["--name", "test1", "--count", "100"],
+            description="Custom description",
+        )
+
+        assert config1.name == config2.name == "test1"
+        assert config1.count == config2.count == 100
+
+    def test_backward_compatibility_direct_builder(self):
+        """Test that existing code using GenericConfigBuilder still works."""
+        import argparse
+
+        # Old pattern: GenericConfigBuilder without description
+        builder = GenericConfigBuilder(SimpleConfig)
+        parser = argparse.ArgumentParser(description="Custom parser")
+        builder.add_arguments(parser)
+
+        args = parser.parse_args(["--name", "legacy", "--count", "42"])
+        config = builder.build_config(args)
+
+        assert config.name == "legacy"
+        assert config.count == 42
+
+    def test_backward_compatibility_convenience_functions(self):
+        """Test that existing convenience function calls still work."""
+        # Old pattern: build_config without description
+        config = build_config(SimpleConfig, args=["--name", "oldstyle"])
+
+        assert config.name == "oldstyle"
+        assert config.count == 10  # default
+
+    def test_multiline_description(self, capsys):
+        """Test that multiline descriptions work correctly."""
+        multiline_desc = """Configure the application server.
+
+This tool allows you to set various server parameters
+including name, port, and other settings."""
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description=multiline_desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        # argparse may format this, but key parts should be present
+        assert "Configure the application server" in captured.out
+
+    def test_empty_string_description(self, capsys):
+        """Test that empty string description is handled."""
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description="")
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        # Empty description should be used (not default)
+        assert "Build SimpleConfig from CLI" not in captured.out
+
+    def test_description_with_special_characters(self, capsys):
+        """Test description with special characters."""
+        special_desc = "Config tool: <options> [required] {advanced}"
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description=special_desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert "Config tool:" in captured.out
+
+
+class TestDescriptionWithComplexConfig:
+    """Test description parameter with more complex configurations."""
+
+    @dataclass
+    class ComplexConfig:
+        """Complex config with various field types."""
+
+        host: str = "localhost"
+        port: int = 8080
+        debug: bool = False
+        tags: Optional[List[str]] = None
+
+        def __post_init__(self):
+            if self.tags is None:
+                self.tags = []
+
+    def test_complex_config_with_description(self, capsys):
+        """Test complex config with custom description."""
+        desc = "Advanced server configuration with multiple options"
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(self.ComplexConfig, args=["--help"], description=desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        assert desc in captured.out
+        # Should still show all the arguments
+        assert "--host" in captured.out
+        assert "--port" in captured.out
+        assert "--debug" in captured.out
+
+    def test_complex_config_parsing_with_description(self):
+        """Test that complex config parsing works with description."""
+        config = build_config(
+            self.ComplexConfig,
+            args=["--host", "0.0.0.0", "--port", "9000", "--debug"],
+            description="Test configuration",
+        )
+
+        assert config.host == "0.0.0.0"
+        assert config.port == 9000
+        assert config.debug is True
+
+
+class TestDescriptionEdgeCases:
+    """Test edge cases and error conditions."""
+
+    def test_none_description_explicitly(self):
+        """Test explicitly passing None as description."""
+        builder = GenericConfigBuilder(SimpleConfig, description=None)
+        assert builder.description is None
+
+    def test_description_type_validation(self):
+        """Test that non-string descriptions work (argparse coerces to str)."""
+        # argparse will convert to string, so this should work
+        builder = GenericConfigBuilder(SimpleConfig, description=123)
+        assert builder.description == 123
+
+        # When used in ArgumentParser, argparse will handle conversion
+        import argparse
+
+        desc = builder.description or f"Build {builder.config_class.__name__} from CLI"
+        parser = argparse.ArgumentParser(description=str(desc))
+        assert "123" in parser.format_help()
+
+    def test_very_long_description(self, capsys):
+        """Test with a very long description."""
+        long_desc = "A " + "very " * 100 + "long description."
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description=long_desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        # argparse will format it, but it should appear
+        assert "very" in captured.out
+
+    def test_description_with_unicode(self, capsys):
+        """Test description with unicode characters."""
+        unicode_desc = "配置工具 - Configuration Tool 🚀"
+
+        with pytest.raises(SystemExit) as exc_info:
+            build_config(SimpleConfig, args=["--help"], description=unicode_desc)
+
+        assert exc_info.value.code == 0
+        captured = capsys.readouterr()
+        # Check for parts of the unicode string
+        assert "Configuration Tool" in captured.out