paramtrack 0.2.0__tar.gz → 0.3.0__tar.gz

{paramtrack-0.2.0 → paramtrack-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramtrack
-Version: 0.2.0
+Version: 0.3.0
 Summary: Remembers the arguments of each method's last call, defaults included.
 Author: Alessio Popovic
 Author-email: Alessio Popovic <alessiopopovic@gmail.com>
@@ -8,10 +8,15 @@ License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.9
 Project-URL: Repository, https://github.com/AlessioPop/paramtrack
+Project-URL: Documentation, https://paramtrack.readthedocs.io
 Description-Content-Type: text/markdown
 
 # paramtrack
 
+[![PyPI](https://img.shields.io/pypi/v/paramtrack)](https://pypi.org/project/paramtrack/)
+[![Tests](https://github.com/AlessioPop/paramtrack/actions/workflows/tests.yml/badge.svg)](https://github.com/AlessioPop/paramtrack/actions/workflows/tests.yml)
+[![Documentation](https://readthedocs.org/projects/paramtrack/badge/?version=latest)](https://paramtrack.readthedocs.io/en/latest/)
+
 Remembers the arguments of each method's last call, defaults included.
 
 ## Install
@@ -74,7 +79,7 @@ This works through chains of `**kwargs` and for calls like `self.method(**kwargs
 
 ### Functions
 
-`track_function` does the same for plain functions and stores the arguments as `function.parameters`:
+`track_function` does the same for plain functions and stores the arguments as `function.parameters`. Before the first call, it shows the defaults, with `?` for arguments that have none:
 
 ```python
 from paramtrack import track_function
@@ -83,7 +88,28 @@ from paramtrack import track_function
 def observe(target, exposure=30, filter="V"):
     ...
 
-observe("Vega")
-
 print(observe.parameters)
 ```
+
+```
+observe
+├─ target   = ?
+├─ exposure = 30
+└─ filter   = 'V'
+```
+
+After a call such as `observe("Vega")`, the values of that call are shown instead.
+
+## Development
+
+Run the tests:
+
+```bash
+uv run pytest
+```
+
+Build the docs into `docs/_build/html`:
+
+```bash
+uv run --with-requirements docs/requirements.txt sphinx-build docs docs/_build/html
+```

{paramtrack-0.2.0 → paramtrack-0.3.0}/README.md

@@ -1,5 +1,9 @@
 # paramtrack
 
+[![PyPI](https://img.shields.io/pypi/v/paramtrack)](https://pypi.org/project/paramtrack/)
+[![Tests](https://github.com/AlessioPop/paramtrack/actions/workflows/tests.yml/badge.svg)](https://github.com/AlessioPop/paramtrack/actions/workflows/tests.yml)
+[![Documentation](https://readthedocs.org/projects/paramtrack/badge/?version=latest)](https://paramtrack.readthedocs.io/en/latest/)
+
 Remembers the arguments of each method's last call, defaults included.
 
 ## Install
@@ -62,7 +66,7 @@ This works through chains of `**kwargs` and for calls like `self.method(**kwargs
 
 ### Functions
 
-`track_function` does the same for plain functions and stores the arguments as `function.parameters`:
+`track_function` does the same for plain functions and stores the arguments as `function.parameters`. Before the first call, it shows the defaults, with `?` for arguments that have none:
 
 ```python
 from paramtrack import track_function
@@ -71,7 +75,28 @@ from paramtrack import track_function
 def observe(target, exposure=30, filter="V"):
     ...
 
-observe("Vega")
-
 print(observe.parameters)
 ```
+
+```
+observe
+├─ target   = ?
+├─ exposure = 30
+└─ filter   = 'V'
+```
+
+After a call such as `observe("Vega")`, the values of that call are shown instead.
+
+## Development
+
+Run the tests:
+
+```bash
+uv run pytest
+```
+
+Build the docs into `docs/_build/html`:
+
+```bash
+uv run --with-requirements docs/requirements.txt sphinx-build docs docs/_build/html
+```

{paramtrack-0.2.0 → paramtrack-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "paramtrack"
-version = "0.2.0"
+version = "0.3.0"
 description = "Remembers the arguments of each method's last call, defaults included."
 readme = "README.md"
 license = "MIT"
@@ -13,6 +13,10 @@ dependencies = []
 
 [project.urls]
 Repository = "https://github.com/AlessioPop/paramtrack"
+Documentation = "https://paramtrack.readthedocs.io"
+
+[dependency-groups]
+dev = ["pytest"]
 
 [build-system]
 requires = ["uv_build>=0.11.28,<0.12.0"]

{paramtrack-0.2.0 → paramtrack-0.3.0}/src/paramtrack/__init__.py

@@ -17,9 +17,29 @@ def tree(arguments):
     return [f"├─ {line}" for line in lines[:-1]] + [f"└─ {line}" for line in lines[-1:]]
 
 
+# Stands in for an argument without a default until a call gives it a value.
+class Unset:
+    def __repr__(self):
+        return "?"
+
+
+UNSET = Unset()
+
+
 class Parameters(dict):
+    def __init__(self):
+        super().__init__()
+        self.uncalled = {}  # functions not called yet, as name -> function giving their defaults
+
+    # Recompute the entries of functions not called yet: what their **kwargs are passed on to
+    # may have been defined after them.
+    def refresh(self):
+        for name, defaults in self.uncalled.items():
+            self[name] = defaults()
+
     # Text version, used by print() and the terminal.
     def __repr__(self):
+        self.refresh()
         blocks = []
         for name, arguments in self.items():
             blocks.append("\n".join([f"\033[1m{name}\033[0m", *tree(arguments)]))  # \033[1m = bold
@@ -27,6 +47,7 @@ class Parameters(dict):
 
     # Clickable version, used by Jupyter; click a method name to unfold it.
     def _repr_html_(self):
+        self.refresh()
         html = ""
         for name, arguments in self.items():
             lines = escape("\n".join(tree(arguments)))
@@ -64,7 +85,8 @@ def resolve(node, namespace):
     raise LookupError(ast.dump(node))
 
 
-# The parameters that func's **kwargs end up in: the passed value where given, the default otherwise.
+# The parameters that func's **kwargs end up in: the passed value where given, the default otherwise,
+# and UNSET for those without one.
 # local holds func's own arguments so that self.method(**kwargs) resolves. Follows chains of **kwargs.
 def forwarded(func, local, kwargs, seen=()):
     seen = (*seen, func)
@@ -84,8 +106,8 @@ def forwarded(func, local, kwargs, seen=()):
                 continue
             if p.name in rest:
                 result.setdefault(p.name, rest.pop(p.name))
-            elif p.default is not p.empty:
-                result.setdefault(p.name, p.default)
+            else:
+                result.setdefault(p.name, UNSET if p.default is p.empty else p.default)
         inner = inspect.unwrap(getattr(callee, "__func__", callee))
         if parameters and parameters[-1].kind is VAR_KEYWORD and inspect.isfunction(inner) and inner not in seen:
             inner_local = {next(iter(inspect.signature(inner).parameters)): callee.__self__} if inspect.ismethod(callee) else {}
@@ -96,6 +118,19 @@ def forwarded(func, local, kwargs, seen=()):
     return result
 
 
+# What is stored for one call: {name: repr(value)}, without self.
+def describe(function, signature, arguments):
+    result = {}
+    for name, value in arguments.items():
+        # Instead of one dict, list what **kwargs is passed on to, defaults included.
+        if signature.parameters[name].kind is VAR_KEYWORD:
+            for key, val in forwarded(inspect.unwrap(function), arguments, value).items():
+                result.setdefault(key, val)
+        elif name != "self":
+            result[name] = value
+    return {k: repr(v) for k, v in result.items()}
+
+
 def track(function, parameters):
     signature = inspect.signature(function)
 
@@ -103,21 +138,41 @@ def track(function, parameters):
     def wrapper(*args, **kwargs):
         bound = signature.bind(*args, **kwargs)
         bound.apply_defaults()
-        arguments = {}
-        for name, value in bound.arguments.items():
-            # Instead of one dict, list what **kwargs is passed on to, defaults included.
-            if signature.parameters[name].kind is VAR_KEYWORD:
-                for key, val in forwarded(inspect.unwrap(function), bound.arguments, value).items():
-                    arguments.setdefault(key, val)
-            elif name != "self":
-                arguments[name] = value
-        parameters[function.__name__] = {k: repr(v) for k, v in arguments.items()}
+        parameters.uncalled.pop(function.__name__, None)
+        parameters[function.__name__] = describe(function, signature, bound.arguments)
         return function(*args, **kwargs)
     return wrapper
 
 
-# Class decorator: track every method and store the arguments as cls.parameters.
 def track_class(cls):
+    """Track the arguments of every method of a class.
+
+    Each call stores the method's arguments, defaults included, in ``cls.parameters``
+    under the method's name, replacing those of the previous call. Keywords that a
+    method passes on with ``**kwargs`` are listed together with the parameters and
+    defaults of the function receiving them.
+
+    Parameters
+    ----------
+    cls : type
+        The class to track.
+
+    Returns
+    -------
+    type
+        The same class, with its methods wrapped and a ``parameters`` attribute added.
+
+    Examples
+    --------
+    >>> @track_class
+    ... class Telescope:
+    ...     def observe(self, target, exposure=30):
+    ...         ...
+    >>> telescope = Telescope()
+    >>> telescope.observe("Vega")
+    >>> telescope.parameters["observe"]
+    {'target': "'Vega'", 'exposure': '30'}
+    """
     cls.parameters = Parameters()
     for name, method in list(vars(cls).items()):
         if inspect.isfunction(method):
@@ -125,9 +180,43 @@ def track_class(cls):
     return cls
 
 
-# Function decorator: track the function and store its arguments as function.parameters.
 def track_function(function):
+    """Track the arguments of a function.
+
+    Each call stores the arguments, defaults included, in ``function.parameters``,
+    replacing those of the previous call. Before the first call, ``function.parameters``
+    shows the defaults, with ``?`` for arguments that have none. Keywords passed on with
+    ``**kwargs`` are listed as in :func:`track_class`.
+
+    Parameters
+    ----------
+    function : callable
+        The function to track.
+
+    Returns
+    -------
+    callable
+        A wrapper around the function with a ``parameters`` attribute.
+
+    Examples
+    --------
+    >>> @track_function
+    ... def observe(target, exposure=30):
+    ...     ...
+    >>> observe.parameters["observe"]
+    {'target': '?', 'exposure': '30'}
+    >>> observe("Vega")
+    >>> observe.parameters["observe"]
+    {'target': "'Vega'", 'exposure': '30'}
+    """
     parameters = Parameters()
     wrapper = track(function, parameters)
     wrapper.parameters = parameters
+    # Before the first call: the defaults, and UNSET for arguments without one.
+    signature = inspect.signature(function)
+    bound = signature.bind_partial()
+    bound.apply_defaults()
+    arguments = {name: bound.arguments.get(name, UNSET) for name in signature.parameters}
+    parameters.uncalled[function.__name__] = lambda: describe(function, signature, arguments)
+    parameters.refresh()
     return wrapper