Function and method signaturesΒΆ

Function signatures in this standard adhere to the following:

  1. Positional parameters should 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.

    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.

  2. Optional parameters should be keyword-only arguments.

    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.

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

  4. Signatures include type annotations. The type annotations are also added to individual parameter and return value descriptions. For code which aims to adhere to the standard, adding type annotations is strongly recommended.

A function signature and description will look like:

funcname(x1, x2, /, *, key1=-1, key2=None) -> out:
    Parameters

     x1 : array
         description
     x2 : array
         description
     key1 : int
         description
     key2 : Optional[str]
         description

     Returns

     out : array
         description

Method signatures will follow the same conventions modulo the addition of self.

Note that there are a few exceptions to rules (1) and (2), in cases where it enhances readability or use of the non-default form of the parameter in question is commonly used in code written for existing array libraries.