From cc450badfda4f226e427e4353adda14f93e795ff Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Wed, 28 Oct 2020 22:02:57 +0000 Subject: [PATCH 1/2] Add section on static typing Closes gh-13 --- spec/API_specification/array_object.md | 2 + .../function_and_method_signatures.md | 2 + spec/design_topics/static_typing.md | 47 +++++++++++++++++++ 3 files changed, 51 insertions(+) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 07e4f0850..f555eeb76 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -1 +1,3 @@ +.. array-object: + # Array object diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.md index efe477636..1aa25091f 100644 --- a/spec/API_specification/function_and_method_signatures.md +++ b/spec/API_specification/function_and_method_signatures.md @@ -1,3 +1,5 @@ +.. _function-and-method-signatures: + # Function and method signatures Function signatures in this standard adhere to the following: diff --git a/spec/design_topics/static_typing.md b/spec/design_topics/static_typing.md index ee3df101f..1567133cb 100644 --- a/spec/design_topics/static_typing.md +++ b/spec/design_topics/static_typing.md @@ -1 +1,48 @@ # Static typing + +Good support for static typing both in array libraries and array-consuming +code is desirable. Therefore the exact type or set of types for each +parameter, keyword and return value is specified for functions and methods - +see :ref:`function-and-method-signatures`. That section specifies arrays +simply as `array`; what that means is dealt with in this section. + +Introducing type annotations in libraries became more relevant only when +Python 2.7 support was dropped at the start of 2020. As a consequence, using +type annotations with array libraries is largely still a work in progress. +This version of the API standard does not deal with trying to type _array +properties_ like shape, dimensionality or dtype, because that's not a solved +problem in individual array libraries yet. + +An `array` type annotation can mean either the type of one specific array +object, or some superclass or typing Protocol - as long as it is consistent +with the array object specified in :ref:`array-object`. To illustrate by +example: + +```python +# `Array` is a particular class in the library +sin(x: Array, / ...) -> Array: + ... +``` + +and + +```python +# There's some base class `_BaseArray`, and there may be multiple +# array subclasses inside the library +A = TypeVar('A', bound=_BaseArray) +sin(x: A, / ...) -> A: + ... +``` +should both be fine. There may be other variations possible. Also note that +this standard does not require that input and output array types are the same +(they're expected to be defined in the same library though). Given that +array libraries don't have to be aware of other types of arrays defined in +other libraries (see :ref:`assumptions-dependencies`), this should be enough +for a single array library. + +That said, an array-consuming library aiming to support multiple array types +may need more - for example a protocol to enable structural subtyping. This +API standard currently takes the position that it does not provide any +reference implementation or package that can or should be relied on at +runtime, hence no such protocol is defined here. This may be dealt with in a +future version of this standard. From 92eae74d4906bedf859a791b64d1ebbaab1d627a Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Fri, 30 Oct 2020 14:11:08 +0000 Subject: [PATCH 2/2] address review comment --- spec/design_topics/static_typing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/design_topics/static_typing.md b/spec/design_topics/static_typing.md index 1567133cb..7b4d3e3ad 100644 --- a/spec/design_topics/static_typing.md +++ b/spec/design_topics/static_typing.md @@ -20,7 +20,7 @@ example: ```python # `Array` is a particular class in the library -sin(x: Array, / ...) -> Array: +def sin(x: Array, / ...) -> Array: ... ``` @@ -30,7 +30,7 @@ and # There's some base class `_BaseArray`, and there may be multiple # array subclasses inside the library A = TypeVar('A', bound=_BaseArray) -sin(x: A, / ...) -> A: +def sin(x: A, / ...) -> A: ... ``` should both be fine. There may be other variations possible. Also note that