development up to tests

Author: andreascaglioni

.gitignore

@@ -0,0 +1,77 @@
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Python cache and bytecode
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+pip-wheel-metadata/
+.eggs/
+*.egg-link
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# pytest
+.pytest_cache/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# mypy / cache
+.mypy_cache/
+.pyre/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Static analysis / tooling
+.cache/
+.mercurial/
+
+# Logs
+*.log
+
+# Misc
+*.sqlite3
+*.db
+
+# Local env files
+.env
+.env.local
+.env.*.local
+
+# Node modules (if any experiments use node tooling)
+node_modules/
+
+# Generated docs
+docs/_build/
+
+# Ignore build artifacts created by editable installs
+*.egg-link
+
+# Keep track of any project-specific ignores below
+# e.g. experiments/data/, notebooks/data/, etc.

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+      - id: black
+        args: ["--line-length=88"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.2
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.11.2
+    hooks:
+      - id: mypy
+        additional_dependencies: ["types-setuptools"]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+All notable changes to this project are recorded here.
+
+## [Unreleased]
+
+### Added
+- Mini calculator library (`example_lib`) with:
+	- `Operation`, `OperationRegistry`, and `Calculator` classes
+	- example operations: `add`, `sub`, `mul`, `div`, `neg`, `sqr`
+- Minimal test suite (pytest) with unit and edge tests
+- `pyproject.toml` for editable installs and packaging
+- `.gitignore` and basic repo scaffolding (`src/`, `tests/`, `experiments/`, `notebooks/`, `docs/`, `scripts/`)
+
+### Changed
+- Replaced decorator-based registration with explicit `Operation` registration API
+
+### Fixed
+- Import path handling in tests: tests now assume editable install; `conftest.py` removed sys.path hacks
+
+---
+
+## [0.1.0] - 2025-10-10
+
+Initial public release
+
+### Added
+- Project scaffold and minimal working library to demonstrate portfolio-ready features

docs/.gitkeep

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "example-lib"
+version = "0.1.0"
+description = "Mini calculator library"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "Andrea" }]
+license = { text = "MIT" }
+dependencies = []
+
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["example_lib*"]

notebooks/.gitkeep

@@ -0,0 +1,37 @@
+"""example_lib: mini math utility library
+
+Exports:
+- Operation, Operation registry, Calculator, convenience operations
+"""
+
+from .exceptions import CalculatorError, OperationError, RegistryError
+from .operations import Operation, ADD, SUB, MUL, DIV, NEG, SQR
+from .registry import OperationRegistry
+from .calculator import Calculator
+from .utils import is_number
+
+__all__ = [
+    "CalculatorError",
+    "OperationError",
+    "RegistryError",
+    "Operation",
+    "OperationRegistry",
+    "Calculator",
+    "ADD",
+    "SUB",
+    "MUL",
+    "DIV",
+    "NEG",
+    "SQR",
+    "is_number",
+]
+
+# Provide a default registry populated with common ops
+_default_registry = OperationRegistry()
+for op in (ADD, SUB, MUL, DIV, NEG, SQR):
+    _default_registry.register(op)
+
+
+# Convenience constructor using default registry
+def default_calculator() -> Calculator:
+    return Calculator(registry=_default_registry)

pyproject.toml

@@ -0,0 +1,111 @@
+"""Calculator that can register and compose operations."""
+
+from typing import Callable, Iterable, List, Any, Optional
+
+from .registry import OperationRegistry
+from .operations import Operation
+from .exceptions import OperationError
+
+
+class Calculator:
+    """A tiny calculator that uses an OperationRegistry.
+
+    Features:
+    - register operations (via registry or helper)
+    - apply a named operation to arguments
+    - compose a sequence of operations into a single callable
+    """
+
+    def __init__(self, registry: Optional[OperationRegistry] = None):
+        self.registry = registry or OperationRegistry()
+
+    def register(self, op: Operation, *, replace: bool = False) -> None:
+        self.registry.register(op, replace=replace)
+
+    def apply(self, op_name: str, *args) -> Any:
+        op = self.registry.get(op_name)
+        try:
+            return op(*args)
+        except Exception as exc:
+            raise OperationError(
+                f"Error applying operation '{op_name}': {exc}"
+            ) from exc
+
+    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))).
+
+        Returns:
+            callable f(x)
+        """
+
+        op_list: List[Operation] = [self.registry.get(name) for name in ops]
+        for op in op_list:
+            if op.arity != 1:
+                raise OperationError(f"Cannot compose non-unary operation: {op.name}")
+
+        if left_to_right:
+
+            def composed(x):
+                val = x
+                for op in op_list:
+                    val = op(val)
+                return val
+
+        else:
+
+            def composed(x):
+                val = x
+                for op in reversed(op_list):
+                    val = op(val)
+                return val
+
+        return composed
+
+    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.
+        """
+        seq = list(sequence)
+        cur = initial
+        i = 0
+        while i < len(seq):
+            item = seq[i]
+            if isinstance(item, str):
+                op = self.registry.get(item)
+                if op.arity == 1:
+                    cur = op(cur)
+                    i += 1
+                elif op.arity == 2:
+                    # expect next item as argument
+                    if i + 1 >= len(seq):
+                        raise OperationError(
+                            f"Operation '{op.name}' expects an additional argument in the sequence"
+                        )
+                    arg = seq[i + 1]
+                    cur = op(cur, arg)
+                    i += 2
+                else:
+                    raise OperationError("Only arity 1 or 2 supported in chain")
+            else:
+                # literal encountered: treat as updating current value
+                cur = item
+                i += 1
+        return cur

scripts/.gitkeep

@@ -0,0 +1,13 @@
+"""Custom exceptions for the mini calculator library."""
+
+
+class CalculatorError(Exception):
+    """Base class for calculator-related errors."""
+
+
+class OperationError(CalculatorError):
+    """Raised when an operation fails (e.g. wrong arity or invalid input)."""
+
+
+class RegistryError(CalculatorError):
+    """Raised for registry problems (duplicate name, not found)."""