config-cli-gui 0.1.2__tar.gz → 0.1.4__tar.gz

{config_cli_gui-0.1.2 → config_cli_gui-0.1.4}/.idea/runConfigurations/config_generate.xml

@@ -13,7 +13,7 @@
     <option name="ADD_CONTENT_ROOTS" value="true" />
     <option name="ADD_SOURCE_ROOTS" value="true" />
     <EXTENSION ID="PythonCoverageRunConfigurationExtension" runner="coverage.py" />
-    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/tests/example_project/config/config.py" />
+    <option name="SCRIPT_NAME" value="$PROJECT_DIR$/tests/example_project/config/config_example.py" />
     <option name="PARAMETERS" value="" />
     <option name="SHOW_COMMAND_LINE" value="false" />
     <option name="EMULATE_TERMINAL" value="false" />

config_cli_gui-0.1.4/HISTORY.md

@@ -0,0 +1,50 @@
+Changelog
+=========
+
+
+(unreleased)
+------------
+- Update README.md from docs/index.md. [github-actions]
+- Feat #5: extensive renaming and adjustments. [Paul Magister]
+- Feat #5: extensive renaming. [Paul Magister]
+- Feat #5: extensive renaming. [Paul Magister]
+
+
+0.1.2 (2025-06-23)
+------------------
+- Feat #5: improve dialog. [Paul Magister]
+- Feat #5: Bugfig: use specific dialog for path parameters. [Paul
+  Magister]
+- Fix #4: fix test. [Paul Magister]
+- Fix #4: write yaml file with nicely with comments. [Paul Magister]
+- Fix #4: add comments to the yaml. [Paul Magister]
+- Fix #4: make new special datatypes work (Color, Path): correct
+  load/save lifecycle. [Paul Magister]
+- Feat #3: some advanced parameter types as example. [Paul Magister]
+- Feat #3: delete build workflow since it is not necessary for the lib.
+  [Paul Magister]
+- Feat #3: add verbose and quiet doc to auto generated config. [Paul
+  Magister]
+
+
+0.1.1 (2025-06-22)
+------------------
+- Feat #3: avoid type_ [Paul Magister]
+- Feat #3: Improved paramter types: [Paul Magister]
+- Feat #3: Improved paramter types: * move example project to tests *
+  remove type_ * add improved widgets to gui_generator.py * separate
+  module for docs_generator.py. [Paul Magister]
+
+
+0.1.0 (2025-06-22)
+------------------
+- Remove unnecessary example files and deps. [Paul Magister]
+- Update README.md from docs/index.md. [github-actions]
+- Fix doc: formatting. [Paul Magister]
+
+
+0.0.2 (2025-06-22)
+------------------
+- Remove _version.py. [Paul Magister]
+
+

{config_cli_gui-0.1.2 → config_cli_gui-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: config-cli-gui
-Version: 0.1.2
+Version: 0.1.4
 Summary: Feature-rich Python project template for config-cli-gui.
 Author: pamagister
 Requires-Python: <3.12,>=3.10
@@ -78,79 +78,74 @@ pip install config-cli-gui
 Start by defining your application's configuration parameters in a central `config.py` file within your project. You will inherit from `config-cli-gui`'s `GenericConfigManager` and `BaseConfigCategory`.
 
 ```python
-# my_project/config.py
-from config_cli_gui.config import ConfigParameter, GenericConfigManager, BaseConfigCategory
-from pydantic import Field # Make sure pydantic is installed
-
-class MyCliConfig(BaseConfigCategory):
-    """CLI-specific parameters for MyProject."""
-    input_path: ConfigParameter = ConfigParameter(
-        name="input_path",
+# my_project/config_example.py
+
+from config_cli_gui.config import (
+    ConfigCategory,
+    ConfigManager,
+    ConfigParameter,
+)
+
+
+class CliConfig(ConfigCategory):
+    """CLI-specific configuration parameters."""
+
+    def get_category_name(self) -> str:
+        return "cli"
+
+    # Positional argument
+    input: ConfigParameter = ConfigParameter(
+        name="input",
         default="",
-        type_=str,
-        help="Path to the input file or directory",
+        help="Path to input (file or folder)",
         required=True,
-        cli_arg=None # Positional argument
+        is_cli=True,
     )
-    output_dir: ConfigParameter = ConfigParameter(
-        name="output_dir",
-        default="./output",
-        type_=str,
-        help="Directory for output files",
-        cli_arg="--output"
+
+    min_dist: ConfigParameter = ConfigParameter(
+        name="min_dist",
+        default=20,
+        help="Maximum distance between two waypoints",
+        is_cli=True,
     )
-    dry_run: ConfigParameter = ConfigParameter(
-        name="dry_run",
-        default=False,
-        type_=bool,
-        help="Perform a dry run without making actual changes",
-        cli_arg="--dry-run"
+
+    extract_waypoints: ConfigParameter = ConfigParameter(
+        name="extract_waypoints",
+        default=True,
+        help="Extract starting points of each track as waypoint",
+        is_cli=True,
     )
 
-class MyAppConfig(BaseConfigCategory):
-    """Application-wide settings."""
+
+class AppConfig(ConfigCategory):
+    """Application-specific configuration parameters."""
+
+    def get_category_name(self) -> str:
+        return "app"
+
     log_level: ConfigParameter = ConfigParameter(
         name="log_level",
         default="INFO",
-        type_=str,
-        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
-        help="Logging verbosity level"
-    )
-    max_threads: ConfigParameter = ConfigParameter(
-        name="max_threads",
-        default=4,
-        type_=int,
-        help="Maximum number of processing threads"
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Logging level for the application",
     )
 
-class MyGuiConfig(BaseConfigCategory):
-    """GUI-specific settings."""
-    theme: ConfigParameter = ConfigParameter(
-        name="theme",
-        default="dark",
-        type_=str,
-        choices=["light", "dark", "system"],
-        help="GUI theme"
-    )
-    window_size: ConfigParameter = ConfigParameter(
-        name="window_size",
-        default="800x600",
-        type_=str,
-        help="Initial GUI window size"
+    log_file_max_size: ConfigParameter = ConfigParameter(
+        name="log_file_max_size",
+        default=10,
+        help="Maximum log file size in MB before rotation",
     )
 
-class ProjectConfigManager(GenericConfigManager):
-    """Main configuration manager for MyProject."""
-    cli: MyCliConfig = Field(default_factory=MyCliConfig)
-    app: MyAppConfig = Field(default_factory=MyAppConfig)
-    gui: MyGuiConfig = Field(default_factory=MyGuiConfig)
+
+class ProjectConfigManager(ConfigManager):  # Inherit from ConfigManager
+    """Main configuration manager that handles all parameter categories."""
+
+    categories = (CliConfig(), AppConfig())
 
     def __init__(self, config_file: str | None = None, **kwargs):
-        # Dynamically register categories for the generic manager
-        self.__class__.add_config_category("cli", MyCliConfig)
-        self.__class__.add_config_category("app", MyAppConfig)
-        self.__class__.add_config_category("gui", MyGuiConfig)
-        super().__init__(config_file, **kwargs)
+        """Initialize the configuration manager with all parameter categories."""
+        super().__init__(self.categories, config_file, **kwargs)
+
 
 ```
 
@@ -159,60 +154,76 @@ class ProjectConfigManager(GenericConfigManager):
 Use the generic CLI functions to parse command-line arguments based on your defined `CliConfig`.
 
 ```python
-# my_project/cli.py
-import argparse
-from my_project.config import ProjectConfigManager
-from config_cli_gui.cli import create_argument_parser, create_config_overrides_from_args
-
-def parse_my_args():
-    # Define any project-specific hardcoded CLI args (e.g., --version)
-    extra_cli_args = {
-        "--version": {"action": "version", "version": "MyProject 1.0.0", "help": "Show program's version number and exit."}
-    }
-
-    parser = create_argument_parser(
-        config_manager_class=ProjectConfigManager,
-        description="MyProject CLI application",
-        epilog="""
-Examples:
-  python -m my_project.cli my_input.txt --output ./results
-  python -m my_project.cli --config custom.yaml another_input.csv
-        """,
-        cli_category_name="cli", # The name of your CLI config category
-        extra_arguments=extra_cli_args
-    )
-    return parser.parse_args()
-
-def main_cli():
-    args = parse_my_args()
-
-    # Map generic flags like verbose/quiet to specific log levels if desired
-    log_level_map = {
-        "verbose": "DEBUG", # Assuming you added a --verbose flag in extra_cli_args
-        "quiet": "WARNING"  # Assuming you added a --quiet flag
-    }
-
-    cli_overrides = create_config_overrides_from_args(
-        args,
-        config_manager_class=ProjectConfigManager,
-        cli_category_name="cli",
-        log_level_map=log_level_map
+# my_project/cli_example.py
+from config_cli_gui.cli import CliGenerator
+from config_cli_gui.config import ConfigManager
+from tests.example_project.config.config_example import ProjectConfigManager
+from tests.example_project.core.base import BaseGPXProcessor
+from tests.example_project.core.logging import initialize_logging
+
+
+def run_main_processing(_config: ConfigManager) -> int:
+    """Main processing function that gets called by the CLI generator.
+
+    Args:
+        _config: Configuration manager with all settings
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    # Initialize logging system
+    logger_manager = initialize_logging(_config)
+    logger = logger_manager.get_logger("config_cli_gui.cli")
+
+    try:
+        # Log startup information
+        logger.info("Starting config_cli_gui CLI")
+        logger_manager.log_config_summary()
+
+        logger.info(f"Processing input")
+
+        # Create and run BaseGPXProcessor
+        processor = BaseGPXProcessor(
+            _config.get_category("cli").input.default,
+            _config.get_category("cli").output.default,
+            _config.get_category("cli").min_dist.default,
+            _config.get_category("app").date_format.default,
+            _config.get_category("cli").elevation.default,
+            logger=logger,
+        )
+
+        logger.info("Starting conversion process")
+
+        # Run the processing (adjust method name based on your actual implementation)
+        result_files = processor.compress_files()
+        logger.info(f"Successfully processed {result_files}")
+        return 0
+
+    except Exception as e:
+        logger.error(f"Processing failed: {e}")
+        logger.debug("Full traceback:", exc_info=True)
+        return 1
+
+
+def main():
+    """Main entry point for the CLI application."""
+    # Create the base configuration manager
+    config_manager = ProjectConfigManager()
+
+    # Create CLI generator
+    cli_generator = CliGenerator(config_manager=config_manager, app_name="config_cli_gui")
+
+    # Run the CLI with our main processing function
+    return cli_generator.run_cli(
+        main_function=run_main_processing,
+        description="Example CLI for config-cli-gui using the generic config framework.",
     )
 
-    # Initialize your project's configuration
-    config = ProjectConfigManager(
-        config_file=args.config if hasattr(args, "config") and args.config else None,
-        **cli_overrides
-    )
-
-    print(f"Input Path: {config.cli.input_path.default}")
-    print(f"Output Directory: {config.cli.output_dir.default}")
-    print(f"Dry Run: {config.cli.dry_run.default}")
-    print(f"Log Level: {config.app.log_level.default}")
-    # ... your application logic using 'config'
 
 if __name__ == "__main__":
-    main_cli()
+    import sys
+
+    sys.exit(main())
 ```
 
 ### 3\. Integrate GUI Settings Dialog
@@ -220,27 +231,29 @@ if __name__ == "__main__":
 The `SettingsDialog` from `config-cli-gui` (or your project's adapted version) can be used to easily create a settings window.
 
 ```python
-# my_project/gui.py (Simplified example)
+# my_project/gui_example.py (Simplified example)
 import tkinter as tk
-from my_project.config import ProjectConfigManager
-from config_cli_gui.gui_settings import SettingsDialog # Assuming gui_settings is part of the generic lib or adapted
+from tests.example_project.config.config_example import ProjectConfigManager
+from config_cli_gui.gui import GenericSettingsDialog  # Assuming gui_settings is part of the generic lib or adapted
+
 
 def open_settings_window(parent_root, config_manager: ProjectConfigManager):
-    dialog = SettingsDialog(parent_root, config_manager)
+    dialog = GenericSettingsDialog(parent_root, config_manager)
     parent_root.wait_window(dialog.dialog)
     # After dialog closes, config_manager will have updated values if 'OK' was clicked
     print("Settings updated or cancelled.")
-    print(f"New GUI Theme: {config_manager.gui.theme.default}")
+    print(f"New GUI Theme: {config_manager.get_category('gui').theme.default}")
+
 
 if __name__ == "__main__":
     root = tk.Tk()
-    root.withdraw() # Hide main window for this example
-    
+    root.withdraw()  # Hide main window for this example
+
     # Initialize your project's config manager
-    project_config = ProjectConfigManager() 
-    
+    project_config = ProjectConfigManager()
+
     open_settings_window(root, project_config)
-    
+
     root.destroy()
 ```
 
@@ -250,29 +263,27 @@ Use the static methods on your `ProjectConfigManager` to generate `config.yaml`,
 
 ```python
 # scripts/generate_docs.py (or similar script in your project)
-from my_project.config import ProjectConfigManager
+from tests.example_project.config.config_example import ProjectConfigManager
+from config_cli_gui.docs import DocumentationGenerator
 import os
 
 # Define output paths
 output_dir = "docs/generated"
 os.makedirs(output_dir, exist_ok=True)
 
-config_file_path = "config.yaml" # At the project root or similar
-cli_doc_path = os.path.join(output_dir, "cli.md")
-config_doc_path = os.path.join(output_dir, "config.md")
-
-print(f"Generating default config to: {config_file_path}")
-ProjectConfigManager.generate_default_config_file(config_file_path)
+default_config = "config.yaml"  # At the project root or similar
+default_cli_doc = os.path.join(output_dir, "cli.md")
+default_config_doc = os.path.join(output_dir, "config.md")
+_config = ProjectConfigManager()
+doc_gen = DocumentationGenerator(_config)
+doc_gen.generate_default_config_file(output_file=default_config)
+print(f"Generated: {default_config}")
 
-print(f"Generating general config documentation to: {config_doc_path}")
-ProjectConfigManager.generate_config_markdown_doc(config_doc_path)
+doc_gen.generate_config_markdown_doc(output_file=default_config_doc)
+print(f"Generated: {default_config_doc}")
 
-print(f"Generating CLI documentation to: {cli_doc_path}")
-ProjectConfigManager.generate_cli_markdown_doc(
-    output_file=cli_doc_path,
-    cli_category_name="cli", # Ensure this matches your CLI config category
-    cli_entry_point="python -m my_project.cli" # Your project's actual CLI entry point
-)
+doc_gen.generate_cli_markdown_doc(output_file=default_cli_doc)
+print(f"Generated: {default_cli_doc}")
 
 print("Documentation and default config generation complete.")
 ```

config_cli_gui-0.1.4/README.md

@@ -0,0 +1,264 @@
+<!-- This README.md is auto-generated from docs/index.md -->
+
+# Welcome to config-cli-gui
+
+**Unified Configuration and Interface Management**
+
+Provides a generic configuration framework that automatically generates both command-line interfaces and GUI settings dialogs from configuration parameters. 
+
+[![Github CI Status](https://github.com/pamagister/config-cli-gui/actions/workflows/main.yml/badge.svg)](https://github.com/pamagister/config-cli-gui/actions)
+[![GitHub release](https://img.shields.io/github/v/release/pamagister/config-cli-gui)](https://github.com/pamagister/config-cli-gui/releases)
+[![Read the Docs](https://readthedocs.org/projects/config-cli-gui/badge/?version=stable)](https://config-cli-gui.readthedocs.io/en/stable/)
+[![License](https://img.shields.io/github/license/pamagister/config-cli-gui)](https://github.com/pamagister/config-cli-gui/blob/main/LICENSE)
+[![GitHub issues](https://img.shields.io/github/issues/pamagister/config-cli-gui)](https://github.com/pamagister/config-cli-gui/issues)
+[![PyPI](https://img.shields.io/pypi/v/config-cli-gui)](https://pypi.org/project/config-cli-gui/)
+[![Downloads](https://pepy.tech/badge/config-cli-gui)](https://pepy.tech/project/config-cli-gui/)
+
+
+`config-cli-gui` is a Python library designed to streamline the management of application configurations, 
+generating command-line interfaces (CLIs), and dynamically creating graphical user interface (GUI) settings dialogs 
+from a single source of truth. It leverages Pydantic for robust parameter definition and offers 
+powerful features for consistent configuration across different application entry points.
+
+---
+
+## 🚀 Installation
+
+You can install `config-cli-gui` using pip:
+
+```bash
+pip install config-cli-gui
+```
+
+---
+
+## ✨ Features
+
+  * **Single Source of Truth**: Define all your application parameters in one place using simple, dataclass-like structures based on Pydantic's `BaseModel`. This ensures consistency and reduces errors across your application.
+  * **Categorized Configuration**: Organize your parameters into logical categories (e.g., `cli`, `app`, `gui`) for better structure and maintainability.
+  * **Dynamic CLI Generation**: Automatically generate `argparse`-compatible command-line arguments directly from your defined configuration parameters, including help texts, types, and choices.
+  * **Config File Management**: Easily load and save configurations from/to YAML or JSON files, allowing users to customize default settings.
+  * **GUI Settings Dialogs**: Dynamically create Tkinter-based settings dialogs for your application, allowing users to intuitively modify configuration parameters via a graphical interface.
+  * **Documentation Generation**: Generate detailed Markdown documentation for both your CLI options and all configuration parameters, keeping your user guides always up-to-date with your codebase.
+  * **Override System**: Supports robust overriding of configuration values via configuration files and command-line arguments, with clear precedence.
+
+---
+
+## 📚 Usage
+
+### 1\. Define Your Configuration
+
+Start by defining your application's configuration parameters in a central `config.py` file within your project. You will inherit from `config-cli-gui`'s `GenericConfigManager` and `BaseConfigCategory`.
+
+```python
+# my_project/config_example.py
+
+from config_cli_gui.config import (
+    ConfigCategory,
+    ConfigManager,
+    ConfigParameter,
+)
+
+
+class CliConfig(ConfigCategory):
+    """CLI-specific configuration parameters."""
+
+    def get_category_name(self) -> str:
+        return "cli"
+
+    # Positional argument
+    input: ConfigParameter = ConfigParameter(
+        name="input",
+        default="",
+        help="Path to input (file or folder)",
+        required=True,
+        is_cli=True,
+    )
+
+    min_dist: ConfigParameter = ConfigParameter(
+        name="min_dist",
+        default=20,
+        help="Maximum distance between two waypoints",
+        is_cli=True,
+    )
+
+    extract_waypoints: ConfigParameter = ConfigParameter(
+        name="extract_waypoints",
+        default=True,
+        help="Extract starting points of each track as waypoint",
+        is_cli=True,
+    )
+
+
+class AppConfig(ConfigCategory):
+    """Application-specific configuration parameters."""
+
+    def get_category_name(self) -> str:
+        return "app"
+
+    log_level: ConfigParameter = ConfigParameter(
+        name="log_level",
+        default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Logging level for the application",
+    )
+
+    log_file_max_size: ConfigParameter = ConfigParameter(
+        name="log_file_max_size",
+        default=10,
+        help="Maximum log file size in MB before rotation",
+    )
+
+
+class ProjectConfigManager(ConfigManager):  # Inherit from ConfigManager
+    """Main configuration manager that handles all parameter categories."""
+
+    categories = (CliConfig(), AppConfig())
+
+    def __init__(self, config_file: str | None = None, **kwargs):
+        """Initialize the configuration manager with all parameter categories."""
+        super().__init__(self.categories, config_file, **kwargs)
+
+
+```
+
+### 2\. Generate CLI
+
+Use the generic CLI functions to parse command-line arguments based on your defined `CliConfig`.
+
+```python
+# my_project/cli_example.py
+from config_cli_gui.cli import CliGenerator
+from config_cli_gui.config import ConfigManager
+from tests.example_project.config.config_example import ProjectConfigManager
+from tests.example_project.core.base import BaseGPXProcessor
+from tests.example_project.core.logging import initialize_logging
+
+
+def run_main_processing(_config: ConfigManager) -> int:
+    """Main processing function that gets called by the CLI generator.
+
+    Args:
+        _config: Configuration manager with all settings
+
+    Returns:
+        Exit code (0 for success, non-zero for error)
+    """
+    # Initialize logging system
+    logger_manager = initialize_logging(_config)
+    logger = logger_manager.get_logger("config_cli_gui.cli")
+
+    try:
+        # Log startup information
+        logger.info("Starting config_cli_gui CLI")
+        logger_manager.log_config_summary()
+
+        logger.info(f"Processing input")
+
+        # Create and run BaseGPXProcessor
+        processor = BaseGPXProcessor(
+            _config.get_category("cli").input.default,
+            _config.get_category("cli").output.default,
+            _config.get_category("cli").min_dist.default,
+            _config.get_category("app").date_format.default,
+            _config.get_category("cli").elevation.default,
+            logger=logger,
+        )
+
+        logger.info("Starting conversion process")
+
+        # Run the processing (adjust method name based on your actual implementation)
+        result_files = processor.compress_files()
+        logger.info(f"Successfully processed {result_files}")
+        return 0
+
+    except Exception as e:
+        logger.error(f"Processing failed: {e}")
+        logger.debug("Full traceback:", exc_info=True)
+        return 1
+
+
+def main():
+    """Main entry point for the CLI application."""
+    # Create the base configuration manager
+    config_manager = ProjectConfigManager()
+
+    # Create CLI generator
+    cli_generator = CliGenerator(config_manager=config_manager, app_name="config_cli_gui")
+
+    # Run the CLI with our main processing function
+    return cli_generator.run_cli(
+        main_function=run_main_processing,
+        description="Example CLI for config-cli-gui using the generic config framework.",
+    )
+
+
+if __name__ == "__main__":
+    import sys
+
+    sys.exit(main())
+```
+
+### 3\. Integrate GUI Settings Dialog
+
+The `SettingsDialog` from `config-cli-gui` (or your project's adapted version) can be used to easily create a settings window.
+
+```python
+# my_project/gui_example.py (Simplified example)
+import tkinter as tk
+from tests.example_project.config.config_example import ProjectConfigManager
+from config_cli_gui.gui import GenericSettingsDialog  # Assuming gui_settings is part of the generic lib or adapted
+
+
+def open_settings_window(parent_root, config_manager: ProjectConfigManager):
+    dialog = GenericSettingsDialog(parent_root, config_manager)
+    parent_root.wait_window(dialog.dialog)
+    # After dialog closes, config_manager will have updated values if 'OK' was clicked
+    print("Settings updated or cancelled.")
+    print(f"New GUI Theme: {config_manager.get_category('gui').theme.default}")
+
+
+if __name__ == "__main__":
+    root = tk.Tk()
+    root.withdraw()  # Hide main window for this example
+
+    # Initialize your project's config manager
+    project_config = ProjectConfigManager()
+
+    open_settings_window(root, project_config)
+
+    root.destroy()
+```
+
+### 4\. Generate Documentation and Default Config
+
+Use the static methods on your `ProjectConfigManager` to generate `config.yaml`, `cli.md`, and `config.md` files.
+
+```python
+# scripts/generate_docs.py (or similar script in your project)
+from tests.example_project.config.config_example import ProjectConfigManager
+from config_cli_gui.docs import DocumentationGenerator
+import os
+
+# Define output paths
+output_dir = "docs/generated"
+os.makedirs(output_dir, exist_ok=True)
+
+default_config = "config.yaml"  # At the project root or similar
+default_cli_doc = os.path.join(output_dir, "cli.md")
+default_config_doc = os.path.join(output_dir, "config.md")
+_config = ProjectConfigManager()
+doc_gen = DocumentationGenerator(_config)
+doc_gen.generate_default_config_file(output_file=default_config)
+print(f"Generated: {default_config}")
+
+doc_gen.generate_config_markdown_doc(output_file=default_config_doc)
+print(f"Generated: {default_config_doc}")
+
+doc_gen.generate_cli_markdown_doc(output_file=default_cli_doc)
+print(f"Generated: {default_cli_doc}")
+
+print("Documentation and default config generation complete.")
+```
+
+By following this structure, `config-cli-gui` provides a robust and maintainable foundation for your application's configuration needs.