From 427bd16f619830cc9fcbeedad3581ecb9d23c23f Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 20 Jan 2022 16:09:01 -0500 Subject: [PATCH 1/2] Transform static typing md to rst --- .../{static_typing.md => static_typing.rst} | 44 ++++++++++--------- 1 file changed, 23 insertions(+), 21 deletions(-) rename spec/design_topics/{static_typing.md => static_typing.rst} (67%) diff --git a/spec/design_topics/static_typing.md b/spec/design_topics/static_typing.rst similarity index 67% rename from spec/design_topics/static_typing.md rename to spec/design_topics/static_typing.rst index cc744ca0f..b4ec81b85 100644 --- a/spec/design_topics/static_typing.md +++ b/spec/design_topics/static_typing.rst @@ -1,10 +1,11 @@ -# Static typing +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. +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 @@ -13,31 +14,32 @@ 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 +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 +with the array object specified in :ref:`array-object`. To illustrate by example: -```python -# `Array` is a particular class in the library -def 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) -def sin(x: A, / ...) -> A: - ... -``` +.. code-block:: python + + # `Array` is a particular class in the library + def sin(x: Array, / ...) -> Array: + ... + +and + +.. code-block:: python + + # There's some base class `_BaseArray`, and there may be multiple + # array subclasses inside the library + A = TypeVar('A', bound=_BaseArray) + def 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 +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 From f43762928f45c2e37c288dc7bc8221a747e54f52 Mon Sep 17 00:00:00 2001 From: Stephannie Jimenez Date: Thu, 20 Jan 2022 16:11:21 -0500 Subject: [PATCH 2/2] fix warning --- spec/design_topics/static_typing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/design_topics/static_typing.rst b/spec/design_topics/static_typing.rst index b4ec81b85..26a1fb901 100644 --- a/spec/design_topics/static_typing.rst +++ b/spec/design_topics/static_typing.rst @@ -10,8 +10,8 @@ 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 +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