diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.rst similarity index 52% rename from spec/API_specification/function_and_method_signatures.md rename to spec/API_specification/function_and_method_signatures.rst index d199bcbb6..86d0819a6 100644 --- a/spec/API_specification/function_and_method_signatures.md +++ b/spec/API_specification/function_and_method_signatures.rst @@ -1,36 +1,34 @@ -(function-and-method-signatures)= +.. _function-and-method-signatures: -# Function and method signatures +Function and method signatures +============================== Function signatures in this standard adhere to the following: -1. Positional parameters must be - [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. +1. Positional parameters must be `positional-only `_ parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order. - _Rationale: existing libraries have incompatible conventions, and using names - of positional parameters is not normal/recommended practice._ + *Rationale: existing libraries have incompatible conventions, and using names + of positional parameters is not normal/recommended practice.* - ```{note} + .. note:: Positional-only parameters are only available in Python >= 3.8. Libraries still supporting 3.7 or 3.6 may consider making the API standard-compliant namespace >= 3.8. Alternatively, they can add guidance to their users in the - documentation to use the functions as if they were positional-only. - ``` + documentation to use the functions as if they were positional-only. -2. Optional parameters must be - [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments. +2. Optional parameters must be `keyword-only `_ arguments. - _Rationale: this leads to more readable code, and it makes it easier to + *Rationale: this leads to more readable code, and it makes it easier to evolve an API over time by adding keywords without having to worry about - keyword order._ + keyword order.* 3. For functions that have a single positional array parameter, that parameter - is called `x`. For functions that have multiple array parameters, those - parameters are called `xi` with `i = 1, 2, ...` (i.e., `x1`, `x2`). + is called ``x``. For functions that have multiple array parameters, those + parameters are called ``xi`` with ``i = 1, 2, ...`` (i.e., ``x1``, ``x2``). 4. Type annotations are left out of the signatures themselves for readability; however, they are added to individual parameter descriptions. For code which aims to @@ -38,25 +36,24 @@ Function signatures in this standard adhere to the following: A function signature and description will look like: -``` -funcname(x1, x2, /, *, key1=-1, key2=None) +:: - Parameters + funcname(x1, x2, /, *, key1=-1, key2=None) -> out: + Parameters - x1 : array - description - x2 : array - description - key1 : int - description - key2 : Optional[str] - description + x1 : array + description + x2 : array + description + key1 : int + description + key2 : Optional[str] + description - Returns + Returns - out : array - description -``` + out : array + description -Method signatures will follow the same conventions modulo the addition of -`self`. + +Method signatures will follow the same conventions modulo the addition of ``self``.