PEP 465: a dedicated infix operator for matrix multiplication (closes #21176)

8 files changed, 95 insertions, 33 deletions

diff --git a/Doc/c-api/number.rst b/Doc/c-api/number.rst
index 21951c3..9bcb649 100644
--- a/Doc/c-api/number.rst
+++ b/Doc/c-api/number.rst
@@ -30,6 +30,14 @@ Number Protocol
    the equivalent of the Python expression ``o1 * o2``.
 
 
+.. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 @ o2``.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
 
    Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
@@ -146,6 +154,15 @@ Number Protocol
    the Python statement ``o1 *= o2``.
 
 
+.. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is
+   the equivalent of the Python statement ``o1 @= o2``.
+
+   .. versionadded:: 3.5
+
+
 .. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
 
    Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index 666de64..5d52315 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1121,6 +1121,9 @@ Number Object Structures
             binaryfunc nb_inplace_true_divide;
 
             unaryfunc nb_index;
+
+            binaryfunc nb_matrix_multiply;
+            binaryfunc nb_inplace_matrix_multiply;
        } PyNumberMethods;
 
    .. note::
diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index d86550f..fbabe35 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -364,6 +364,11 @@ result back on the stack.
    Implements ``TOS = TOS1 * TOS``.
 
 
+.. opcode:: BINARY_MATRIX_MULTIPLY
+
+   Implements ``TOS = TOS1 @ TOS``.
+
+
 .. opcode:: BINARY_FLOOR_DIVIDE
 
    Implements ``TOS = TOS1 // TOS``.
@@ -436,6 +441,11 @@ the original TOS1.
    Implements in-place ``TOS = TOS1 * TOS``.
 
 
+.. opcode:: INPLACE_MATRIX_MULTIPLY
+
+   Implements in-place ``TOS = TOS1 @ TOS``.
+
+
 .. opcode:: INPLACE_FLOOR_DIVIDE
 
    Implements in-place ``TOS = TOS1 // TOS``.
diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst
index 3bcbaa4..3654d13 100644
--- a/Doc/library/operator.rst
+++ b/Doc/library/operator.rst
@@ -138,6 +138,14 @@ The mathematical and bitwise operations are the most numerous:
    Return ``a * b``, for *a* and *b* numbers.
 
 
+.. function:: matmul(a, b)
+              __matmul__(a, b)
+
+   Return ``a @ b``.
+
+   .. versionadded:: 3.5
+
+
 .. function:: neg(obj)
               __neg__(obj)
 
@@ -400,6 +408,8 @@ Python syntax and the functions in the :mod:`operator` module.
 +-----------------------+-------------------------+---------------------------------------+
 | Multiplication        | ``a * b``               | ``mul(a, b)``                         |
 +-----------------------+-------------------------+---------------------------------------+
+| Matrix Multiplication | ``a @ b``               | ``matmul(a, b)``                      |
++-----------------------+-------------------------+---------------------------------------+
 | Negation (Arithmetic) | ``- a``                 | ``neg(a)``                            |
 +-----------------------+-------------------------+---------------------------------------+
 | Negation (Logical)    | ``not a``               | ``not_(a)``                           |
@@ -508,6 +518,14 @@ will perform the update, so no subsequent assignment is necessary:
    ``a = imul(a, b)`` is equivalent to ``a *= b``.
 
 
+.. function:: imatmul(a, b)
+              __imatmul__(a, b)
+
+   ``a = imatmul(a, b)`` is equivalent to ``a @= b``.
+
+   .. versionadded:: 3.5
+
+
 .. function:: ior(a, b)
               __ior__(a, b)
 
diff --git a/Doc/library/token.rst b/Doc/library/token.rst
index 4cd7098..88fb38b 100644
--- a/Doc/library/token.rst
+++ b/Doc/library/token.rst
@@ -93,6 +93,7 @@ The token constants are:
           DOUBLESLASH
           DOUBLESLASHEQUAL
           AT
+          ATEQUAL
           RARROW
           ELLIPSIS
           OP
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index ccaa4f7..825580a 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1970,6 +1970,7 @@ left undefined.
 .. method:: object.__add__(self, other)
             object.__sub__(self, other)
             object.__mul__(self, other)
+            object.__matmul__(self, other)
             object.__truediv__(self, other)
             object.__floordiv__(self, other)
             object.__mod__(self, other)
@@ -1986,15 +1987,16 @@ left undefined.
       builtin: pow
       builtin: pow
 
-   These methods are called to implement the binary arithmetic operations (``+``,
-   ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``, ``<<``,
-   ``>>``, ``&``, ``^``, ``|``).  For instance, to evaluate the expression
-   ``x + y``, where *x* is an instance of a class that has an :meth:`__add__`
-   method, ``x.__add__(y)`` is called.  The :meth:`__divmod__` method should be the
-   equivalent to using :meth:`__floordiv__` and :meth:`__mod__`; it should not be
-   related to :meth:`__truediv__`.  Note that :meth:`__pow__` should be defined
-   to accept an optional third argument if the ternary version of the built-in
-   :func:`pow` function is to be supported.
+   These methods are called to implement the binary arithmetic operations
+   (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
+   :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``).  For instance, to
+   evaluate the expression ``x + y``, where *x* is an instance of a class that
+   has an :meth:`__add__` method, ``x.__add__(y)`` is called.  The
+   :meth:`__divmod__` method should be the equivalent to using
+   :meth:`__floordiv__` and :meth:`__mod__`; it should not be related to
+   :meth:`__truediv__`.  Note that :meth:`__pow__` should be defined to accept
+   an optional third argument if the ternary version of the built-in :func:`pow`
+   function is to be supported.
 
    If one of those methods does not support the operation with the supplied
    arguments, it should return ``NotImplemented``.
@@ -2003,6 +2005,7 @@ left undefined.
 .. method:: object.__radd__(self, other)
             object.__rsub__(self, other)
             object.__rmul__(self, other)
+            object.__rmatmul__(self, other)
             object.__rtruediv__(self, other)
             object.__rfloordiv__(self, other)
             object.__rmod__(self, other)
@@ -2018,14 +2021,14 @@ left undefined.
       builtin: divmod
       builtin: pow
 
-   These methods are called to implement the binary arithmetic operations (``+``,
-   ``-``, ``*``, ``/``, ``//``, ``%``, :func:`divmod`, :func:`pow`, ``**``,
-   ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected (swapped) operands.
-   These functions are only called if the left operand does not support the
-   corresponding operation and the operands are of different types. [#]_  For
-   instance, to evaluate the expression ``x - y``, where *y* is an instance of
-   a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)`` is called if
-   ``x.__sub__(y)`` returns *NotImplemented*.
+   These methods are called to implement the binary arithmetic operations
+   (``+``, ``-``, ``*``, ``@``, ``/``, ``//``, ``%``, :func:`divmod`,
+   :func:`pow`, ``**``, ``<<``, ``>>``, ``&``, ``^``, ``|``) with reflected
+   (swapped) operands.  These functions are only called if the left operand does
+   not support the corresponding operation and the operands are of different
+   types. [#]_ For instance, to evaluate the expression ``x - y``, where *y* is
+   an instance of a class that has an :meth:`__rsub__` method, ``y.__rsub__(x)``
+   is called if ``x.__sub__(y)`` returns *NotImplemented*.
 
    .. index:: builtin: pow
 
@@ -2043,6 +2046,7 @@ left undefined.
 .. method:: object.__iadd__(self, other)
             object.__isub__(self, other)
             object.__imul__(self, other)
+            object.__imatmul__(self, other)
             object.__itruediv__(self, other)
             object.__ifloordiv__(self, other)
             object.__imod__(self, other)
@@ -2054,17 +2058,17 @@ left undefined.
             object.__ior__(self, other)
 
    These methods are called to implement the augmented arithmetic assignments
-   (``+=``, ``-=``, ``*=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``, ``>>=``,
-   ``&=``, ``^=``, ``|=``).  These methods should attempt to do the operation
-   in-place (modifying *self*) and return the result (which could be, but does
-   not have to be, *self*).  If a specific method is not defined, the augmented
-   assignment falls back to the normal methods.  For instance, if *x* is an
-   instance of a class with an :meth:`__iadd__` method, ``x += y`` is equivalent
-   to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and ``y.__radd__(x)``
-   are considered, as with the evaluation of ``x + y``. In certain situations,
-   augmented assignment can result in unexpected errors (see
-   :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in
-   fact part of the data model.
+   (``+=``, ``-=``, ``*=``, ``@=``, ``/=``, ``//=``, ``%=``, ``**=``, ``<<=``,
+   ``>>=``, ``&=``, ``^=``, ``|=``).  These methods should attempt to do the
+   operation in-place (modifying *self*) and return the result (which could be,
+   but does not have to be, *self*).  If a specific method is not defined, the
+   augmented assignment falls back to the normal methods.  For instance, if *x*
+   is an instance of a class with an :meth:`__iadd__` method, ``x += y`` is
+   equivalent to ``x = x.__iadd__(y)`` . Otherwise, ``x.__add__(y)`` and
+   ``y.__radd__(x)`` are considered, as with the evaluation of ``x + y``. In
+   certain situations, augmented assignment can result in unexpected errors (see
+   :ref:`faq-augmented-assignment-tuple-error`), but this behavior is in fact
+   part of the data model.
 
 
 .. method:: object.__neg__(self)
diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst
index 06baba0..5b92a48 100644
--- a/Doc/reference/expressions.rst
+++ b/Doc/reference/expressions.rst
@@ -892,8 +892,9 @@ from the power operator, there are only two levels, one for multiplicative
 operators and one for additive operators:
 
 .. productionlist::
-   m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "//" `u_expr` | `m_expr` "/" `u_expr`
-         : | `m_expr` "%" `u_expr`
+   m_expr: `u_expr` | `m_expr` "*" `u_expr` | `m_expr` "@" `m_expr` |
+         : `m_expr` "//" `u_expr`| `m_expr` "/" `u_expr` |
+         : `m_expr` "%" `u_expr`
    a_expr: `m_expr` | `a_expr` "+" `m_expr` | `a_expr` "-" `m_expr`
 
 .. index:: single: multiplication
@@ -904,6 +905,13 @@ the other must be a sequence. In the former case, the numbers are converted to a
 common type and then multiplied together.  In the latter case, sequence
 repetition is performed; a negative repetition factor yields an empty sequence.
 
+.. index:: single: matrix multiplication
+
+The ``@`` (at) operator is intended to be used for matrix multiplication.  No
+builtin Python types implement this operator.
+
+.. versionadded:: 3.5
+
 .. index::
    exception: ZeroDivisionError
    single: division
@@ -1346,8 +1354,9 @@ groups from right to left).
 +-----------------------------------------------+-------------------------------------+
 | ``+``, ``-``                                  | Addition and subtraction            |
 +-----------------------------------------------+-------------------------------------+
-| ``*``, ``/``, ``//``, ``%``                   | Multiplication, division, remainder |
-|                                               | [#]_                                |
+| ``*``, ``@``, ``/``, ``//``, ``%``            | Multiplication, matrix              |
+|                                               | multiplication division,            |
+|                                               | remainder [#]_                      |
 +-----------------------------------------------+-------------------------------------+
 | ``+x``, ``-x``, ``~x``                        | Positive, negative, bitwise NOT     |
 +-----------------------------------------------+-------------------------------------+
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 40bbc39..799c323 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -267,7 +267,7 @@ operation and an assignment statement:
 .. productionlist::
    augmented_assignment_stmt: `augtarget` `augop` (`expression_list` | `yield_expression`)
    augtarget: `identifier` | `attributeref` | `subscription` | `slicing`
-   augop: "+=" | "-=" | "*=" | "/=" | "//=" | "%=" | "**="
+   augop: "+=" | "-=" | "*=" | "@=" | "/=" | "//=" | "%=" | "**="
         : | ">>=" | "<<=" | "&=" | "^=" | "|="
 
 (See section :ref:`primaries` for the syntax definitions for the last three