param 2.3.3b0__tar.gz → 2.4.0a0__tar.gz

{param-2.3.3b0 → param-2.4.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: param
-Version: 2.3.3b0
+Version: 2.4.0a0
 Summary: Declarative parameters for robust Python classes and a rich API for reactive programming
 Project-URL: Homepage, https://param.holoviz.org/
 Project-URL: Tracker, https://github.com/holoviz/param/issues
@@ -25,6 +25,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Provides-Extra: all
 Requires-Dist: aiohttp; extra == 'all'

{param-2.3.3b0 → param-2.4.0a0}/param/__init__.py

@@ -112,10 +112,11 @@ from ._utils import (
 try:
     # For performance reasons on imports, avoid importing setuptools_scm
     # if not in a .git folder
+    __version__ : str
     if os.path.exists(os.path.join(os.path.dirname(__file__), "..", ".git")):
         # If setuptools_scm is installed (e.g. in a development environment with
         # an editable install), then use it to determine the version dynamically.
-        from setuptools_scm import get_version
+        from setuptools_scm import get_version  # type: ignore[unresolved-import,import-untyped,reportMissingImports]
 
         # This will fail with LookupError if the package is not installed in
         # editable mode or if Git is not installed.
@@ -127,7 +128,7 @@ except (ImportError, LookupError, FileNotFoundError):
     try:
         # __version__ was added in _version in setuptools-scm 7.0.0, we rely on
         # the hopefully stable version variable.
-        from ._version import version as __version__
+        from ._version import version as __version__  # type: ignore[unresolved-import,no-redef]  # pyright: ignore[reportMissingImports]
     except (ModuleNotFoundError, ImportError):
         # Either _version doesn't exist (ModuleNotFoundError) or version isn't
         # in _version (ImportError). ModuleNotFoundError is a subclass of
@@ -137,7 +138,7 @@ except (ImportError, LookupError, FileNotFoundError):
         from importlib.metadata import version as mversion, PackageNotFoundError
 
         try:
-            __version__ = mversion("param")
+            __version__ = str(mversion("param"))
         except PackageNotFoundError:
             # The user is probably trying to run this without having installed
             # the package.
@@ -145,8 +146,7 @@ except (ImportError, LookupError, FileNotFoundError):
 
 #: Top-level object to allow messaging not tied to a particular
 #: Parameterized object, as in 'param.main.warning("Invalid option")'.
-main=Parameterized(name="main")
-
+main = Parameterized(name="main")
 
 # A global random seed (integer or rational) available for controlling
 # the behaviour of Parameterized objects with random state.
@@ -227,7 +227,6 @@ __all__ = (
     'resolve_path',
     'rx',
     'script_repr',
-    'serializer',
     'shared_parameters',
     'version',
 )

{param-2.3.3b0 → param-2.4.0a0}/param/_utils.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import collections
 import datetime as dt
 import functools
 import inspect
@@ -8,20 +7,19 @@ import numbers
 import os
 import re
 import traceback
+import typing as t
 import warnings
 from collections import OrderedDict, abc, defaultdict
 from contextlib import contextmanager
-from numbers import Real
 from textwrap import dedent
 from threading import get_ident
-from typing import TYPE_CHECKING, Callable, TypeVar
 
-if TYPE_CHECKING:
-    from typing_extensions import Concatenate, ParamSpec
+if t.TYPE_CHECKING:
+    from param.parameterized import Parameter
 
-    P = ParamSpec("P")
-    R = TypeVar("R")
-    CallableT = TypeVar("CallableT", bound=Callable)
+    _P = t.ParamSpec("_P")
+    _R = t.TypeVar("_R")
+    _CallableT = t.TypeVar("_CallableT", bound=abc.Callable)
 
 DEFAULT_SIGNATURE = inspect.Signature([
     inspect.Parameter('self', inspect.Parameter.POSITIONAL_OR_KEYWORD),
@@ -99,8 +97,8 @@ class Skip(Exception):
     """
 
 
-def _deprecated(extra_msg="", warning_cat=ParamDeprecationWarning):
-    def decorator(func):
+def _deprecated(extra_msg: str = "", warning_cat: type[Warning] = ParamDeprecationWarning):
+    def decorator(func: abc.Callable[..., t.Any]) -> abc.Callable[..., t.Any]:
         """Mark a function or method as deprecated.
 
         This internal decorator issues a warning when the decorated function
@@ -119,7 +117,8 @@ def _deprecated(extra_msg="", warning_cat=ParamDeprecationWarning):
         """
         @functools.wraps(func)
         def inner(*args, **kwargs):
-            msg = f"{func.__name__!r} has been deprecated and will be removed in a future version."
+            func_name = getattr(func, "__name__", repr(func))
+            msg = f"{func_name!r} has been deprecated and will be removed in a future version."
             if extra_msg:
                 em = dedent(extra_msg)
                 em = em.strip().replace('\n', ' ')
@@ -152,8 +151,9 @@ def _recursive_repr(fillvalue='...'):
     return decorating_function
 
 
-def _is_auto_name(class_name, instance_name):
-    return re.match('^'+class_name+'[0-9]{5}$', instance_name)
+def _is_auto_name(class_name: str, instance_name: str) -> bool:
+    pattern = rf'^{re.escape(class_name)}[0-9]{{5}}$'
+    return bool(re.match(pattern, instance_name))
 
 
 def _find_pname(pclass):
@@ -163,12 +163,14 @@ def _find_pname(pclass):
     """
     stack = traceback.extract_stack()
     for frame in stack:
-        match = re.match(r"^(\S+)\s*=\s*(param|pm)\." + pclass + r"\(", frame.line)
+        if frame.line is None:
+            continue
+        match = re.match(rf"^(\S+)\s*=\s*(param|pm)\.{pclass}\(", frame.line)
         if match:
             return match.group(1)
 
 
-def _validate_error_prefix(parameter, attribute=None):
+def _validate_error_prefix(parameter: Parameter, attribute: str | None = None) -> str:
     """
     Generate an error prefix suitable for Parameters when they raise a validation
     error.
@@ -279,11 +281,11 @@ def flatten(line):
 
 
 def accept_arguments(
-    f: Callable[Concatenate[CallableT, P], R]
-) -> Callable[P, Callable[[CallableT], R]]:
+    f: abc.Callable[t.Concatenate[_CallableT, _P], _R]
+) -> abc.Callable[..., abc.Callable[[_CallableT], _R]]:
     """Decorate a decorator to accept arguments."""
     @functools.wraps(f)
-    def _f(*args: P.args, **kwargs: P.kwargs) -> Callable[[CallableT], R]:
+    def _f(*args: _P.args, **kwargs: _P.kwargs) -> abc.Callable[[_CallableT], _R]:
         return lambda actual_f: f(actual_f, *args, **kwargs)
     return _f
 
@@ -308,10 +310,10 @@ def _hashable(x):
     part of the object has changed.  Does not (currently) recursively
     replace mutable subobjects.
     """
-    if isinstance(x, collections.abc.MutableSequence):
+    if isinstance(x, abc.MutableSequence):
         return tuple(x)
-    elif isinstance(x, collections.abc.MutableMapping):
-        return tuple([(k,v) for k,v in x.items()])
+    elif isinstance(x, abc.MutableMapping):
+        return tuple([(k, v) for k, v in x.items()])
     else:
         return x
 
@@ -351,39 +353,52 @@ def _named_objs(objlist, namesdict=None):
 
 def _get_min_max_value(min, max, value=None, step=None):
     """Return min, max, value given input values with possible None."""
-    # Either min and max need to be given, or value needs to be given
+    fmin = float(min) if min is not None else None
+    fmax = float(max) if max is not None else None
+
     if value is None:
-        if min is None or max is None:
-            raise ValueError(
-                f'unable to infer range, value from: ({min}, {max}, {value})'
-            )
-        diff = max - min
-        value = min + (diff / 2)
-        # Ensure that value has the same type as diff
-        if not isinstance(value, type(diff)):
-            value = min + (diff // 2)
-    else:  # value is not None
-        if not isinstance(value, Real):
-            raise TypeError('expected a real number, got: %r' % value)
-        # Infer min/max from value
-        if value == 0:
-            # This gives (0, 1) of the correct type
-            vrange = (value, value + 1)
-        elif value > 0:
-            vrange = (-value, 3*value)
-        else:
-            vrange = (3*value, -value)
-        if min is None:
-            min = vrange[0]
-        if max is None:
-            max = vrange[1]
+        if fmin is None or fmax is None:
+            raise ValueError(f"unable to infer range, value from: ({min}, {max}, {value})")
+        fvalue = (fmin + fmax) / 2.0
+    else:
+        fvalue = float(value)
+        if fmin is None or fmax is None:
+            if fvalue == 0.0:
+                low, high = 0.0, 1.0
+            elif fvalue > 0.0:
+                low, high = -fvalue, 3.0 * fvalue
+            else:
+                low, high = 3.0 * fvalue, -fvalue
+            if fmin is None:
+                fmin = low
+            if fmax is None:
+                fmax = high
+
+    # Safety: ensure bounds exist
+    if fmin is None or fmax is None:
+        raise RuntimeError("internal error: bounds not resolved")
+
+    # Normalize so fmin <= fmax
+    if fmin > fmax:
+        fmin, fmax = fmax, fmin
+
+    # Snap to step if requested
     if step is not None:
-        # ensure value is on a step
-        tick = int((value - min) / step)
-        value = min + tick * step
-    if not min <= value <= max:
-        raise ValueError(f'value must be between min and max (min={min}, value={value}, max={max})')
-    return min, max, value
+        fstep = abs(float(step))
+        if fstep == 0.0:
+            raise ValueError("step must be non-zero")
+        ticks = round((fvalue - fmin) / fstep)  # nearest tick; use math.floor for always-down
+        fvalue = fmin + ticks * fstep
+        # Clamp after snapping
+        if fvalue < fmin:
+            fvalue = fmin
+        if fvalue > fmax:
+            fvalue = fmax
+
+    if not (fmin <= fvalue <= fmax):
+        raise ValueError(f"value must be between min and max (min={fmin}, value={fvalue}, max={fmax})")
+
+    return fmin, fmax, fvalue
 
 
 def _deserialize_from_path(ext_to_routine, path, type_name):
@@ -425,10 +440,7 @@ def _is_number(obj):
 def _is_abstract(class_: type) -> bool:
     if inspect.isabstract(class_):
         return True
-    try:
-        return class_.abstract
-    except AttributeError:
-        return False
+    return bool(getattr(class_, "abstract", False))
 
 
 def descendents(class_: type, concrete: bool = False) -> list[type]:
@@ -470,7 +482,7 @@ def descendents(class_: type, concrete: bool = False) -> list[type]:
     if not isinstance(class_, type):
         raise TypeError(f"descendents expected a class object, not {type(class_).__name__}")
     q = [class_]
-    out = []
+    out: list[type] = []
     while len(q):
         x = q.pop(0)
         out.insert(0, x)
@@ -580,12 +592,13 @@ def exceptions_summarized():
     except Exception:
         import sys
         etype, value, tb = sys.exc_info()
-        print(f"{etype.__name__}: {value}", file=sys.stderr)
+        if etype is not None:
+            print(f"{etype.__name__}: {value}", file=sys.stderr)
 
 
 def _in_ipython():
     try:
-        get_ipython
+        get_ipython()  # type: ignore[name-defined,ty:unresolved-reference]  # pyright: ignore[reportUndefinedVariable]
         return True
     except NameError:
         return False
@@ -605,21 +618,27 @@ def async_executor(func):
     else:
         event_loop.run_until_complete(func())
 
+@t.runtime_checkable
+class _HasTypes(t.Protocol):
+    @classmethod
+    def types(cls) -> abc.Iterable[type]: ...
+
 class _GeneratorIsMeta(type):
-    def __instancecheck__(cls, inst):
+    def __instancecheck__(cls: type[_HasTypes], inst):
         return isinstance(inst, tuple(cls.types()))
 
-    def __subclasscheck__(cls, sub):
+    def __subclasscheck__(cls: type[_HasTypes], sub: type) -> bool:
         return issubclass(sub, tuple(cls.types()))
 
-    def __iter__(cls):
+    def __iter__(cls: type[_HasTypes]) -> abc.Iterator[type]:
         yield from cls.types()
 
 class _GeneratorIs(metaclass=_GeneratorIsMeta):
     @classmethod
-    def __iter__(cls):
+    def __iter__(cls: type[_HasTypes]) -> abc.Iterator[type]:
         yield from cls.types()
 
+
 def gen_types(gen_func):
     """Decorate a generator function to support type checking.
 
@@ -656,8 +675,12 @@ def _find_stack_level() -> int:
     import numbergen
     import param
 
-    ng_dir = os.path.dirname(numbergen.__file__)
-    param_dir = os.path.dirname(param.__file__)
+    numbergen_file = getattr(numbergen, "__file__", None)
+    param_file = getattr(param, "__file__", None)
+    if numbergen_file is None or param_file is None:
+        return 2
+    ng_dir = os.path.dirname(numbergen_file)
+    param_dir = os.path.dirname(param_file)
 
     # https://stackoverflow.com/questions/17407119/python-inspect-stack-is-slow
     frame = inspect.currentframe()

{param-2.3.3b0 → param-2.4.0a0}/param/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.3.3b0'
-__version_tuple__ = version_tuple = (2, 3, 3, 'b0')
+__version__ = version = '2.4.0a0'
+__version_tuple__ = version_tuple = (2, 4, 0, 'a0')
 
 __commit_id__ = commit_id = None

param-2.4.0a0/param/depends.py

@@ -0,0 +1,233 @@
+from __future__ import annotations
+
+import inspect
+import typing as t
+
+from collections import defaultdict
+from functools import wraps
+
+from .parameterized import (
+    Event, Parameter, Parameterized, ParameterizedMetaclass, transform_reference,
+)
+from ._utils import iscoroutinefunction
+
+if t.TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Callable, Generator
+
+    _Y = t.TypeVar("_Y")
+    _S = t.TypeVar("_S")
+    _T = t.TypeVar("_T")
+
+_P = t.ParamSpec("_P")
+_R = t.TypeVar("_R", covariant=True)
+Dependency = Parameter | str
+
+class DependencyInfo(t.TypedDict):
+    dependencies: tuple[Dependency, ...]
+    kw: dict[str, Dependency]
+    watch: bool
+    on_init: bool
+
+class DependsFunc(t.Protocol[_P, _R]):
+    _dinfo: DependencyInfo
+    def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+
+
+@t.overload
+def depends(
+    func: Callable[_P, _R], /, *dependencies: Dependency, watch: bool = False, on_init: bool = False, **kw: Dependency
+) -> DependsFunc[_P, _R]:
+    ...
+
+@t.overload
+def depends(
+    *dependencies: str, watch: bool = False, on_init: bool = False
+) -> Callable[[Callable[_P, _R]], DependsFunc[_P, _R]]:
+    ...
+
+@t.overload
+def depends(
+    *dependencies: Parameter, watch: bool = False, on_init: bool = False, **kw: Parameter
+) -> Callable[[Callable[_P, _R]], DependsFunc[_P, _R]]:
+    ...
+
+def depends(
+    *dependencies: Dependency | Callable[_P, _R], watch: bool = False, on_init: bool = False, **kw: Dependency
+) -> DependsFunc[_P, _R] | Callable[[Callable[_P, _R]], DependsFunc[_P, _R]]:
+    """
+    Annotates a function or :class:`Parameterized` method to express its dependencies.
+
+    The specified dependencies can be either be :class:`Parameter` instances or if a
+    method is supplied they can be defined as strings referring to Parameters
+    of the class, or Parameters of subobjects (Parameterized objects that are
+    values of this object's parameters). Dependencies can either be on
+    Parameter values, or on other metadata about the Parameter.
+
+    Parameters
+    ----------
+    watch : bool, optional
+        Whether to invoke the function/method when the dependency is updated,
+        by default ``False``.
+    on_init : bool, optional
+        Whether to invoke the function/method when the instance is created,
+        by default ``False``.
+
+    """
+    if dependencies and callable(dependencies[0]) and not isinstance(dependencies[0], (str, Parameter)):
+        func = t.cast("Callable[_P, _R]", dependencies[0])
+        deps = t.cast("tuple[Dependency, ...]", dependencies[1:])
+        return _depends_impl(func, *deps, watch=watch, on_init=on_init, **kw)
+
+    deps = t.cast("tuple[Dependency, ...]", dependencies)
+
+    def _decorator(func: Callable[_P, _R]) -> DependsFunc[_P, _R]:
+        return _depends_impl(func, *deps, watch=watch, on_init=on_init, **kw)
+
+    return _decorator
+
+
+def _depends_impl(
+    func: Callable[_P, _R], /, *dependencies: Dependency, watch: bool = False, on_init: bool = False, **kw: Dependency
+) -> DependsFunc[_P, _R]:
+    dependencies, kw = (
+        tuple(transform_reference(arg) for arg in dependencies),
+        {key: transform_reference(arg) for key, arg in kw.items()}
+    )
+
+    if inspect.isgeneratorfunction(func):
+        func_gen = t.cast("Callable[_P, Generator[t.Any, t.Any, t.Any]]", func)
+        @wraps(func)
+        def _depends_gen(*args, **kw):
+            for val in func_gen(*args, **kw):
+                yield val
+        _depends = t.cast("Callable[_P, _R]", _depends_gen)
+    elif inspect.isasyncgenfunction(func):
+        func_agen = t.cast("Callable[_P, AsyncGenerator[t.Any, t.Any]]", func)
+        @wraps(func)
+        async def _depends_async_gen(*args, **kw):
+            async for val in func_agen(*args, **kw):
+                yield val
+        _depends = t.cast("Callable[_P, _R]", _depends_async_gen)
+    elif iscoroutinefunction(func):
+        F = t.cast("Callable[_P, t.Awaitable[_R]]", func)
+        @wraps(func)
+        async def _depends_coro(*args, **kw):
+            return await F(*args, **kw)
+        _depends = t.cast("Callable[_P, _R]", _depends_coro)
+    else:
+        @wraps(func)
+        def _depends_sync(*args, **kw):
+            return func(*args, **kw)
+        _depends = t.cast("Callable[_P, _R]", _depends_sync)
+
+    deps = list(dependencies)+list(kw.values())
+    string_specs = False
+    for dep in deps:
+        if isinstance(dep, str):
+            string_specs = True
+        elif hasattr(dep, '_dinfo'):
+            pass
+        elif not isinstance(dep, Parameter):
+            raise ValueError('The depends decorator only accepts string '
+                             'types referencing a parameter or parameter '
+                             'instances, found %s type instead.' %
+                             type(dep).__name__)
+        elif not (isinstance(dep.owner, Parameterized) or
+                  (isinstance(dep.owner, ParameterizedMetaclass))):
+            owner = 'None' if dep.owner is None else '%s class' % type(dep.owner).__name__
+            raise ValueError('Parameters supplied to the depends decorator, '
+                             'must be bound to a Parameterized class or '
+                             'instance, not %s.' % owner)
+
+    if (any(isinstance(dep, Parameter) for dep in deps) and
+        any(isinstance(dep, str) for dep in deps)):
+        raise ValueError('Dependencies must either be defined as strings '
+                         'referencing parameters on the class defining '
+                         'the decorated method or as parameter instances. '
+                         'Mixing of string specs and parameter instances '
+                         'is not supported.')
+    elif string_specs and kw:
+        raise AssertionError('Supplying keywords to the decorated method '
+                             'or function is not supported when referencing '
+                             'parameters by name.')
+
+    _dinfo = t.cast("DependencyInfo", dict(getattr(func, '_dinfo', {})))
+    _dinfo.update({'dependencies': dependencies,
+                   'kw': kw, 'watch': watch, 'on_init': on_init})
+
+    typed_depends = t.cast("DependsFunc[_P, _R]", _depends)
+    typed_depends._dinfo = _dinfo
+
+    if string_specs or not watch:
+         # string_specs case handled elsewhere (later), in Parameterized.__init__
+         return typed_depends
+    param_args = [dep for dep in dependencies if isinstance(dep, Parameter)]
+    param_kwargs = {n: dep for n, dep in kw.items() if isinstance(dep, Parameter)}
+    param_deps = list(param_args) + list(param_kwargs.values())
+
+    def _dep_owner_name(dep: Parameter) -> tuple[Parameterized, str] | None:
+        owner = dep.owner
+        name = dep.name
+        if owner is None or name is None:
+            return None
+        return owner, name
+
+    def _resolve_args() -> tuple[t.Any, ...]:
+        args: list[t.Any] = []
+        for dep in param_args:
+            owner_name = _dep_owner_name(dep)
+            if owner_name is None:
+                continue
+            owner, name = owner_name
+            args.append(getattr(owner, name))
+        return tuple(args)
+
+    def _resolve_kwargs() -> dict[str, t.Any]:
+        dep_kwargs: dict[str, t.Any] = {}
+        for key, dep in param_kwargs.items():
+            owner_name = _dep_owner_name(dep)
+            if owner_name is None:
+                continue
+            owner, name = owner_name
+            dep_kwargs[key] = getattr(owner, name)
+        return dep_kwargs
+
+    if inspect.isgeneratorfunction(func):
+        def cb_gen(*events: Event):
+            args = _resolve_args()
+            dep_kwargs = _resolve_kwargs()
+            func_gen = t.cast("Callable[_P, Generator[t.Any, t.Any, t.Any]]", func)
+            for val in func_gen(*args, **dep_kwargs):
+                yield val
+        cb = cb_gen
+    elif inspect.isasyncgenfunction(func):
+        async def cb_async_gen(*events: Event):
+            args = _resolve_args()
+            dep_kwargs = _resolve_kwargs()
+            func_agen = t.cast("Callable[_P, AsyncGenerator[t.Any, t.Any]]", func)
+            async for val in func_agen(*args, **dep_kwargs):
+                yield val
+        cb = cb_async_gen
+    elif iscoroutinefunction(func):
+        async def cb_coro(*events: Event):
+            args = _resolve_args()
+            dep_kwargs = _resolve_kwargs()
+            func_coro = t.cast("Callable[_P, t.Awaitable[t.Any]]", func)
+            await func_coro(*args, **dep_kwargs)
+        cb = cb_coro
+    else:
+        def cb_sync(*events: Event):
+            args = _resolve_args()
+            dep_kwargs = _resolve_kwargs()
+            return func(*args, **dep_kwargs)
+        cb = cb_sync
+
+    grouped = defaultdict(list)
+    for dep in param_deps:
+        grouped[id(dep.owner)].append(dep)
+    for group in grouped.values():
+        if group[0].owner is None:
+            continue
+        group[0].owner.param.watch(cb, [dep.name for dep in group])
+
+    return typed_depends

{param-2.3.3b0 → param-2.4.0a0}/param/display.py

@@ -1,7 +1,7 @@
 import weakref
 
-_display_accessors = {}
-_reactive_display_objs = weakref.WeakSet()
+_display_accessors: dict[str, object] = {}
+_reactive_display_objs: weakref.WeakSet[object] = weakref.WeakSet()
 
 def register_display_accessor(name, accessor, force=False):
     if name in _display_accessors and not force: