Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Annotate depends and accept_arguments decorators #962

Merged
merged 3 commits into from
Aug 21, 2024
Merged

Annotate depends and accept_arguments decorators #962

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b424b3d
Annotate depends and accept_arguments decorators
gandhis1 Aug 7, 2024
fb079c8
Make annotations Python 3.8-compatible
gandhis1 Aug 14, 2024
06112c9
Remove underscores from instantiated type constructs
gandhis1 Aug 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 14 additions & 6 deletions param/_utils.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,22 +1,28 @@
from __future__ import annotations

import asyncio
import collections
import contextvars
import datetime as dt
import inspect
import functools
import inspect
import numbers
import os
import re
import sys
import traceback
import warnings

from collections import defaultdict, OrderedDict
from collections import OrderedDict, abc, defaultdict
from contextlib import contextmanager
from numbers import Real
from textwrap import dedent
from threading import get_ident
from collections import abc
from typing import TYPE_CHECKING, Callable, Concatenate, ParamSpec, TypeVar

if TYPE_CHECKING:
_P = ParamSpec("_P")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do you use underscore here? Is this the norm?

It is "hidden" behind TYPE_CHECKING, so it will be private for users. It also adds extra overhead to reading the type hinting itself.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is typical for typeshed, for example: https://github.com/python/typeshed/blob/main/stdlib/urllib/request.pyi#L51

It is "hidden" behind TYPE_CHECKING, so it will be private for users.

Not if they are also using TYPE_CHECKING:

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from param._utils import P

And regardless of TYPE_CHECKING it still becomes visible in IDE auto-complete, interspersed with symbols that are part of the public API (as opposed to being namespaced with an underscore prefix):

image

(Granted, underscore is just a convention, they could just as well import it anyway.)

That said, I don't really care either way, so I'll just remove the underscores

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the clarification.

Whatever the norm should be done, and if you say it is making them private, then so be it.

If you want to avoid repeating complex types, you are welcome to create a _typing.py file, though it does not need to be in this PR.

Do you have a preferred way to test type hints? If possible, I would like your help in setting it up.

And like Philipp said, I also appreciate your work on these PRs! 💯

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have a preferred way to test type hints?

For these PRs I generally am just running mypy path/to/file/changed.py --follow-imports=silent and making sure that the errors after are a strict subset of the errors that existed before. I also just create some dummy code that uses the decorator to see whether it works as expected.

For something more automated - and I'm mostly thinking in the context of panel - we could set up a Mypy run that's part of CI. We could start with some subset of the examples folder that we can get zero issues on, then extend to all the examples, and after we reach 100% no issues, we can switch to Mypy strict and repeat. The point would be to prioritize the public API - which examples would encompass - over the internal library code.

I figure examples would work a lot better than me manually creating functions in test code and applying @param.depends etc. on it.

Only after that would I try to Mypy panel or param internal code as that is a much bigger lift and could require some actual code changes to be type-compatible, etc. So we'd probably want to run the examples CI check with --follow-imports=silent so that it doesn't prematurely start checking internal code.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have opened a PR for Panel here holoviz/panel#7151

_R = TypeVar("_R")
CallableT = TypeVar("CallableT", bound=Callable)

DEFAULT_SIGNATURE = inspect.Signature([
inspect.Parameter('self', inspect.Parameter.POSITIONAL_OR_KEYWORD),
Expand Down Expand Up @@ -282,12 +288,14 @@ def flatten(line):
yield element


def accept_arguments(f):
def accept_arguments(
f: Callable[Concatenate[CallableT, _P], _R]
) -> Callable[_P, Callable[[CallableT], _R]]:
"""
Decorator for decorators that accept arguments
"""
@functools.wraps(f)
def _f(*args, **kwargs):
def _f(*args: _P.args, **kwargs: _P.kwargs) -> Callable[[CallableT], _R]:
return lambda actual_f: f(actual_f, *args, **kwargs)
return _f

Expand Down
34 changes: 32 additions & 2 deletions param/depends.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,46 @@
from __future__ import annotations

import inspect

from collections import defaultdict
from functools import wraps
from typing import TYPE_CHECKING, TypeVar, Callable, Protocol, TypedDict, overload

from .parameterized import (
Parameter, Parameterized, ParameterizedMetaclass, transform_reference,
)
from ._utils import accept_arguments, iscoroutinefunction

if TYPE_CHECKING:
CallableT = TypeVar("CallableT", bound=Callable)
Dependency = Parameter | str

class DependencyInfo(TypedDict):
dependencies: tuple[Dependency, ...]
kw: dict[str, Dependency]
watch: bool
on_init: bool

class DependsFunc(Protocol[CallableT]):
_dinfo: DependencyInfo
__call__: CallableT

@overload
def depends(
*dependencies: str, watch: bool = ..., on_init: bool = ...
) -> Callable[[CallableT], DependsFunc[CallableT]]:
...

@overload
def depends(
*dependencies: Parameter, watch: bool = ..., on_init: bool = ..., **kw: Parameter
) -> Callable[[CallableT], DependsFunc[CallableT]]:
Copy link
Contributor Author

@gandhis1 gandhis1 Aug 14, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention with these overloads is to prevent usage that violates the validation that depends applies internally at runtime, for example, this fails:

@depends("test", foobar=Parameter())
def test(a: int, b: str) -> None:
    print("foobar")
param/depends.py:154: error: No overload variant of "depends" matches argument types "str", "Parameter"  [call-overload]
param/depends.py:154: note: Possible overload variants:
param/depends.py:154: note:     def depends(*dependencies: str, watch: bool = ..., on_init: bool = ...) -> Callable[[CallableT], DependsFunc[CallableT]]
param/depends.py:154: note:     def depends(*dependencies: Parameter, watch: bool = ..., on_init: bool = ..., **kw: Parameter) -> Callable[[CallableT], DependsFunc[CallableT]]

While this works:

@depends(Parameter(), foobar=Parameter())
def test(a: int, b: str) -> None:
    print("foobar")

...

@accept_arguments
def depends(func, *dependencies, watch=False, on_init=False, **kw):
def depends(
func: CallableT, /, *dependencies: Dependency, watch: bool = False, on_init: bool = False, **kw: Parameter
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Without the /, Mypy complains:

param/depends.py:40: error: Argument 1 to "accept_arguments" has incompatible type "Callable[[CallableT@depends, VarArg(Parameter | str), DefaultNamedArg(bool, 'watch'), DefaultNamedArg(bool, 'on_init'), KwArg(Parameter)], Callable[[CallableT@depends], DependsFunc[CallableT@depends]]]"; expected "Callable[[CallableT, VarArg(Parameter | str), DefaultNamedArg(bool, 'watch'), DefaultNamedArg(bool, 'on_init'), KwArg(Parameter)], Callable[[CallableT], DependsFunc[CallableT]]]"  [arg-type]
param/depends.py:40: note: This is likely because "depends" has named arguments: "func". Consider marking them positional-only

This looks like a Mypy bug; variadic arguments via * should necessarily mean that func is positional-only. However, adding in / I believe makes no meaningful difference at runtime, so I just went ahead and did that.

) -> Callable[[CallableT], DependsFunc[CallableT]]:
"""Annotates a function or Parameterized method to express its dependencies.

The specified dependencies can be either be Parameter instances or if a
Expand Down Expand Up @@ -117,6 +147,6 @@ def cb(*events):
_dinfo.update({'dependencies': dependencies,
'kw': kw, 'watch': watch, 'on_init': on_init})

_depends._dinfo = _dinfo
_depends._dinfo = _dinfo # type: ignore[attr-defined]

return _depends
Loading