pythagoras 0.24.4__py3-none-any.whl → 0.24.7__py3-none-any.whl

pythagoras/_070_protected_code_portals/fn_arg_names_checker.py

@@ -3,15 +3,21 @@ from typing import List, Set
 
 
 def check_if_fn_accepts_args(required_arg_names: List[str]|Set[str], fn: str) -> bool:
-    """
-    Analyzes the source code (string) `fn` of a Python function and determines
-    if it can accept the arguments named in `required_arg_names`.
+    """Determine whether a function can accept specific keyword argument names.
+
+    Analyzes the source code of a single Python function and checks whether
+    all required names could be passed as keyword arguments.
 
-    This will return True if:
-      - The function has a **kwargs parameter, or
-      - The function explicitly defines all of the names in `required_arg_names` as parameters.
+    Args:
+      required_arg_names: Iterable of parameter names that must be accepted.
+      fn: Source code string containing exactly one function definition.
 
-    Otherwise, returns False.
+    Returns:
+      True if the function has **kwargs or explicitly defines all required names
+      as keyword-acceptable parameters; otherwise False.
+
+    Raises:
+      ValueError: If no function definition is found or if multiple functions are present.
     """
 
     tree = ast.parse(fn)
@@ -19,6 +25,8 @@ def check_if_fn_accepts_args(required_arg_names: List[str]|Set[str], fn: str) ->
     func_def_nodes = [node for node in tree.body if isinstance(node, ast.FunctionDef)]
     if not func_def_nodes:
         raise ValueError("No function definition found in the provided source code.")
+    if not len(func_def_nodes) == 1:
+        raise ValueError("Multiple function definitions found in the provided source code.")
     func_def = func_def_nodes[0]
     args = func_def.args
 
@@ -26,14 +34,8 @@ def check_if_fn_accepts_args(required_arg_names: List[str]|Set[str], fn: str) ->
     if args.kwarg is not None:
         return True
 
-    # Collect all explicitly named parameters
-    param_names = set()
-    for arg in args.args:
-        param_names.add(arg.arg)
-    for kwarg in args.kwonlyargs:
-        param_names.add(kwarg.arg)
-
-    for name in required_arg_names:
-        if name not in param_names:
-            return False
-    return True
+    # Collect all explicitly named parameters (excluding positional-only)
+    # Note: args.posonlyargs are NOT included as they cannot be passed by keyword
+    param_names = {arg.arg for arg in args.args + args.kwonlyargs}
+
+    return set(required_arg_names).issubset(param_names)

pythagoras/_070_protected_code_portals/list_flattener.py

@@ -1,12 +1,50 @@
+from typing import List, Any
 
 
-def flatten_list(nested_list):
-    """Flatten a list with unlimited nesting levels."""
-    assert isinstance(nested_list, list)
+def flatten_list(nested_list: List[Any]) -> List[Any]:
+    """Flatten a nested list into a single-level list.
+
+    This function flattens lists of arbitrary depth using an iterative
+    (non-recursive) algorithm. Only values of type ``list`` are treated as
+    containers to be expanded. Other iterable types (e.g., tuples, sets,
+    strings, generators) are considered atomic values and are not traversed.
+
+    Parameters:
+    - nested_list: list
+        A possibly nested Python list. Must be an instance of ``list``.
+
+    Returns:
+    - list
+        A new list containing all elements from ``nested_list`` in their
+        original left-to-right order, but with one level of nesting (flat).
+
+    Raises:
+    - TypeError: If ``nested_list`` is not a ``list`` instance.
+
+    Notes:
+    - Preserves the order of elements.
+    - Supports unlimited nesting depth without recursion.
+    - Cyclic references (e.g., a list that contains itself, directly or
+      indirectly) will lead to an infinite loop.
+
+    Examples:
+    >>> flatten_list([1, [2, 3, [4]], 5])
+    [1, 2, 3, 4, 5]
+    >>> flatten_list([["a", ["b"]], "c"]) 
+    ['a', 'b', 'c']
+    >>> flatten_list([(1, 2), [3, 4]])
+    [(1, 2), 3, 4]
+    """
+    if not isinstance(nested_list, list):
+        raise TypeError(f"Expected list, got {type(nested_list).__name__}")
     flattened = []
-    for item in nested_list:
-        if isinstance(item, list):
-            flattened.extend(flatten_list(item))
+    stack = [nested_list]
+
+    while stack:
+        current = stack.pop()
+        if isinstance(current, list):
+            stack.extend(reversed(current))
         else:
-            flattened.append(item)
+            flattened.append(current)
+
     return flattened

pythagoras/_070_protected_code_portals/package_manager.py

@@ -1,23 +1,55 @@
+"""Utilities to install and uninstall Python packages at runtime.
+
+This module provides a thin wrapper around pip and the uv tool to install
+and uninstall packages from within the running Python process.
+
+Key points:
+- By default, uv is preferred as the installer frontend (uv pip ...). If uv
+  or pip is not available, the module will attempt to install the missing
+  tool as needed.
+- For safety, uninstall_package refuses to operate on 'pip' or 'uv' directly.
+- Calls are synchronous and raise on non-zero exit status.
+"""
+
 import subprocess
 import importlib
 import sys
+from functools import lru_cache
 from typing import Optional
 
-_uv_and_pip_installation_needed:bool = True
 
-def _install_uv_and_pip() -> None:
-    global _uv_and_pip_installation_needed
-    if not _uv_and_pip_installation_needed:
-        return
+def _run(command: list[str]) -> str:
+    """Run command; raise RuntimeError on failure."""
+    try:
+        subprocess.run(command, check=True, stdout=subprocess.PIPE
+            , stderr=subprocess.STDOUT, text=True)
+    except subprocess.CalledProcessError as e:
+        raise RuntimeError(
+            f"Command failed: {' '.join(command)}\n{e.stdout}") from e
+
 
+@lru_cache(maxsize=1) # ensure only one call to _install_uv_and_pip
+def _install_uv_and_pip() -> None:
+    """Ensure the 'uv' and 'pip' frontends are available.
+
+    Behavior:
+    - If this helper has already run in the current process and determined
+      the tools are present, it returns immediately.
+    - Tries to import 'uv'; if missing, installs it using system pip
+      (use_uv=False).
+    - Tries to import 'pip'; if missing, installs it using uv (use_uv=True).
+
+    This function is an internal helper and is called implicitly by
+    install_package() for any package other than 'pip' or 'uv'.
+    """
     try:
         importlib.import_module("uv")
-    except:
+    except ModuleNotFoundError:
         install_package("uv", use_uv=False)
 
     try:
         importlib.import_module("pip")
-    except:
+    except ModuleNotFoundError:
         install_package("pip", use_uv=True)
 
 
@@ -26,13 +58,40 @@ def install_package(package_name:str
         , version:Optional[str]=None
         , use_uv:bool = True
         ) -> None:
-    """Install package using pip."""
-
-    if package_name == "pip":
-        assert use_uv
-    elif package_name == "uv":
-        assert not use_uv
-    else:
+    """Install a Python package using uv (default) or pip.
+
+    Parameters:
+    - package_name: Name of the package to install. Special cases:
+      - 'pip': must be installed using uv (use_uv=True).
+      - 'uv' : must be installed using pip (use_uv=False).
+    - upgrade: If True, pass "--upgrade" to the installer.
+    - version: Optional version pin, e.g. "1.2.3". If provided, constructs
+      "package_name==version".
+    - use_uv: If True, run as `python -m uv pip install ...`; otherwise use pip.
+
+    Behavior:
+    - Ensures both uv and pip are available unless installing one of them.
+    - Runs the installer in a subprocess with check=True (raises on failure).
+    - Imports the package after installation to verify it is importable.
+
+    Raises:
+    - RuntimeError: if the installation command fails.
+    - ValueError: if package_name or version are invalid, or if attempting
+      to install pip with use_uv=False or uv with use_uv=True.
+    - ModuleNotFoundError: if the package cannot be imported after installation.
+    """
+
+    if not package_name or not isinstance(package_name, str):
+        raise ValueError("package_name must be a non-empty string")
+
+    if version and not isinstance(version, str):
+        raise ValueError("version must be a string")
+
+    if package_name == "pip" and not use_uv:
+            raise ValueError("pip must be installed using uv (use_uv=True)")
+    elif package_name == "uv" and use_uv:
+            raise ValueError("uv must be installed using pip (use_uv=False)")
+    elif package_name not in ("pip", "uv"):
         _install_uv_and_pip()
 
     if use_uv:
@@ -46,30 +105,46 @@ def install_package(package_name:str
     package_spec = f"{package_name}=={version}" if version else package_name
     command += [package_spec]
 
-    subprocess.run(command, check=True, stdout=subprocess.PIPE
-        , stderr=subprocess.STDOUT, text=True)
+    _run(command)
 
+    # Verify import. Note: assumes package name matches importable module name.
     importlib.import_module(package_name)
 
 
 def uninstall_package(package_name:str, use_uv:bool=True)->None:
-    """Uninstall package using uv or pip."""
+    """Uninstall a Python package using uv (default) or pip.
+
+    Parameters:
+    - package_name: Name of the package to uninstall. Must not be 'pip' or 'uv'.
+    - use_uv: If True, run `python -m uv pip uninstall <name>`; otherwise use pip with "-y".
+
+    Behavior:
+    - Runs the uninstaller in a subprocess with check=True.
+    - Attempts to import and reload the package after uninstallation. If that
+      succeeds, raises an Exception to indicate the package still appears installed.
 
-    assert package_name not in ["pip", "uv"]
+    Raises:
+    - ValueError: if package_name is 'pip' or 'uv'.
+    - RuntimeError: if the uninstall command fails, or if post-uninstall
+      validation indicates the package is still importable.
+    """
+
+    if package_name in ["pip", "uv"]:
+        raise ValueError(f"Cannot uninstall '{package_name}' "
+                         "- it's a protected package")
 
     if use_uv:
         command = [sys.executable, "-m", "uv", "pip", "uninstall", package_name]
     else:
         command = [sys.executable, "-m", "pip", "uninstall", "-y", package_name]
 
-    subprocess.run(command, check=True, stdout=subprocess.PIPE
-        , stderr=subprocess.STDOUT, text=True)
+    _run(command)
 
     try:
         package = importlib.import_module(package_name)
         importlib.reload(package)
-    except:
+        raise RuntimeError(
+            f"Package '{package_name}' still importable after uninstallation")
+    except ModuleNotFoundError:
         pass
-    else:
-        raise Exception(
-            f"Failed to validate package uninstallation for '{package_name}'. ")
+

pythagoras/_070_protected_code_portals/protected_decorators.py

@@ -1,4 +1,14 @@
-"""Support for work with protected functions."""
+"""Decorators for building protected functions.
+
+This module provides the protected decorator which wraps callables
+into ProtectedFn objects. A ProtectedFn coordinates pre- and post-execution
+validation using ValidatorFn instances and executes within a
+ProtectedCodePortal context.
+
+The decorator is a thin, declarative layer over the underlying core classes,
+allowing you to attach validators at definition
+time while keeping function logic clean and focused.
+"""
 
 from typing import Callable, Any
 
@@ -8,6 +18,27 @@ from .protected_portal_core_classes import *
 from persidict import Joker, KEEP_CURRENT
 
 class protected(autonomous):
+    """Decorator for protected functions with pre/post validation.
+
+    This decorator wraps a target callable into a ProtectedFn that enforces
+    a sequence of pre- and post-execution validators. It builds on the
+    autonomous decorator, adding validator support to it.
+
+    Typical usage:
+        @protected(pre_validators=[...], post_validators=[...])
+        def fn(...):
+            ...
+
+    See Also:
+        ProtectedFn: The runtime wrapper that performs validation and execution.
+        ProtectedCodePortal: Portal coordinating protected function execution.
+
+    Attributes:
+        _pre_validators (list[ValidatorFn] | None): Validators executed before
+            the target function.
+        _post_validators (list[ValidatorFn] | None): Validators executed after
+            the target function.
+    """
 
     _pre_validators: list[ValidatorFn] | None
     _post_validators: list[ValidatorFn] | None
@@ -19,6 +50,24 @@ class protected(autonomous):
                  , excessive_logging: bool|Joker = KEEP_CURRENT
                  , portal: ProtectedCodePortal | None = None
                  ):
+        """Initialize the protected decorator.
+
+        Args:
+            pre_validators (list[ValidatorFn] | None): Pre-execution validators
+                to apply. Each item is either a ValidatorFn or a callable that
+                can be wrapped into a PreValidatorFn by ProtectedFn.
+            post_validators (list[ValidatorFn] | None): Post-execution validators
+                to apply. Each item is either a ValidatorFn or a callable that
+                can be wrapped into a PostValidatorFn by ProtectedFn.
+            fixed_kwargs (dict[str, Any] | None): Keyword arguments to pre-bind
+                to the wrapped function for every call.
+            excessive_logging (bool | Joker): Enables verbose logging for the
+                wrapped function and its validators. Use KEEP_CURRENT to inherit
+                the current setting from the portal/context.
+            portal (ProtectedCodePortal | None): Optional portal instance to
+                bind the wrapped function to. If None, a suitable portal will be
+                inferred when fuction is called.
+        """
         assert isinstance(portal, ProtectedCodePortal) or portal is None
         assert isinstance(fixed_kwargs, dict) or fixed_kwargs is None
         autonomous.__init__(self=self
@@ -30,6 +79,15 @@ class protected(autonomous):
 
 
     def __call__(self, fn: Callable|str) -> ProtectedFn:
+        """Wrap the given function into a ProtectedFn.
+
+        Args:
+            fn (Callable | str): The target function or its source code string.
+
+        Returns:
+            ProtectedFn: A wrapper that performs pre/post validation and then
+            executes the function.
+        """
         wrapper = ProtectedFn(fn
                               , portal=self._portal
                               , pre_validators=self._pre_validators