Skip to content

ParamSpec doc uses list of types instead of tuple of types for default value #143206

@dhruvmanila

Description

@dhruvmanila

Documentation

The documentation for ParamSpec uses a tuple of types for the default value of a ParamSpec type variable but the typing spec mentions that it should be a list of types:

ParamSpec defaults are defined using the same syntax as TypeVar s but use a list of types or an ellipsis literal “...” or another in-scope ParamSpec (see Scoping Rules).

https://typing.python.org/en/latest/spec/generics.html#paramspec-defaults

The documentation is defined here:

PyDoc_STRVAR(paramspec_doc,
"Parameter specification variable.\n\
\n\
The preferred way to construct a parameter specification is via the\n\
dedicated syntax for generic functions, classes, and type aliases,\n\
where the use of '**' creates a parameter specification::\n\
\n\
type IntFunc[**P] = Callable[P, int]\n\
\n\
The following syntax creates a parameter specification that defaults\n\
to a callable accepting two positional-only arguments of types int\n\
and str:\n\
\n\
type IntFuncDefault[**P = (int, str)] = Callable[P, int]\n\
\n\
For compatibility with Python 3.11 and earlier, ParamSpec objects\n\
can also be created as follows::\n\
\n\
P = ParamSpec('P')\n\
DefaultP = ParamSpec('DefaultP', default=(int, str))\n\
\n\
Parameter specification variables exist primarily for the benefit of\n\
static type checkers. They are used to forward the parameter types of\n\
one callable to another callable, a pattern commonly found in\n\
higher-order functions and decorators. They are only valid when used\n\
in ``Concatenate``, or as the first argument to ``Callable``, or as\n\
parameters for user-defined Generics. See class Generic for more\n\
information on generic types.\n\
\n\
An example for annotating a decorator::\n\
\n\
def add_logging[**P, T](f: Callable[P, T]) -> Callable[P, T]:\n\
'''A type-safe decorator to add logging to a function.'''\n\
def inner(*args: P.args, **kwargs: P.kwargs) -> T:\n\
logging.info(f'{f.__name__} was called')\n\
return f(*args, **kwargs)\n\
return inner\n\
\n\
@add_logging\n\
def add_two(x: float, y: float) -> float:\n\
'''Add two numbers together.'''\n\
return x + y\n\
\n\
Parameter specification variables can be introspected. e.g.::\n\
\n\
>>> P = ParamSpec(\"P\")\n\
>>> P.__name__\n\
'P'\n\
\n\
Note that only parameter specification variables defined in the global\n\
scope can be pickled.\n\
");

I'm not sure why the default value doesn't show up in the rendered documentation over at https://docs.python.org/3/library/typing.html#typing.ParamSpec though.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions