Glossary

General

callable

A callable is a Python object that receives arguments and returns a result. Typical examples are builtin functions (like sorted()), lambda functions, traditional functions, and class instances that implement a __call__() method.

parameter

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

parameter kind

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

signature

A signature is the interface of a function. It contains zero or more parameters, and optionally a return-type annotation. The native Python implementation is inspect.Signature. The forge implementation is available at forge.FSignature.

variadic parameter

A variadic parameter is a parameter that accepts one or more parameters. There are two types: the var-positional parameter (traditionally named args) and the var-keyword parameter (traditionally named kwargs).

Parameter kinds

positional-only

A kind of parameter that can only receive an unnamed argument. It is defined canonically as inspect.Parameter.POSITIONAL_ONLY, and is publicly available in forge as forge.FParameter.POSITIONAL_ONLY.

They are followed by positional-or-keyword, var-positional, keyword-only and var-keyword parameters. positional-only parameters are distinguishable as they are followed by a slash (/).

Consider the builtin function pow() – with three positional-only parameters: x, y, and z:

>>> 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

There is currently no way to compose a function with a positional-only parameter in Python without diving deep into the internals of Python, or using a library like forge. Without diving into the deep internals of Python and without using forge, 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 kind of parameter that can receive either named or unnamed arguments. It is defined canonically as inspect.Parameter.POSITIONAL_OR_KEYWORD, and is publicly available in forge as forge.FParameter.POSITIONAL_OR_KEYWORD.

In function signatures, positional-or-keyword parameters follow positional-only parameters. They are followed by var-positional, keyword-only and var-keyword parameters. positional-or-keyword parameters are distinguishable as they are separated from positional-only parameters by a slash (/).

Consider the function isequal() which has two positional-or-keyword parameters: a and b:

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

var-positional

A kind of parameter that receives unnamed arguments that are not associated with a positional-only or positional-or-keyword parameter. It is defined canonically as inspect.Parameter.VAR_POSITIONAL, and is publicly available in forge as forge.FParameter.VAR_POSITIONAL.

In function signatures, the var-positional parameter follows positional-only and positional-or-keyword parameters. They are followed by keyword-only and var-keyword parameters. var-positional parameters are distinguishable as their parameter name is prefixed by an asterisk (e.g. *args).

Consider the stdlib function os.path.join() which has the var-positional parameter p:

>>> 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 kind of parameter that can only receive a named argument. It is defined canonically as inspect.Parameter.KEYWORD_ONLY, and is publicly available in forge as forge.FParameter.KEYWORD_ONLY.

In function signatures, keyword-only parameters follow positional-only, positional-or-keyword and var-positional parameters. They are followed by the var-keyword parameter. keyword-only parameters are distinguishable as they follow either an asterisk (*) or a var-positional parameter with an asterisk preceding its name (e.g. *args).

Consider the function compare() – with a keyword-only parameter key:

>>> 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 kind of parameter that receives named arguments that are not associated with a positional-or-keyword or keyword-only parameter. It is defined canonically as inspect.Parameter.VAR_KEYWORD, and is publicly available in forge as forge.FParameter.VAR_KEYWORD.

In function signatures, the var-keyword parameter follows positional-only, positional-or-keyword, var-positional, and keyword-only parameters. It is distinguished with two asterisks that precedes the name. var-keyword parameters are distinguishable as their parameter name is prefixed by two asterisks (e.g. **kwargs).

Consider the types.SimpleNamespace constructor which takes only the var-keyword parameter kwargs:

>>> 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)