updated docstrings

Author: andreascaglioni

src/python_project_template/__init__.py

@@ -1,7 +1,18 @@
-"""python-project-template: mini math utility library
+"""Top-level package for python_project_template.
 
-Exports:
-- Operation, Operation registry, Calculator, convenience operations
+This package exposes the core types and a small set of convenience symbols
+for the mini calculator demo project.
+
+Module layout (concise):
+- exceptions: error classes
+- operations: Operation class and example operations
+- registry: OperationRegistry for registering operations
+- calculator: Calculator class to apply/compose operations
+- utils: tiny helper functions
+
+The exported symbols are intentionally small and stable for tests and
+examples. Use :func:`default_calculator` to quickly get a Calculator pre-
+populated with common operations.
 """
 
 from .exceptions import CalculatorError, OperationError, RegistryError
@@ -26,12 +37,18 @@
     "is_number",
 ]
 
-# Provide a default registry populated with common ops
+
+# Default registry pre-populated with a few convenience operations.
 _default_registry = OperationRegistry()
 for op in (ADD, SUB, MUL, DIV, NEG, SQR):
     _default_registry.register(op)
 
 
-# Convenience Calculator constructor using default registry
 def default_calculator() -> Calculator:
+    """Create a Calculator using the package default registry.
+
+    Returns:
+        Calculator: a calculator with common operations already registered.
+    """
+
     return Calculator(registry=_default_registry)

src/python_project_template/calculator.py

@@ -1,4 +1,13 @@
-"""Calculator that can register and compose operations."""
+"""Calculator utilities for applying and composing operations.
+
+The :class:`Calculator` provides a thin layer over :class:`OperationRegistry`.
+It supports applying named operations, composing unary operations into a
+callable, and a small 'chain' helper for mixed sequences of unary/binary
+operations used by the examples and tests.
+
+Keep the behaviour minimal: methods raise :class:`OperationError` for
+operation-related failures.
+"""
 
 from typing import Callable, Iterable, List, Any, Optional
 
@@ -8,13 +17,13 @@
 
 
 class Calculator:
-    """A tiny calculator that uses an OperationRegistry.
+    """Thin calculator wrapper around an OperationRegistry.
 
-    Features:
-
-    - register operations (via registry or helper)
-    - apply a named operation to arguments
-    - compose a sequence of operations into a single callable
+    Methods:
+        register(op, replace=False): Register an Operation.
+        apply(op_name, *args): Apply a registered operation.
+        compose(ops, left_to_right=True): Compose unary operations.
+        chain(sequence, initial): Apply a mixed sequence DSL-style.
     """
 
     def __init__(self, registry: Optional[OperationRegistry] = None):
@@ -24,9 +33,22 @@ def __init__(self, registry: Optional[OperationRegistry] = None):
             self.registry = registry
 
     def register(self, op: Operation, *, replace: bool = False) -> None:
+        """Register an :class:`Operation` with the calculator's registry.
+
+        Args:
+            op: Operation to register.
+            replace: If True, replace an existing operation with the same name.
+        """
+
         self.registry.register(op, replace=replace)
 
     def apply(self, op_name: str, *args: Any) -> Any:
+        """Apply a named operation to the provided arguments.
+
+        Raises:
+            OperationError: wraps underlying errors from the operation call.
+        """
+
         op = self.registry.get(op_name)
         try:
             return op(*args)
@@ -38,17 +60,11 @@ def apply(self, op_name: str, *args: Any) -> Any:
     def compose(
         self, ops: Iterable[str], *, left_to_right: bool = True
     ) -> Callable[[Any], Any]:
-        """Compose a sequence of unary operations into a single callable.
-
-        The composed function takes one argument and applies the operations in order.
-        Only unary operations (arity == 1) are supported for composition.
-
-        Args:
-            ops: iterable of operation names
-            left_to_right: if True, apply first op then next (f2(f1(x))).
+        """Compose a sequence of unary operations into a callable.
 
-        Returns:
-            callable f(x)
+        Only supports unary operations (arity == 1). The returned function
+        accepts a single value and applies the operations in the requested
+        order.
         """
 
         op_list: List[Operation] = [self.registry.get(name) for name in ops]
@@ -77,16 +93,11 @@ def composed(x):
     def chain(self, sequence: Iterable[str], initial: Any) -> Any:
         """Apply a mixed sequence of operations to an initial value.
 
-        For binary operations, the operation consumes (current_value, next_input)
-        and returns a new current_value. To support binary ops in a chain, the
-        sequence should alternate between operation names and provided literals
-        (which are interpreted as inputs). Example::
-
-            sequence = ['add', 5, 'sqr']
-            chain(sequence, initial=2) -> sqr(add(2,5)) = (2+5)^2
-
-        This is a very small DSL useful for demos.
+        The sequence may contain operation names (str) and literal values.
+        Binary operations consume the current value and the next literal.
+        This helper is intentionally small and tailored for tests/examples.
         """
+
         seq = list(sequence)
         cur = initial
         i = 0

src/python_project_template/exceptions.py

@@ -1,12 +1,21 @@
-"""Custom exceptions for the mini calculator library."""
+"""Custom exceptions used across the mini calculator package.
+
+All exceptions inherit from :class:`CalculatorError` so callers may catch the
+base class for broad error handling. Use the more specific subclasses for
+programmatic checks in tests or higher-level code.
+"""
 
 
 class CalculatorError(Exception):
-    """Base class for calculator-related errors."""
+    """Base class for calculator-related errors.
+
+    Use this as the top-level exception when handling errors coming from the
+    package.
+    """
 
 
 class OperationError(CalculatorError):
-    """Raised when an operation fails (e.g. wrong arity or invalid input)."""
+    """Raised when an operation fails (wrong arity, invalid input, etc.)."""
 
 
 class RegistryError(CalculatorError):

src/python_project_template/operations.py

@@ -1,4 +1,9 @@
-"""Definition of Operation and a handful of example math operations."""
+"""Operation container and a few example math operations.
+
+The :class:`Operation` is a tiny callable wrapper that validates arity and
+delegates to the underlying function. A small set of convenience
+instances (ADD, SUB, MUL, DIV, NEG, SQR) are provided for tests/examples.
+"""
 
 from dataclasses import dataclass
 from typing import Callable, Any
@@ -8,6 +13,14 @@
 
 @dataclass
 class Operation:
+    """Container for a named callable with an expected arity.
+
+    Attributes:
+        name: operation name used for registry lookups.
+        func: callable implementing the operation.
+        arity: number of positional arguments expected by the operation.
+    """
+
     name: str
     func: Callable[..., Any]
     arity: int = 1
@@ -24,29 +37,41 @@ def __call__(self, *args):
 
 
 def add(a, b):
+    """Return the sum of two numbers."""
+
     return a + b
 
 
 def sub(a, b):
+    """Return the difference of two numbers."""
+
     return a - b
 
 
 def mul(a, b):
+    """Return the product of two numbers."""
+
     return a * b
 
 
 def safe_div(a, b):
+    """Divide a by b, raising :class:`OperationError` on zero division."""
+
     try:
         return a / b
     except ZeroDivisionError as e:
         raise OperationError("Division by zero") from e
 
 
 def neg(a):
+    """Return the numeric negation of a value."""
+
     return -a
 
 
 def square(a):
+    """Return the square of a value."""
+
     return a * a
 
 

src/python_project_template/registry.py

@@ -1,4 +1,9 @@
-"""Registry for operations: register, lookup, decorator support."""
+"""Operation registry used to register and lookup operations by name.
+
+The :class:`OperationRegistry` is intentionally minimal: register operations,
+retrieve them by name, list registered names, and update from another
+registry. It raises :class:`RegistryError` for lookup/registration problems.
+"""
 
 from typing import Dict, Iterable
 
@@ -9,30 +14,46 @@
 class OperationRegistry:
     """A simple name->Operation registry.
 
-    Usage:
+    Example:
         reg = OperationRegistry()
-        reg.register(Operation(...))
+        reg.register(Operation('add', func, arity=2))
         op = reg.get('add')
     """
 
     def __init__(self):
         self._ops: Dict[str, Operation] = {}
 
     def register(self, op: Operation, *, replace: bool = False) -> None:
+        """Register an :class:`Operation`.
+
+        Args:
+            op: operation instance to register.
+            replace: if False (default) raise on duplicate names.
+        """
+
         if op.name in self._ops and not replace:
             raise RegistryError(f"Operation already registered: {op.name}")
         self._ops[op.name] = op
 
     def get(self, name: str) -> Operation:
+        """Return a registered Operation by name.
+
+        Raises:
+            RegistryError: if the name is unknown.
+        """
+
         try:
             return self._ops[name]
         except KeyError:
             raise RegistryError(f"Unknown operation: {name}")
 
     def list_ops(self) -> Iterable[str]:
+        """Return a list of registered operation names."""
+
         return list(self._ops.keys())
 
     def update(self, other: "OperationRegistry") -> None:
         """Update the registry with operations from another registry."""
+
         for name in other.list_ops():
             self._ops[name] = other.get(name)

src/python_project_template/utils.py

@@ -1,7 +1,16 @@
-"""Small utilities for the mini calculator library."""
+"""Tiny helper utilities used by the examples and tests.
+
+Only lightweight predicates live here to keep the package dependency-free and
+easy to read.
+"""
 
 from typing import Any
 
 
 def is_number(x: Any) -> bool:
+    """Return True if ``x`` is an int or float.
+
+    Useful in examples and tests to guard numeric operations.
+    """
+
     return isinstance(x, (int, float))