config-cli-gui 0.2.9__tar.gz → 0.3.0__tar.gz

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/HISTORY.md

@@ -4,6 +4,26 @@ Changelog
 
 (unreleased)
 ------------
+- Docs: Update HISTORY.md for release 0.2.9. [Paul Magister]
+- Refactoring: config parameters will stay ordered like in the config.
+  [Paul Magister]
+- Refactoring: config parameters will stay ordered like in the config.
+  [Paul Magister]
+- Refactor cli.py, move logging into this project. [Paul Magister]
+- Docs: Update HISTORY.md for release 0.2.9. [Paul Magister]
+- Docs: Update HISTORY.md for release 0.2.10. [Paul Magister]
+- Docs: Update HISTORY.md for release 0.2.9. [Paul Magister]
+- Update README.md from docs/index.md. [github-actions]
+
+
+0.2.10 (2025-12-03)
+-------------------
+- Docs: Update HISTORY.md for release 0.2.10. [Paul Magister]
+
+
+0.2.9 (2025-12-03)
+------------------
+- Docs: Update HISTORY.md for release 0.2.9. [Paul Magister]
 - Spinbox for vector. [Paul Magister]
 - Better example, make get_image_font sensitive to dpi, [Paul Magister]
 

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: config-cli-gui
-Version: 0.2.9
+Version: 0.3.0
 Summary: Feature-rich Python project template for config-cli-gui.
 Author: pamagister
 Requires-Python: <3.12,>=3.10

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/README.md

@@ -30,11 +30,6 @@ You can install `config-cli-gui` using pip:
 pip install config-cli-gui
 ```
 
-## Contribution
-
-Refer to this how-to in the referenced project for getting started to install and develop on this project:
-https://github.com/pamagister/python-template-project
-
 ---
 
 ## ✨ Features
@@ -67,44 +62,27 @@ from config_cli_gui.config import (
     ConfigParameter,
 )
 from config_cli_gui.configtypes.color import Color
-from config_cli_gui.docs import DocumentationGenerator
-
+from config_cli_gui.configtypes.font import Font
+from config_cli_gui.configtypes.vector import Vector
 
-class CliConfig(ConfigCategory):
-    """CLI-specific configuration parameters."""
 
+class MiscConfig(ConfigCategory):
     def get_category_name(self) -> str:
-        return "cli"
-
-    # Positional argument
-    input: ConfigParameter = ConfigParameter(
-        name="input",
-        value="",
-        help="Path to input (file or folder)",
-        required=True,
-        is_cli=True,
-    )
+        return "misc"
 
-    # Optional CLI arguments
-    output: ConfigParameter = ConfigParameter(
-        name="output",
-        value="",
-        help="Path to output destination",
+    some_numeric: ConfigParameter = ConfigParameter(
+        name="some_numeric",
+        value=int(42),
+        help="Example integer",
         is_cli=True,
     )
 
-    min_dist: ConfigParameter = ConfigParameter(
-        name="min_dist",
-        value=20,
-        help="Maximum distance between two waypoints",
-        is_cli=True,
+    some_vector: ConfigParameter = ConfigParameter(
+        name="some_vector",
+        value=Vector(1, 2, 3),
+        help="Example vector",
     )
 
-
-class MiscConfig(ConfigCategory):
-    def get_category_name(self) -> str:
-        return "misc"
-
     some_file: ConfigParameter = ConfigParameter(
         name="some_file",
         value=Path("some_file.txt"),
@@ -119,20 +97,46 @@ class MiscConfig(ConfigCategory):
 
     some_date: ConfigParameter = ConfigParameter(
         name="some_date",
-        value=datetime.now(),
+        value=datetime.fromisoformat("2025-12-31 10:30:45"),
         help="Date setting for the application",
     )
 
+    some_font: ConfigParameter = ConfigParameter(
+        name="some_font",
+        value=Font("DejaVuSans.ttf", size=12, color=Color(0, 0, 255)),
+        help="Font setting for the application",
+    )
+
+
+class AppConfig(ConfigCategory):
+    """Application-specific configuration parameters."""
+
+    def get_category_name(self) -> str:
+        return "app"
+
+    log_level: ConfigParameter = ConfigParameter(
+        name="log_level",
+        value="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Logging level for the application",
+    )
+
+    log_file_max_size: ConfigParameter = ConfigParameter(
+        name="log_file_max_size",
+        value=10,
+        help="Maximum log file size in MB before rotation",
+    )
+
 
 class ProjectConfigManager(ConfigManager):  # Inherit from ConfigManager
     """Main configuration manager that handles all parameter categories."""
 
-    cli: CliConfig
+    app: AppConfig
     misc: MiscConfig
-
+    
     def __init__(self, config_file: str | None = None, **kwargs):
         """Initialize the configuration manager with all parameter categories."""
-        categories = (CliConfig(), MiscConfig())
+        categories = (MiscConfig(), AppConfig())
         super().__init__(categories, config_file, **kwargs)
 
 

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/config.yaml

@@ -1,63 +1,60 @@
+cli:
+  # Path to input (file or folder) | type=str | [CLI]
+  input: ''
+  # Path to output destination | type=str | [CLI]
+  output: ''
+  # Maximum distance between two waypoints | type=int | [CLI]
+  min_dist: 20
+  # Extract starting points of each track as waypoint | type=bool | [CLI] | choices=[True, False]
+  extract_waypoints: true
+  # Include elevation data in waypoints | type=bool | [CLI] | choices=[True, False]
+  elevation: false
 app:
   # Date format to use | type=str
   date_format: '%Y-%m-%d'
-  # Enable logging to console | type=bool | choices=[True, False]
-  enable_console_logging: true
-  # Enable logging to file | type=bool | choices=[True, False]
-  enable_file_logging: true
-  # Number of backup log files to keep | type=int
-  log_backup_count: 5
+  # Logging level for the application | type=str | choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
+  log_level: INFO
   # Maximum log file size in MB before rotation | type=int
   log_file_max_size: 10
+  # Number of backup log files to keep | type=int
+  log_backup_count: 5
   # Log message format style | type=str | choices=['simple', 'detailed', 'json']
   log_format: detailed
-  # Logging level for the application | type=str | choices=['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL']
-  log_level: INFO
   # Maximum number of worker threads | type=int
   max_workers: 4
-cli:
-  # Include elevation data in waypoints | type=bool [CLI] | choices=[True, False]
-  elevation: false
-  # Extract starting points of each track as waypoint | type=bool [CLI] | choices=[True, False]
-  extract_waypoints: true
-  # Path to input (file or folder) | type=str [CLI]
-  input: ''
-  # Maximum distance between two waypoints | type=int [CLI]
-  min_dist: 20
-  # Path to output destination | type=str [CLI]
-  output: ''
+  # Enable logging to file | type=bool | choices=[True, False]
+  enable_file_logging: true
+  # Enable logging to console | type=bool | choices=[True, False]
+  enable_console_logging: true
 gui:
-  # Automatically scroll to the newest log entries | type=bool | choices=[True, False]
-  auto_scroll_log: true
+  # GUI theme setting | type=str | choices=['light', 'dark', 'auto']
+  theme: light
+  # Default window width | type=int
+  window_width: 800
+  # Default window height | type=int
+  window_height: 600
   # Height of the log window in pixels | type=int
   log_window_height: 200
+  # Automatically scroll to the newest log entries | type=bool | choices=[True, False]
+  auto_scroll_log: true
   # Maximum number of log lines to keep in GUI | type=int
   max_log_lines: 1000
   # Point in 2D space | type=Vector
   point2D: (7, 11)
   # Point in 3D space | type=Vector
   point3D: (1.2, 3.4, 5.6)
-  # GUI theme setting | type=str | choices=['light', 'dark', 'auto']
-  theme: light
-  # Default window height | type=int
-  window_height: 600
-  # Default window width | type=int
-  window_width: 800
 misc:
-  # Color setting for the application | type=Color
-  some_color: '#ff0000'
-  # Date setting for the application | type=datetime
-  some_date: '2025-12-31T10:30:45'
-  # Path to the file to use | type=PosixPath
-  some_file: some_file.txt
-  # Font setting for the application | type=Font
-  some_font:
-  - DejaVuSans.ttf
-  - 12
-  - '#0000ff'
   # Example integer | type=int
   some_numeric: 42
   # Example vector 2D | type=Vector
   some_vector2d: (1, 2)
   # Example vector 3D | type=Vector
-  some_vector3d: (1.1, 2.2, 3.3)
+  some_vector3d: (1.1, 2.2, 3.3)
+  # Path to the file to use | type=PosixPath
+  some_file: some_file.txt
+  # Color setting for the application | type=Color
+  some_color: '#ff0000'
+  # Date setting for the application | type=datetime
+  some_date: '2025-12-31T10:30:45'
+  # Font setting for the application | type=Font
+  some_font: 'DejaVuSans.ttf, 12, #0000ff'

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/src/config_cli_gui/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.9'
-__version_tuple__ = version_tuple = (0, 2, 9)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'gc34b684af'
+__commit_id__ = commit_id = 'g10ea5e914'

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/src/config_cli_gui/cli.py

@@ -4,6 +4,7 @@
 import argparse
 import traceback
 from collections.abc import Callable
+from logging import Logger, getLogger
 from typing import Any
 
 from config_cli_gui.config import ConfigManager
@@ -103,13 +104,17 @@ class CliGenerator:
     # ----------------------------------------------------------------------
     def run_cli(
         self,
-        main_function: Callable[[ConfigManager], int],
+        main_function: Callable[[ConfigManager, Logger], int],
         description: str = None,
-        validator: Callable[[ConfigManager], bool] = None,
+        validator: Callable[[ConfigManager, Logger], bool] = None,
+        logger: Logger = None,
     ) -> int:
         parser = self.create_argument_parser(description)
         args = parser.parse_args()
 
+        if logger is None:
+            logger = getLogger(self.app_name)
+
         # Load config_file only ONCE
         config = ConfigManager(
             categories=tuple(self.config_manager._categories.values()),
@@ -121,17 +126,17 @@ class CliGenerator:
         config.apply_overrides(overrides)
 
         # Optional validation
-        if validator and not validator(config):
-            print("Configuration validation failed.")
+        if validator and not validator(config, logger):
+            logger.error("Configuration validation failed.")
             return 1
 
         # Execute main
         try:
-            return main_function(config)
+            return main_function(config, logger)
         except KeyboardInterrupt:
-            print("Interrupted.")
+            logger.info("Interrupted.")
             return 130
         except Exception as e:
-            print(f"Unexpected error: {e}")
-            traceback.print_exc()
+            logger.error(f"Unexpected error: {e}")
+            logger.debug(traceback.format_exc())
             return 1

config_cli_gui-0.3.0/src/config_cli_gui/config.py

@@ -0,0 +1,251 @@
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import BaseModel
+
+from config_cli_gui.configtypes.color import Color
+from config_cli_gui.configtypes.font import Font
+from config_cli_gui.configtypes.vector import Vector
+
+
+@dataclass
+class ConfigParameter:
+    """Represents a single configuration parameter with metadata."""
+
+    name: str
+    value: Any
+    choices: list[Any] | None = None
+    help: str = ""
+    cli_arg: str | None = None
+    required: bool = False
+    is_cli: bool = False
+    category: str = "general"
+
+    def __post_init__(self):
+        if self.is_cli and self.cli_arg is None and not self.required:
+            self.cli_arg = f"--{self.name}"
+        if isinstance(self.value, bool) and self.choices is None:
+            self.choices = [True, False]
+
+    @property
+    def type_(self) -> type[Any]:
+        """Return the Python type of this parameter’s value."""
+        return type(self.value)
+
+
+class ConfigCategory(BaseModel, ABC):
+    """Base class for configuration categories."""
+
+    @abstractmethod
+    def get_category_name(self) -> str:
+        """Return the unique name for this configuration category."""
+        pass
+
+    def get_parameters(self) -> list[ConfigParameter]:
+        """Return all `ConfigParameter` instances from this category."""
+        params = []
+        for value in vars(self).values():  # faster, only instance attrs
+            if isinstance(value, ConfigParameter):
+                value.category = self.get_category_name()
+                params.append(value)
+        return params
+
+
+class ConfigSerializer:
+    """Handles serialization and deserialization of custom config types."""
+
+    TYPE_MAPPING = {
+        Font: {
+            "to_serializable": lambda v: v.to_str(),
+            "from_serializable": lambda v: Font.from_list(v)
+            if isinstance(v, list)
+            else Font.from_str(v),
+        },
+        Color: {
+            "to_serializable": lambda v: v.to_hex(),
+            "from_serializable": lambda v: Color.from_list(v)
+            if isinstance(v, list)
+            else (Color.from_hex(v) if isinstance(v, str) else v),
+        },
+        Vector: {
+            "to_serializable": lambda v: v.to_str(),
+            "from_serializable": lambda v: Vector.from_list(v)
+            if isinstance(v, list)
+            else (Vector.from_str(v) if isinstance(v, str) else v),
+        },
+        Path: {
+            "to_serializable": lambda v: str(v.as_posix()),
+            "from_serializable": lambda v: Path(v) if isinstance(v, str) else v,
+        },
+        datetime: {
+            "to_serializable": lambda v: v.isoformat(),
+            "from_serializable": lambda v: datetime.fromisoformat(v) if isinstance(v, str) else v,
+        },
+    }
+
+    def to_serializable(self, value: Any) -> Any:
+        """Convert a value to a serializable format."""
+        for type_class, methods in self.TYPE_MAPPING.items():
+            if isinstance(value, type_class):
+                return methods["to_serializable"](value)
+        return value
+
+    def from_serializable(self, value: Any, target_type: type[Any]) -> Any:
+        """Convert a value from a serializable format to its original type."""
+        for type_class, methods in self.TYPE_MAPPING.items():
+            if target_type == type_class:
+                return methods["from_serializable"](value)
+        return value
+
+
+class ConfigManager:
+    """Manages loading, saving, and accessing configuration categories."""
+
+    def __init__(
+        self,
+        categories: tuple[ConfigCategory, ...],
+        config_file: str | None = None,
+        **overrides: Any,
+    ):
+        self._categories: dict[str, ConfigCategory] = {}
+        self._serializer = ConfigSerializer()
+
+        for category in categories:
+            if not isinstance(category, ConfigCategory):
+                raise TypeError(f"Expected ConfigCategory instance, got {type(category)}")
+            self.add_category(category.get_category_name(), category)
+
+        if config_file:
+            self.load_from_file(config_file)
+
+        self.apply_overrides(overrides)
+
+    def add_category(self, name: str, category: ConfigCategory) -> None:
+        """Register a new configuration category."""
+        self._categories[name] = category
+        setattr(self, name, category)
+
+    def get_category(self, name: str) -> ConfigCategory | None:
+        """Retrieve a category by name."""
+        return self._categories.get(name)
+
+    def apply_overrides(self, overrides: dict[str, Any]) -> None:
+        """Apply keyword overrides in the format `category__param=value`."""
+        for key, value in overrides.items():
+            if "__" not in key:
+                continue
+            category_name, param_name = key.split("__", 1)
+            category = self._categories.get(category_name)
+            if category and hasattr(category, param_name):
+                param = getattr(category, param_name)
+                if isinstance(param, ConfigParameter):
+                    param.value = value
+                else:
+                    setattr(category, param_name, value)
+
+    def load_from_file(self, config_file: str) -> None:
+        """Load configuration from a YAML or JSON file."""
+        path = Path(config_file)
+        if not path.exists():
+            raise FileNotFoundError(f"Configuration file not found: {config_file}")
+
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f) if path.suffix.lower() in [".yml", ".yaml"] else json.load(f)
+
+        self._apply_config_data(data)
+
+    def _apply_config_data(self, data: dict[str, Any]) -> None:
+        """Apply loaded data to the configuration parameters."""
+        for category_name, category_data in data.items():
+            category = self._categories.get(category_name)
+            if not category:
+                continue
+            for param_name, param_value in category_data.items():
+                if hasattr(category, param_name):
+                    param: ConfigParameter = getattr(category, param_name)
+                    if isinstance(param, ConfigParameter):
+                        target_type = param.type_
+                        if isinstance(param.value, Path):
+                            target_type = Path
+                        deserialized_value = self._serializer.from_serializable(
+                            param_value, target_type
+                        )
+                        param.value = deserialized_value
+
+    def save_to_file(self, config_file: str, format_: str = "auto") -> None:
+        """Save the current configuration to a file."""
+        path = Path(config_file)
+        data = self.to_dict()
+
+        file_format = format_
+        if file_format == "auto":
+            file_format = "yaml" if path.suffix.lower() in [".yml", ".yaml"] else "json"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            if file_format == "yaml":
+                yaml.dump(data, f, indent=2, sort_keys=False)
+            else:
+                json.dump(data, f, indent=2)
+
+        if file_format == "yaml":
+            self._append_comments_to_yaml(path)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert all configuration categories to a dictionary."""
+        result: dict[str, dict[str, Any]] = {}
+        for category_name, category in self._categories.items():
+            result[category_name] = {}
+            for param in category.get_parameters():
+                value = self._serializer.to_serializable(param.value)
+                result[category_name][param.name] = value
+        return result
+
+    def get_all_parameters(self) -> list[ConfigParameter]:
+        """Return a flat list of all parameters from all categories."""
+        return [p for c in self._categories.values() for p in c.get_parameters()]
+
+    def get_cli_parameters(self) -> list[ConfigParameter]:
+        """Return a list of all parameters that are exposed to the CLI."""
+        return [p for p in self.get_all_parameters() if p.is_cli]
+
+    def _append_comments_to_yaml(self, path: Path) -> None:
+        """Append helpful metadata comments to the YAML file."""
+        lines = path.read_text(encoding="utf-8").splitlines()
+        new_lines = []
+        all_params = {p.name: p for p in self.get_all_parameters()}
+        current_category = ""
+
+        for line in lines:
+            stripped = line.strip()
+            if (
+                stripped.endswith(":")
+                and not stripped.startswith("#")
+                and line.lstrip() == stripped
+            ):
+                current_category = stripped[:-1]
+                new_lines.append(line)
+                continue
+
+            param_name = stripped.split(":")[0].strip()
+            if param_name in all_params:
+                param = all_params[param_name]
+                if param.category == current_category:
+                    indent = " " * (line.find(param_name))
+                    comment_parts = [param.help, f"type={param.type_.__name__}"]
+                    if param.is_cli:
+                        comment_parts.append("[CLI]")
+                    if param.choices:
+                        comment_parts.append(f"choices={param.choices}")
+
+                    comment = f"{indent}# " + " | ".join(filter(None, comment_parts))
+                    new_lines.append(comment)
+
+            new_lines.append(line)
+
+        path.write_text("\n".join(new_lines), encoding="utf-8")

{config_cli_gui-0.2.9 → config_cli_gui-0.3.0}/src/config_cli_gui/configtypes/font.py

@@ -54,6 +54,40 @@ class Font:
         )
         return cls(str(font_type), float(size), color)
 
+    def to_str(self) -> str:
+        return f"{self.name}, {self.size}, {self.color.to_hex()}"
+
+    @classmethod
+    def from_str(cls, font_init_str: str) -> "Font":
+        """
+        Parses a string of the form:
+            "FontName, size, #rrggbb"
+        or alternative color formats.
+        """
+        if not isinstance(font_init_str, str):
+            return cls("Arial", 12, Color(0, 0, 0))
+
+        parts = [p.strip() for p in font_init_str.split(",")]
+
+        # at least name, size, color
+        if len(parts) < 3:
+            return cls("Arial", 12, Color(0, 0, 0))
+
+        # parse font name
+        font_name = parts[0]
+
+        # parse size
+        try:
+            size = float(parts[1])
+        except ValueError:
+            size = 12.0
+
+        # parse color
+        color_raw = ",".join(parts[2:]).strip()
+        color = Color.from_hex(color_raw)
+
+        return cls(font_name, size, color)
+
     def get_image_font(self, dpi=25.4) -> ImageFont.FreeTypeFont:
         """
         Return a PIL FreeTypeFont, with fallback to default.
@@ -77,4 +111,4 @@ class Font:
         return f"Font(type='{self.name}', size={self.size}, color={self.color!r})"
 
     def __str__(self) -> str:
-        return f"{self.name}, {self.size}pt, {self.color}"
+        return f"{self.to_str()}"