From 89cb6aa8b92da231b9348ad0ac16be0671c3a9cc Mon Sep 17 00:00:00 2001 From: Matthew Rahtz Date: Sat, 20 Mar 2021 15:07:04 +0000 Subject: [PATCH] PEP 646: Make explicit some more considerations of the motivation (#1881) --- pep-0646.rst | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/pep-0646.rst b/pep-0646.rst index e16b55d83..70aecba39 100644 --- a/pep-0646.rst +++ b/pep-0646.rst @@ -33,7 +33,7 @@ large impact, and the main case this PEP targets - concerns typing in numerical libraries. In the context of numerical computation with libraries such as NumPy and TensorFlow, -the *shape* of arguments is often just as important as the argument *type*. +the *shape* of variables is often just as important as the variable *type*. For example, consider the following function which converts a batch [#batch]_ of videos to grayscale: @@ -51,8 +51,22 @@ and time × batch × channels × height × width. [#timebatch]_ -Ideally, we should have some way of making the required shape clear in the -signature itself. Multiple proposals [#numeric-stack]_ [#typing-ideas]_ +This is important for three reasons: + +* **Documentation**. Without the required shape being clear in the signature, + the user must hunt in the docstring or the code in question to determine + what the input/output shape requirements are. +* **Catching shape bugs before runtime**. Ideally, use of incorrect shapes + should be an error we can catch ahead of time using static analysis. + (This is particularly important for machine learning code, where iteration + times can be slow.) +* **Preventing subtle shape bugs**. In the worst case, use of the wrong shape + will result in the program appearing to run fine, but with a subtle bug + that can take days to track down. (See `this exercise`_ in a popular machine learning + tutorial for a particularly pernicious example.) + +Ideally, we should have some way of making shape requirements explicit in +type signatures. Multiple proposals [#numeric-stack]_ [#typing-ideas]_ [#syntax-proposal]_ have suggested the use of the standard generics syntax for this purpose. We would write: @@ -781,6 +795,8 @@ References .. _mrahtz/cpython/pep637+646: https://github.com/mrahtz/cpython/tree/pep637%2B646 +.. _this exercise: https://spinningup.openai.com/en/latest/spinningup/exercise2_2_soln.html + Copyright =========