the1conf 1.0.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

the1conf/app_config_meta.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import copy
+from collections import OrderedDict
+from inspect import getsource
+from typing import Any, Iterable, cast
+from .config_var import ConfigVarDef
+from .utils import get_attribute_docstrings, NameSpace
+
+
+class ConfigVarCollector:
+    """
+    Collector class to gather ConfigVarDef from AppConfig classes and their nested NameSpace classes.
+
+    This class helps in aggregating configuration variables from various sources during the class creation process.
+    It supports two main collection strategies:
+    1. Parsing the class definition directly (useful for mixins or the root class).
+    2. Inheriting already collected variables from a parent `AppConfig` class (optimization).
+
+    This class can be used as a context manager to ensure proper resource management.
+    """
+
+    _collected_vars: OrderedDict[str, ConfigVarDef]
+    _auto_prolog_var_names: list[str]
+
+    def __enter__(self):
+        """Return self to be used in the with statement"""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Cleanup resources on exit"""
+        self.close()
+
+    def __init__(self) -> None:
+        """Create a new ConfigVarCollector instance."""
+        self._collected_vars = OrderedDict()
+        self._auto_prolog_var_names = []
+
+    def close(self) -> None:
+        """
+        Clean up resources if needed.
+        """
+        self._collected_vars.clear()
+        self._auto_prolog_var_names.clear()
+
+    def _collect_config_vars(
+        self, owner: type, prefix: str = ""
+    ) -> Iterable[ConfigVarDef]:
+        """
+        Traverses ConfigVarDef defined in the owner class and its nested NameSpace classes.
+        Search for ConfigVarDef in the owner class __dict__ and yield them.
+        Attach the docstrings as help if help is not already defined and a docstring exists
+        for the attribute.
+        change its name by adding the namespace it is defined in as a prefix.
+        """
+        # extract docstrings from the class source code
+        docstrings = get_attribute_docstrings(owner)
+
+        # Inspect the class __dict__ to find ConfigVarDef defined in this class
+        for attr_name, value in owner.__dict__.items():
+            if isinstance(value, ConfigVarDef):
+                # Clone to update name with prefix
+                new_var = value
+
+                # If help is missing, try to use the docstring
+                if not new_var.help and attr_name in docstrings:
+                    new_var._help = docstrings[attr_name]
+
+                if prefix:
+                    # We need to access _name directly because we don't want to trigger the
+                    # descriptor __get__ method
+                    original_name = getattr(value, "_name", attr_name)
+                    new_var._name = f"{prefix}{original_name}"
+
+                yield new_var
+
+            elif (
+                isinstance(value, type)
+                and issubclass(value, NameSpace)
+                and value is not NameSpace
+            ):
+                # Recurse into nested NameSpace classes
+                yield from self._collect_config_vars(
+                    value, prefix=f"{prefix}{attr_name}."
+                )
+
+    def collect_on_class(self, owner: type) -> None:
+        """
+        Collect configuration variables by inspecting the class `__dict__` and its nested `NameSpace`s.
+
+        This method is used when the class does not have a `_config_var_defs` attribute yet,
+        typically for mixins (like AutoProlog) or during the initialization of the root `AppConfig` class.
+
+        It performs a deep scan:
+        - Iterates over the class attributes to find `ConfigVarDef` instances.
+        - Extracts docstrings to use as help text if needed.
+        - Recurses into nested `NameSpace` classes to collect variables defined within them.
+
+        Any variable found overrides an existing variable with the same name in the collection.
+        """
+        for vardef in self._collect_config_vars(owner):
+            attr_name = getattr(vardef, "_name", None)
+            if attr_name:
+                if attr_name in self._collected_vars:
+                    # Override previous definition
+                    self._collected_vars.pop(attr_name)
+                self._collected_vars[attr_name] = vardef
+                if attr_name and vardef.auto_prolog:
+                    if attr_name in self._auto_prolog_var_names:
+                        # in this case we need to move the var_name to the end of the list to preserve the order
+                        self._auto_prolog_var_names.remove(attr_name)
+                    self._auto_prolog_var_names.append(attr_name)
+
+    def collect_in_config_var_defs(self, owner: type) -> None:
+        """
+        Collect configuration variables from the `_config_var_defs` attribute of the owner class.
+
+        This method is used during inheritance when the parent class (`owner`) is already a subclass
+        of `AppConfig`. Since the parent has already computed its configuration variables (stored in
+        `_config_var_defs`), we can simply copy them instead of re-scanning the class.
+
+        This is much faster than `collect_on_class` and preserves the resolution order established
+        in the parent class.
+
+        Any variable found overrides an existing variable with the same name in the collection.
+        """
+        base_config_var_defs = getattr(owner, "_config_var_defs", None)
+        if not base_config_var_defs:
+            return
+
+        assert isinstance(base_config_var_defs, OrderedDict)
+
+        for var_name, var_def in cast(
+            OrderedDict[str, ConfigVarDef], base_config_var_defs
+        ).items():
+            # base_config_var_defs is the _config_var_defs dict. Loops on each of its elements and store them in the collected list
+            # For each one read its name. If the variable name is already in the collected list, it means that it has been
+            # defined in a parent class of the current inspected base class. So we remove the old definition and add the new one.
+            if var_name:
+                if var_name in self._collected_vars:
+                    # Override previous definition
+                    self._collected_vars.pop(var_name)
+                self._collected_vars[var_name] = var_def
+                if var_name and var_def.auto_prolog:
+                    if var_name in self._auto_prolog_var_names:
+                        # in this case we need to move the var_name to the end of the list to preserve the order
+                        self._auto_prolog_var_names.remove(var_name)
+                    self._auto_prolog_var_names.append(var_name)
+
+    def get_collected_vars(self) -> OrderedDict[str, ConfigVarDef]:
+        """
+        Get the collected configuration variables.
+        """
+        return self._collected_vars.copy()
+
+    def get_auto_prolog_var_names(self) -> list[str]:
+        """
+        Get only the collected configuration variables that have auto_prolog enabled.
+        """
+        return self._auto_prolog_var_names.copy()
+
+
+class AppConfigMeta(type):
+    """
+    Metaclass for AppConfig to handle initialization of the root class itself,
+    specifically to collect configuration variables from mixins that are not AppConfig subclasses.
+    """
+
+    def __init__(cls, name: str, bases: tuple[type, ...], attrs: dict[str, Any]) -> None:
+        """
+        Initialize the class object.
+
+        This method is part of the Python metaclass protocol. It is invoked after the class object `cls`
+        has been created (usually via `type.__new__`). It effectively acts as a constructor for the class
+        object itself.
+
+        Args:
+            name (str): The name of the class being created.
+            bases (tuple[type, ...]): A tuple containing the base classes of the class being created.
+            attrs (dict[str, Any]): A dictionary containing the class namespace (attributes and methods)
+                                  populated during the execution of the class body.
+                                  Keys are the names of the attributes (strings) and values are the
+                                  attribute values (methods, class variables, properties, etc.).
+        """
+        super().__init__(name, bases, attrs)
+
+        # Only perform root initialization for the AppConfig class itself.
+        # Subclasses use the standard __init_subclass__ mechanism.
+        if name == "AppConfig":
+            with ConfigVarCollector() as collector:
+                for base in reversed(cls.__mro__[1:-1]):
+                    # For the root class initialization we want to scan all parents.
+                    # We want to include variables from mixins like AutoProlog.
+                    # Since AppConfig is the root for this mechanism, its parents don't have _config_var_defs.
+                    # In the mro list AppConfig is always at index 0, so we can skip it safely and the last item is always object which we can also skip.
+
+                    collector.collect_on_class(base)
+                # Add own vars
+                collector.collect_on_class(cls)
+
+                cls._config_var_defs = collector.get_collected_vars()
+                cls._autoprolog_var_names = collector.get_auto_prolog_var_names()

the1conf/attr_dict.py

@@ -1,24 +1,11 @@
 from __future__ import annotations
 
-from collections.abc import Mapping, MutableMapping,Sequence, Iterator
-from typing import (Any, Callable, Optional,
-                    Protocol, Union, get_origin)
-
-import numpy as np
-import pandas as pd
-
-def is_sequence(obj: Any) -> bool:
-    """ test if obj is a sequence (list, tuple, etc...) but not a string in thte most general way"""
-    try:
-        len(obj)
-        obj[0:0]
-        return not isinstance(obj, str)
-    except KeyError:
-        return False
-    except TypeError:
-        return False # TypeError: object is not iterable
-    
-class AttrDict(MutableMapping):
+import logging
+from collections.abc import Iterator, Mapping
+from typing import Any, Optional
+
+
+class AttrDict:
     """
     class which properties can be accessed like a dict or like a propertie (.x) and vis/versa:
     if used like a Dict to set a value , if the key contains dots (.) it creates a hierarchy of AttrDict object.
@@ -39,9 +26,9 @@ class AttrDict(MutableMapping):
 
 
     class Test(AttrDict):
-    def __init__(self):
-        self.var1 = "var1"
-        self.__dict__["vardict"] = "vardict"
+        def __init__(self):
+            self.var1 = "var1"
+            self.__dict__["vardict"] = "vardict"
     t = Test()
     print (f"t['vardict'] = {t['vardict']}") # t['vardict'] = vardict
     print (f"t.vardict = {t.vardict}")       # t.vardict = vardict
@@ -61,6 +48,8 @@ class AttrDict(MutableMapping):
     print (f"t.a1 = {t.a1}")                 # t.a1 = {'a2': 'complexval'}
     """
 
+    _logger = logging.getLogger(__name__)
+
     def __init__(self, init: Optional[Mapping[Any, Any]] = None) -> None:
         if init is not None:
             self.__dict__.update(init)
@@ -127,15 +116,39 @@ class AttrDict(MutableMapping):
         """This method is called when an iterator is required for a container."""
         return self.__dict__.__iter__()
 
-    def update(  # type: ignore
-        self, other: Mapping[Any, Any], override: bool = False
-    ) -> None:
+    def update(self, other: Mapping[Any, Any], override: bool = False) -> None:
         if override:
             res = self.__dict__ | other  # type: ignore
         else:
             res = other | self.__dict__  # type: ignore
         self.__dict__ = res
 
+    def to_dict(self) -> dict[Any, Any]:
+        """
+        Return a copy of the AttrDict as a dictionary.
+        This is a recursive copy: nested AttrDict are also converted to dict.
+        """
+        d = {}
+        for k, v in self.__dict__.items():
+            if issubclass(type(v), AttrDict):
+                d[k] = v.to_dict()
+            else:
+                d[k] = v
+        return d
+
+    def has_value(self, key: str | None) -> bool:
+        """
+        Check if the AttrDict has a value for the given key.
+        The key can be a dotted path to access nested AttrDict.
+        """
+        if key is None:
+            return False
+        try:
+            _ = self[key]
+            return True
+        except Exception:
+            return False
+
     def _repr_with_ident(self, indent: int) -> list[str]:
         res = []
         indent_str = "\t" * indent

the1conf/auto_prolog.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Literal, Optional, Any
+
+from .config_var import configvar
+from .utils import PathType
+
+
+def _get_os_type() -> str:
+    if sys.platform.startswith("win"):
+        return "windows"
+    elif sys.platform.startswith("linux"):
+        return "linux"
+    elif sys.platform.startswith("darwin"):
+        return "macos"
+    return "unknown"
+
+
+class AutoProlog:
+    """
+    Automatic configuration for standard paths and environment variables.
+    This class defines configuration variables that will be accessible in any
+    subclass of AppConfig, providing sensible defaults based directories, Os type
+    and execution stage.
+
+    Variables defined:
+    - os_type: The operating system type (windows, linux, macos)
+    - user_home: The user's home directory, as returned by Path.home()
+      Must be used instead of '~' to ensure cross platform compatibility.
+    - xdg_data_home: Base directory for user specific data files (XDG standard)
+    - xdg_config_home: Base directory for user specific configuration files (XDG standard)
+    - xdg_cache_home: Base directory for user specific non-essential data files (XDG standard)
+    - xdg_state_home: Base directory for user specific state files (XDG standard)
+    - app_data: Application Data directory on Windows
+    - app_config: Application Config directory on Windows
+    - app_cache: Application Cache directory on Windows
+    - data_home: OS independent application data directory
+    - config_home: OS independent application configuration directory
+    - cache_home: OS independent application cache directory
+    - exec_stage: The execution stage, default to the string "dev", no restriction on its value
+        to let the user define its own stages.
+
+    Any of this variable can be overridden by a redefinition on a subclasse of AppConfig.
+    """
+
+    os_type: Literal["windows", "linux", "macos", "unknown"] = configvar(
+        default=lambda _, __, ___: _get_os_type(),
+        no_search=True,
+        help="The operating system type (windows, linux, macos)",
+        auto_prolog=True,
+    )
+
+    exec_stage: Any = configvar(
+        default=None,
+        type_info=str,
+        env_name=["EXEC_STAGE", "STAGE", "ENV"],
+        value_key=["exec_stage", "stage", "env"],
+        help="The execution stage (dev, prod, test)",
+        click_key_conversion=True,
+        allow_override=True,
+        auto_prolog=True,
+    )
+
+    user_home: Path = configvar(
+        default=lambda _, __, ___: Path.home(),
+        no_search=True,
+        help="The user's home directory",
+        auto_prolog=True,
+    )
+
+    # XDG Standards
+    xdg_data_home: Optional[Path] = configvar(
+        default=lambda _, c, __: (
+            c.user_home / ".local" / "share" if c.os_type != "windows" else None
+        ),
+        env_name="XDG_DATA_HOME",
+        help="Base directory for user specific data files",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    xdg_config_home: Optional[Path] = configvar(
+        default=lambda _, c, __: (
+            c.user_home / ".config" if c.os_type != "windows" else None
+        ),
+        env_name="XDG_CONFIG_HOME",
+        help="Base directory for user specific configuration files",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    xdg_cache_home: Optional[Path] = configvar(
+        default=lambda _, c, __: (
+            c.user_home / ".cache" if c.os_type != "windows" else None
+        ),
+        env_name="XDG_CACHE_HOME",
+        help="Base directory for user specific non-essential data files",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    xdg_state_home: Optional[Path] = configvar(
+        default=lambda _, c, __: (
+            c.user_home / ".local" / "state" if c.os_type != "windows" else None
+        ),
+        env_name="XDG_STATE_HOME",
+        help="Base directory for user specific state files",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    # Windows specific variables
+    app_data: Optional[Path] = configvar(
+        default=lambda _, c, __: (
+            c.user_home / "AppData" if c.os_type == "windows" else None
+        ),
+        env_name="APP_DATA",
+        help="Application Data directory on Windows",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    app_config: Optional[Path] = configvar(
+        default=lambda _, c, __: c.app_data / "Config" if c.app_data else None,
+        env_name="APP_CONFIG",
+        help="Application Config directory on Windows",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    app_cache: Optional[Path] = configvar(
+        default=lambda _, c, __: c.app_data / "Cache" if c.app_data else None,
+        env_name="APP_CACHE",
+        help="Application Cache directory on Windows",
+        no_value_search=True,
+        no_conffile_search=True,
+        auto_prolog=True,
+    )
+
+    # Unified variables
+    data_home: Path = configvar(
+        default=lambda _, c, __: (
+            c.app_data if c.os_type == "windows" else c.xdg_data_home
+        ),
+        click_key_conversion=True,
+        help="OS independent application data directory",
+        auto_prolog=True,
+        allow_override=True,
+    )
+
+    config_home: Path = configvar(
+        default=lambda _, c, __: (
+            c.app_config if c.os_type == "windows" else c.xdg_config_home
+        ),
+        click_key_conversion=True,
+        help="OS independent application configuration directory",
+        auto_prolog=True,
+        allow_override=True,
+    )
+
+    cache_home: Path = configvar(
+        default=lambda _, c, __: (
+            c.app_cache if c.os_type == "windows" else c.xdg_cache_home
+        ),
+        click_key_conversion=True,
+        help="OS independent application cache directory",
+        auto_prolog=True,
+        allow_override=True,
+    )

the1conf/click_option.py

@@ -1,35 +1,72 @@
 from __future__ import annotations
+
 from typing import Any, Callable
 
 import click
 
-from .app_config import ConfigVarDef, Undefined
+from .app_config import ConfigVarDef
+from .utils import Undefined, _undef
+
+
+class StringOrUndefined(click.ParamType):
+    name = "string"
+
+    def convert(self, value: Any, param: Any, ctx: Any) -> Any:
+        if value is _undef:
+            return value
+        return click.STRING.convert(value, param, ctx)
+
 
 def click_option(config_var: Any, **kwargs: Any) -> Callable[[Any], Any]:
-    """Wrappe click.option avec les métadonnées de ConfigVarDef."""
+    """Wrapper for click.option with the metadata from ConfigVarDef."""
     if not isinstance(config_var, ConfigVarDef):
         raise TypeError(f"click_option expects a ConfigVarDef, got {type(config_var)}")
-        
-    
-    # 1. Nom du flag (ex: my_var -> --my-var)
-    param_name = config_var.Name
-    flag_name = f"--{param_name.replace('_', '-').lower()}"
-    
+
+    # 1. Flag name (ex: my_var -> --my-var)
+    param_decls = []
+
+    keys = []
+    if config_var.value_key is None:
+        keys = [config_var.name]
+    elif isinstance(config_var.value_key, str):
+        keys = [config_var.value_key]
+    else:
+        keys = config_var.value_key
+
+    for key in keys:
+        if len(key) == 1:
+            param_decls.append(f"-{key}")
+        else:
+            param_decls.append(f"--{key.replace('_', '-').lower()}")
+
+    # Used as destination in the dict returned by click
+    param_name = keys[0]
+
     # 2. Documentation
-    if "help" not in kwargs and config_var.Help:
-        kwargs["help"] = config_var.Help
-
-    # 3. Contrainte stricte : Toujours des strings
-    # On écrase tout type passé pour garantir que resolve_vars reçoive du string.
-    kwargs["type"] = click.STRING
-    
-    # 4. Affichage du défaut sans l'appliquer
-    if "show_default" not in kwargs and config_var.Default is not Undefined and not callable(config_var.Default):
-        # On doit convertir en string sinon click interprete les bool/int comme des flags (True/False)
-        # qui lui disent "affiche le default" (qui est None ici), du coup il n'affiche rien.
-        kwargs["show_default"] = str(config_var.Default)
-
-    # Note: On ne passe PAS 'envvar' ni 'default'
-    
-    # On force le nom de destination pour qu'il matche la clé attendue par the1conf
-    return click.option(flag_name, param_name, **kwargs)
+    if "help" not in kwargs and config_var.help:
+        kwargs["help"] = config_var.help
+
+    # 3. Strict constraint: Always strings
+    # We overwrite any passed type to ensure that resolve_vars receives a string.
+    # We use a custom type to handle the `_undef` default value without converting it to string.
+    kwargs["type"] = StringOrUndefined()
+
+    # We set default to `_undef` to distinguish between "option not provided" (_undef)
+    # and "option provided with no value" (which shouldn't happen with string) or None.
+    # AppConfig handles `_undef` as "missing value" and will look for other sources (env, file, default).
+    kwargs["default"] = _undef
+
+    # 4. Display default without applying it
+    if (
+        "show_default" not in kwargs
+        and config_var.default is not Undefined
+        and not callable(config_var.default)
+    ):
+        # We must convert to string otherwise click interprets bool/int as flags (True/False)
+        # which tell it "show the default" (which is None here), so it displays nothing.
+        kwargs["show_default"] = str(config_var.default)
+
+    # Note: We do NOT pass 'envvar' nor 'default'
+
+    # We force the destination name to match the key expected by the1conf
+    return click.option(*param_decls, param_name, **kwargs)