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

the1conf/flags.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class Flags:
+    """
+    Flags that control how to search for variable values in AppConfig.
+    These flags can be set globally in the AppConfig object or locally when calling resolve_vars() or
+    per config variables.
+
+    Not None flag values override other values with the following precedence:
+        ConfigVariableDef > resolve_vars() parameters > AppConfig global flags.
+    Which means that a not None value in a ConfVarDef directive will overrride a global flag value defined in AppConfig. And also that a None value in a ConfVarDef directive
+    will not override the value set in resolve_vars() parameters or an AppConfig global flags.
+
+    Attributes:
+        no_env_search (bool|None): don't search values in the environment.
+        no_value_search (bool|None): don't search values in the values dict.
+        no_conffile_search (bool|None): don't search values in the configuration file.
+        no_search (bool|None): don't search values in any location.
+        click_key_conversion (bool|None): use the variable name converted to lower case and with dashes converted to underscores as
+            the key to search in values.
+        allow_override (bool|None): allow overriding variable in the configuration when calling resolve_vars.
+        mandatory (bool|None): raise exception when no value is found for a variable. Default is True.
+    """
+
+    _no_env_search: bool | None
+    _no_value_search: bool | None
+    _no_conffile_search: bool | None
+    _no_search: bool | None
+    _click_key_conversion: bool | None
+    _allow_override: bool | None
+
+    def __init__(
+        self,
+        *,
+        no_env_search: Optional[bool] = None,
+        no_value_search: Optional[bool] = None,
+        no_conffile_search: Optional[bool] = None,
+        no_search: Optional[bool] = None,
+        click_key_conversion: Optional[bool] = None,
+        allow_override: Optional[bool] = None,
+    ) -> None:
+        self._no_env_search = no_env_search
+        self._no_value_search = no_value_search
+        self._no_conffile_search = no_conffile_search
+        self._no_search = no_search
+        if self._no_search:
+            self._no_env_search = True
+            self._no_value_search = True
+            self._no_conffile_search = True
+        self._click_key_conversion = click_key_conversion
+        self._allow_override = allow_override
+
+    def merge(self, *, inplace: bool = False, other: Flags) -> Flags | None:
+        """
+        Merge the current flags with the given flags.
+        If inplace is True then modify the current object, otherwise return a new Flags object.
+
+        Flags given as parameters have precedence over the current object values if they are not None.
+        """
+        cur_no_search: Optional[bool]
+        cur_no_env_search: Optional[bool]
+        cur_no_value_search: Optional[bool]
+        cur_no_conffile_search: Optional[bool]
+        cur_click_key_conversion: Optional[bool]
+        cur_allow_override: Optional[bool]
+
+        cur_no_search = (
+            other._no_search if other._no_search is not None else self._no_search
+        )
+        if cur_no_search:
+            cur_no_env_search = True
+            cur_no_value_search = True
+            cur_no_conffile_search = True
+        else:
+            cur_no_env_search = (
+                other._no_env_search
+                if other._no_env_search is not None
+                else self._no_env_search
+            )
+            cur_no_value_search = (
+                other._no_value_search
+                if other._no_value_search is not None
+                else self._no_value_search
+            )
+            cur_no_conffile_search = (
+                other._no_conffile_search
+                if other._no_conffile_search is not None
+                else self._no_conffile_search
+            )
+        cur_click_key_conversion = (
+            other._click_key_conversion
+            if other._click_key_conversion is not None
+            else self._click_key_conversion
+        )
+        cur_allow_override = (
+            other._allow_override
+            if other._allow_override is not None
+            else self._allow_override
+        )
+        if not inplace:
+            return Flags(
+                no_env_search=cur_no_env_search,
+                no_value_search=cur_no_value_search,
+                no_conffile_search=cur_no_conffile_search,
+                no_search=cur_no_search,
+                click_key_conversion=cur_click_key_conversion,
+                allow_override=cur_allow_override,
+            )
+        else:
+            self._no_env_search = cur_no_env_search
+            self._no_value_search = cur_no_value_search
+            self._no_conffile_search = cur_no_conffile_search
+            self._no_search = cur_no_search
+            self._click_key_conversion = cur_click_key_conversion
+            self._allow_override = cur_allow_override
+            return None
+
+    @property
+    def no_env_search(self) -> bool:
+        return False if self._no_env_search is None else self._no_env_search
+
+    @property
+    def no_value_search(self) -> bool:
+        return False if self._no_value_search is None else self._no_value_search
+
+    @property
+    def no_conffile_search(self) -> bool:
+        return False if self._no_conffile_search is None else self._no_conffile_search
+
+    @property
+    def no_search(self) -> bool:
+        return False if self._no_search is None else self._no_search
+
+    @property
+    def click_key_conversion(self) -> bool:
+        return False if self._click_key_conversion is None else self._click_key_conversion
+
+    @property
+    def allow_override(self) -> bool:
+        return False if self._allow_override is None else self._allow_override

the1conf/solver.py

@@ -0,0 +1,346 @@
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any, Callable, Iterable, Mapping, Optional, Sequence, cast
+from .config_var import ConfigVarDef, Flags
+from .attr_dict import AttrDict
+from .utils import AppConfigException, Undefined, _undef, is_sequence, PathType
+from .var_substitution import render_template, resolve_candidate_list
+from pydantic import TypeAdapter, ValidationError
+from pathlib import Path
+
+
+class Solver:
+    """Class responsible for solving configuration variables values
+    according to the defined search order and applying transformations and validations."""
+
+    _logger = logging.getLogger(__name__)
+    _local_flags: Flags
+    _values_map: Mapping[str, Any]
+    """ The values provided directly to the AppConfig instance."""
+    _conffile_values_map: Optional[Mapping[str, Any]] = None
+    """ The values found in the configuration file."""
+    _eval_runner: Callable[[Callable[[str, Any, Any], Any], str, Any], Any]
+    """ The function that will run the evaluation of callables for default values and transformations."""
+    _var_solved: AttrDict
+    """ currently solved config var. Used to handle dependencies between variables and variable substitution """
+
+    def __init__(
+        self,
+        *,
+        flags: Flags,
+        values_map: Mapping[str, Any],
+        eval_runner: Callable[[Callable[[str, Any, Any], Any], str, Any], Any],
+        var_solved: AttrDict,
+        conffile_values_map: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        self._local_flags = flags
+        self._values_map = values_map
+        self._conffile_values_map = conffile_values_map
+        self._eval_runner = eval_runner
+        self._var_solved = var_solved
+
+    def set_conffile_values_map(
+        self, conffile_values_map: Optional[Mapping[str, Any]]
+    ) -> None:
+        """
+        Set or update the configuration file values map.
+        Allow to use the same solver with ou without configuration file.
+        """
+        self._conffile_values_map = conffile_values_map
+
+    @classmethod
+    def _find_var_in_dict(
+        cls, where: Mapping[Any, Any], var_name: str
+    ) -> Any | Undefined:
+        """
+        Search for var_name in a dictionary.
+        var_name contains dict keys separated by a dot (.) ie key1.key2.key3
+        The left side key key1 is search in the where directory, if it is found
+        and it is a dictionary then key2 is search in it and
+        all key are searched in sequence.
+        Returns _undef if not found, allowing to distinguish between None (explicit null) and missing.
+        """
+        cur_dic: Mapping[Any, Any] = where
+        for key in var_name.split("."):
+            # logger = logging.getLogger(f"{cls.__module__}.{cls.__name__}")
+            # logger.debug(f"searching for key: {key} in dict : {cur_val}")
+            if key in cur_dic:
+                cur_dic = cur_dic[key]
+                # logger.debug(f"Found key: {key} = {cur_val}")
+            else:
+                return _undef
+
+        return cur_dic
+
+    def resolve_confvar(
+        self, *, var_to_solve: ConfigVarDef, scopes: Optional[str | Iterable[str]]
+    ) -> Any:
+        """
+        Assign a value to the given ConfigVarDef according to the search order:
+        1. values mapping
+        2. environment variables
+        3. configuration file
+        4. default value
+        Applies transformations and validations as specified in the ConfigVarDef.
+        If its a Path variable, process relative paths, create directories if needed.
+        """
+        val_found: Path | str | None | list[Any] | Undefined = _undef
+        found = False
+
+        cur_flags = self._local_flags.merge(inplace=False, other=var_to_solve.flags)
+        assert cur_flags is not None
+
+        # if we are resolving the variables in some specific scopes (ie parameter scope has value)
+        # we check if the variable belongs to one of these scopes and if not we skip it, in this
+        # case the variable is said to be "out of scope" and has no existence.
+        if scopes is None and var_to_solve.scopes is not None:
+            return _undef
+        # if we are resolving the variable in some specific scopes (ie parameter scope has value) and the variable
+        # has also some scopes defined we check if there is at least one scope in common
+        if scopes is not None and var_to_solve.scopes is not None:
+            test_ctx = []
+            # put True in test_ctx for each scope that matches, False otherwise
+            if is_sequence(scopes):
+                test_ctx = [c in var_to_solve.scopes for c in scopes]
+            else:
+                test_ctx = [scopes in var_to_solve.scopes]
+
+            # test if there is any True in test_ctx which means that at least one scope matches
+            if not any(test_ctx):
+                return _undef
+        # if the variable has no scope and we are resolving in some specific scopes this means that
+        # the variable is common to all scopes so we process them but only once except if the flag
+        # allow_override is set to True
+        if var_to_solve.scopes is None and scopes is not None:
+            if not cur_flags.allow_override and var_to_solve.name in self._var_solved:
+                return _undef
+
+        #  Searching variable value in the values mapping
+        if (
+            self._values_map is not None
+            and not cur_flags.no_value_search
+            and var_to_solve.value_key is not None
+        ):
+            ctx = self._var_solved.to_dict()
+            # First Render value_key if needed
+
+            def value_checks(k: str) -> Any:
+                """check if the key k exists in the values_map and return its value or _undef"""
+                if cur_flags.click_key_conversion:
+                    k = k.lower().replace("-", "_")
+                return _undef if k not in self._values_map else self._values_map[k]
+
+            value_checked = resolve_candidate_list(
+                candidates=var_to_solve.value_key,
+                context=ctx,
+                check_exists=lambda k: value_checks(k),
+            )
+            # value_checked can be None meaning that the key exists in values_map with a None value which is the value to use
+            if value_checked != _undef:
+                # We found a key that exists in values_map and the checker has returned its value that can be None.
+                val_found = value_checked
+                found = True
+                self._logger.debug(
+                    f"{var_to_solve.name} -> Found in Values = {val_found}"
+                )
+
+        # Searching variable value in the environment variables
+        if (
+            not found
+            and not cur_flags.no_env_search
+            and var_to_solve.env_name is not None
+        ):
+            ctx = self._var_solved.to_dict()
+
+            def check_env(k: str) -> Any:
+                """check if the key k exists in the environment variables and return its value or _undef"""
+                res = os.getenv(k)
+                return _undef if res is None else res
+
+            value_checked = resolve_candidate_list(
+                candidates=var_to_solve.env_name, context=ctx, check_exists=check_env
+            )
+            # in env None means not found (there is no _undef in this case and the value can't be None)
+            if value_checked != _undef:
+                val_found = value_checked
+                found = True
+                self._logger.debug(f"{var_to_solve.name} -> Found in Env = {val_found}")
+
+        #  Searching variable value in the configuration file
+        if (
+            not found
+            and not cur_flags.no_conffile_search
+            and self._conffile_values_map is not None
+            and var_to_solve.file_key is not None
+        ):
+            ctx = self._var_solved.to_dict()
+
+            def check_file(k: str) -> Any:
+                """check if the key k exists in configuration file and return its value or _undef"""
+                if self._conffile_values_map is None:
+                    return False
+                return self._find_var_in_dict(self._conffile_values_map, k)
+
+            value_checked = resolve_candidate_list(
+                candidates=var_to_solve.file_key, context=ctx, check_exists=check_file
+            )
+            # None is a valid value from config file, _undef means not found
+            if value_checked != _undef:
+                val_found = value_checked
+                found = True
+                self._logger.debug(
+                    f"{var_to_solve.name} -> Found in Configuration File = {val_found}"
+                )
+
+        #  Setting variable value to the default value if defined.
+        if (
+            var_to_solve.name not in self._var_solved
+            and not found
+            and var_to_solve.default is not _undef
+        ):
+            if var_to_solve.default is not None and callable(var_to_solve.default):
+                val_found = self._eval_runner(
+                    var_to_solve.default, var_to_solve.name, None
+                )
+            else:
+                val_found = render_template(
+                    var_to_solve.default, self._var_solved.to_dict()
+                )
+            found = True
+            self._logger.debug(
+                f"{var_to_solve.name} -> Found in Default Value = {val_found}"
+            )
+
+        # Raise exception if no value was found and variable is mandatory and if we have not
+        # already a value for this variable (in case of override with scopes for example)
+        if (
+            not found
+            and var_to_solve.mandatory
+            and var_to_solve.name not in self._var_solved
+        ):
+            raise AppConfigException(
+                f"No value for var {var_to_solve.name} in scope {scopes}"
+            )
+
+        if found:
+            if isinstance(val_found, Undefined):
+                raise AssertionError(
+                    "Internal error: val_found is _undef while found=True"
+                )
+            # spliting lists
+            if (
+                var_to_solve.split_to_list
+                and val_found is not None
+                and isinstance(val_found, str)
+            ):
+                sep: str = (
+                    ","
+                    if isinstance(var_to_solve.split_to_list, bool)
+                    else var_to_solve.split_to_list
+                )
+                val_found = val_found.split(sep)
+
+            # Transform the variable value if specified.
+            if var_to_solve.transform is not None:
+                if isinstance(var_to_solve.transform, str):
+                    ctx = self._var_solved.to_dict()
+                    ctx["value"] = val_found
+                    val_transfo = render_template(var_to_solve.transform, ctx)
+                else:
+                    val_transfo = self._eval_runner(
+                        var_to_solve.transform,
+                        var_to_solve.name,
+                        val_found,
+                    )
+                self._logger.debug(
+                    f"{var_to_solve.name} -> Value Transformed: {val_found} => {val_transfo}"
+                )
+                val_found = val_transfo
+
+            # Validate and cast the variable value using pydantic TypeAdapter
+            if var_to_solve._type_info is not None and val_found is not None:
+                try:
+                    ta = TypeAdapter(var_to_solve._type_info)
+                    val_found = ta.validate_python(val_found)
+                except ValidationError as e:
+                    raise AppConfigException(
+                        f"Validation failed for var {var_to_solve.name}: {e}"
+                    )
+
+            # Make special treatment for paths
+            if (
+                not var_to_solve.no_dir_processing
+                and var_to_solve._type_info == Path
+                and val_found is not None
+            ):
+                new_val: list[Path] | Path | None = None
+                if is_sequence(val_found):
+                    # we need to consider the case where the variable is a list of Path
+                    new_val = []
+                    for cval in cast(Iterable, val_found):
+                        res = self._process_paths(
+                            value=cval, var=var_to_solve, var_solved=self._var_solved
+                        )
+                        new_val.append(res)
+                else:
+                    res = self._process_paths(
+                        value=val_found, var=var_to_solve, var_solved=self._var_solved
+                    )
+                    new_val = res
+                val_found = new_val
+
+        elif var_to_solve.name not in self._var_solved:
+            # in case of overiding and when on subsenquent call no value were found we don't want to erase a value
+            # found on a previous run. This can happen when some global flags are overriden or for variable without
+            # context.
+            val_found = None
+
+        return val_found
+
+    def _process_paths(
+        self, *, value: Any, var: ConfigVarDef, var_solved: AttrDict
+    ) -> Path:
+        """
+        Run the path processing for a single Path variable.
+        """
+        var_value: Path
+        if isinstance(value, str):
+            var_value = Path(value)
+        elif isinstance(value, Path):
+            var_value = value
+        else:
+            raise Exception("not a path")
+
+        res: Path = var_value
+        # First process the can_be_relative_to case.
+        if var.can_be_relative_to is not None:
+
+            if var_value.is_absolute():
+                res = var_value
+            else:
+                # resolving the root directory from which to be relative to.
+                can_be_relative = var.can_be_relative_to
+                root_dir: Path
+                if (
+                    isinstance(can_be_relative, str)
+                    and can_be_relative in var_solved
+                    and var_solved[can_be_relative] is not None
+                    and var_solved[can_be_relative] != _undef
+                ):
+                    root_dir = Path(var_solved[can_be_relative])
+                else:
+                    root_dir = Path(can_be_relative)
+                res = root_dir.joinpath(var_value)
+
+        # Expanding user home and resolving dots in path
+        res = res.expanduser().resolve()
+
+        # create directory if make_dirs is not None
+        if var.make_dirs:
+            if var.make_dirs == PathType.Dir:
+                res.mkdir(parents=True, exist_ok=True)
+            else:
+                res.parent.mkdir(parents=True, exist_ok=True)
+        return res

the1conf/utils.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+try:
+    import pytest
+except ImportError:
+    pytest = None
+
+import ast
+import inspect
+import textwrap
+from typing import TypeAlias, Any
+from enum import Enum, IntFlag, auto
+
+
+class AppConfigException(Exception):
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class NameSpace:
+    """Marker class for configuration namespaces.
+    Used to group configuration variables into nested namespaces within an AppConfig subclass.
+    See AppConfig documentation for more information.
+    """
+
+    pass
+
+
+class PathType(Enum):
+    Dir = auto()
+    File = auto()
+
+
+def get_attribute_docstrings(cls: type) -> dict[str, str]:
+    """
+    Extracts docstrings for class attributes by parsing the source code.
+    This allows using docstrings to populate ConfigVarDef.help.
+
+    currently PEP257 is not yet implemented in python standard library so we need to parse the source code ourselves.
+    This can slow down the class creation but this is done at class creation time only.
+    """
+    docstrings = {}
+    try:
+        source = inspect.getsource(cls)
+        # Deduct to handle nested classes indentation
+        source = textwrap.dedent(source)
+    except (OSError, TypeError):
+        # Source code not available (e.g. dynamic class, REPL, compiled files)
+        return {}
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return {}
+
+    # We look for the ClassDef in the parsed source.
+    # Since inspect.getsource(cls) returns the class definition itself,
+    # the first node in body should be the ClassDef.
+    for node in tree.body:
+        if isinstance(node, ast.ClassDef):
+            for i, item in enumerate(node.body):
+                if isinstance(item, (ast.Assign, ast.AnnAssign)):
+                    # Check if the next node is an expression containing a string (docstring)
+                    if i + 1 < len(node.body):
+                        next_node = node.body[i + 1]
+                        if (
+                            isinstance(next_node, ast.Expr)
+                            and isinstance(next_node.value, ast.Constant)
+                            and isinstance(next_node.value.value, str)
+                        ):
+                            docstring = next_node.value.value.strip()
+
+                            targets = []
+                            if isinstance(item, ast.Assign):
+                                targets = item.targets
+                            elif isinstance(item, ast.AnnAssign):
+                                targets = [item.target]
+
+                            for target in targets:
+                                if isinstance(target, ast.Name):
+                                    docstrings[target.id] = docstring
+            # We found the class def, no need to continue in top level
+            break
+
+    return docstrings
+
+
+def is_sequence(obj: Any) -> bool:
+    """test if obj is a sequence (list, tuple, etc...) but not a string"""
+    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 _UndefinedSentinel:
+    pass
+
+
+Undefined: TypeAlias = _UndefinedSentinel
+_undef: Undefined = _UndefinedSentinel()
+
+
+if pytest:
+    pass

the1conf/var_substitution.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import jinja2
+from typing import Any, Callable, Mapping, Optional, Sequence, Union, cast
+from .utils import is_sequence, _undef
+
+RenderContext = Mapping[str, Any]
+
+
+def render_template(value: Union[str, Any], context: RenderContext) -> Any:
+    """
+    Render a string as a jinja2 template using the provided context.
+    If value is not a string, return it as is.
+    """
+    if isinstance(value, str):
+        return jinja2.Template(value).render(context)
+    return value
+
+
+def resolve_candidate_list(
+    *,
+    candidates: Optional[Union[str, Sequence[str]]],
+    context: RenderContext,
+    check_exists: Optional[Callable[[str], Any]] = None,
+) -> Optional[Any]:
+    """
+    Resolve a list of candidate strings (which can be Jinja2 templates) to find the first valid one.
+
+    Args:
+        candidates: A single string or a list of strings (potentially templates).
+        context: The context used for rendering templates.
+        check_exists: An optional predicate to validate the rendered string.
+                      returns _undef if not valid, or the value to return if valid.
+    Returns:
+        The first successfully resolved and validated candidate string or the first not None value return by check_exists, or None if no match is found.
+    """
+    if candidates is None:
+        return None
+
+    candidates_list: list[str] = []
+    if isinstance(candidates, str):
+        candidates_list = [candidates]
+    elif is_sequence(candidates):
+        candidates_list = cast(list[str], candidates)
+
+    for raw_candidate in candidates_list:
+        rendered = render_template(raw_candidate, context)
+        if rendered is None:
+            continue
+
+        if isinstance(rendered, str):
+            if check_exists is not None:
+                res = check_exists(rendered)
+                if res != _undef:
+                    return res
+            else:
+                return rendered
+
+    return _undef