Glossary

callable

A callable is a Python object that receives arguments and returns a result. Typical examples are builtin functions like sorted, lambda``s and user-defined ``functions, and class instances that implement a __call__ method (including the class object itself).

parameter

A parameter is the atomic unit of a signature. It has at minimum a name and a kind. The native Python implementation is inspect.Parameter and allows for additional attributes default and type.

parameter kind

A parameter’s kind determines its position in a signature, and how arguments are mapped to the callable it represents. There are five kinds of parameters: positional-only, positional-or-keyword, var-positional, keyword-only and var-keyword.

signature

A callable signature is the public-interface to a function. It contains zero or more parameters, and optionally a return-type annotation.

Parameter kinds

positional-only

A parameter kind defined canonically by inspect.Parameter.POSITIONAL_ONLY, and available as forge.POSITIONAL_ONLY, arguments for these parameters cannot be named when supplied to a function.

In function signatures, positional-only parameters precede the / marker, and are followed by positional-or-keyword, var-positional, keyword-only and var-keyword parameters. Consider the builtin function pow():

>>> help(pow)
Help on built-in function pow in module builtins:

pow(x, y, z=None, /)
    Equivalent to x**y (with two arguments) or x**y % z (with three arguments)

    Some types, such as ints, are able to use a more efficient algorithm when invoked using the three argument form.
>>> pow(2, 2)
4
>>> pow(x=2, y=2)
TypeError: pow() takes no keyword arguments

Note

Without diving into the deep internals of Python (or using this library), users are unable to write functions with positional-only parameters. However, as demonstrated above, some builtin functions (such as pow()) have them.

Writing functions with positional-only parameters is proposed in PEP 570.

positional-or-keyword

A parameter kind defined canonically by inspect.Parameter.POSITIONAL_OR_KEYWORD, and available as forge.POSITIONAL_OR_KEYWORD, arguments for these parameters can optionally be named when supplied to a function.

In function signatures, positional-or-keyword parameters follow positional-only parameters, and are followed by var-postitional, keyword-only and var-keyword parameters. Consider the function isequal():

>>> def isequal(a, b):
...     return a == b
>>> isequal(1, 1):
True
>>> isequal(a=1, b=2):
False

var-positional

A parameter kind defined canonically by inspect.Parameter.VAR_POSTIIONAL, and available as forge.VAR_POSTIIONAL, arguments for this parameter cannot be specified by the caller. Instead, all supplied, but unbound and non-named arguments are collected into a tuple under this name.

In function signatures, the var-positional parameter is preceded by the * marker, and is often named args. It follows positional-only and positional-or-keyword parameters, and it preceeds keyword-only and var-keyword parameters. Consider the stdlib function os.path.join():

>>> import os
>>> help(os.path.join)
join(a, *p)
    Join two or more pathname components, inserting '/' as needed.
    If any component is an absolute path, all previous path components will be discarded.
    An empty last part will result in a path that ends with a separator.

>>> os.path.join('/', 'users', 'jack', 'media')
'/users/jack/media'

keyword-only

A parameter kind defined canonically by inspect.Parameter.KEYWORD_ONLY, and available as forge.KEYWORD_ONLY, arguments for these parameters must be named when supplied to a function.

In function signatures, keyword-only parameters follow positional-only, positional-or-keyword and var-keyword parameters. They preceed a var-positional parameter (if supplied). Consider the function compare():

>>> def compare(a, b, *, key=None):
...     if key:
...         return a[key] == b[key]
...     return a == b
>>> compare({'x': 1, 'y':2}, {'x': 1, 'y': 3})
False
>>> compare({'x': 1, 'y':2}, {'x': 1, 'y': 3}, key='x')
True
>>> compare({'x': 1, 'y':2}, {'x': 1, 'y': 3}, 'x')
TypeError: compare() takes 2 positional arguments but 3 were given

Note

Writing functions with keyword-only parameters was proposed in PEP 3102 and accepted in April, 2006.

var-keyword

A parameter kind defined canonically by inspect.Parameter.VAR_KEYWORD, and available as forge.VAR_KEYWORD, arguments for this parameter cannot be specified by the caller. Instead, all supplied, but unbound keyword arguments are collected into a dict under this name.

In function signatures, the var-keyword parameter is preceded by the ** marker, and is often named kwargs. It is the last kind of parameter in a signature, following positional-only, positional-or-keyword, var-positional and keyword-only parameters. Consider the types.SimpleNamespace constructor:

>>> from types import SimpleNamespace
>>> help(SimpleNamespace)
class SimpleNamespace(builtins.object)
|  A simple attribute-based namespace.
|
|  SimpleNamespace(**kwargs)
|  ...
>>> SimpleNamespace(a=1, b=2, c=3)
namespace(a=1, b=2, c=3)