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 isinspect.Parameter
and allows for additional attributesdefault
andtype
. Theforge
implementation is available atforge.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 isinspect.Signature
. Theforge
implementation is available atforge.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 namedkwargs
).
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 inforge
asforge.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
, andz
:>>> 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 usingforge
, users are unable to write functions with positional-only parameters. However, as demonstrated above, some builtin functions (such aspow()
) 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 inforge
asforge.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
andb
:>>> 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 inforge
asforge.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 parameterp
:>>> 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 inforge
asforge.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 parameterkey
:>>> 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 inforge
asforge.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 parameterkwargs
:>>> 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)