Merge pull request #2400 from gabrieldemarmiesse/special_method_table

Removed outdated "Special Methods Table" and put a link to the most recent version.

docs/src/reference/special_methods_table.rst

-.. _special_methods_table:
-
 Special Methods Table
 ---------------------
 
-This table lists all of the special methods together with their parameter and
-return types. In the table below, a parameter name of self is used to indicate
-that the parameter has the type that the method belongs to. Other parameters
-with no type specified in the table are generic Python objects.
-
-You don't have to declare your method as taking these parameter types. If you
-declare different types, conversions will be performed as necessary.
+You can find an updated version of the special methods table
+in :ref:`special_methods_table`.
 
 General
 ^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __cinit__             |self, ...                              |             | Basic initialisation (no direct Python equivalent)  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __init__              |self, ...                              |             | Further initialisation                              |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __dealloc__           |self                                   |             | Basic deallocation (no direct Python equivalent)    |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __cmp__               |x, y                                   | int         | 3-way comparison                                    |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __str__               |self                                   | object      | str(self)                                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __repr__              |self                                   | object      | repr(self)                                          |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __hash__              |self                                   | int         | Hash function                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __call__              |self, ...                              | object      | self(...)                                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __iter__              |self                                   | object      | Return iterator for sequence                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getattr__           |self, name                             | object      | Get attribute                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getattribute__      |self, name                             | object      | Get attribute, unconditionally                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __setattr__           |self, name, val                        |             | Set attribute                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __delattr__           |self, name                             |             | Delete attribute                                    |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Rich comparison operators
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __richcmp__           |x, y, int op                           | object      | Rich comparison (no direct Python equivalent)       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __eq__                |x, y                                   | object      | x == y                                              |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ne__                |x, y                                   | object      | x != y  (falls back to ``__eq__`` if not available) |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __lt__                |x, y                                   | object      | x < y                                               |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __gt__                |x, y                                   | object      | x > y                                               |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __le__                |x, y                                   | object      | x <= y                                              |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ge__                |x, y                                   | object      | x >= y                                              |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Arithmetic operators
 ^^^^^^^^^^^^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __add__               | x, y                                  | object      | binary `+` operator                                 |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __sub__               | x, y                                  | object      | binary `-` operator                                 |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __mul__               | x, y                                  | object      | `*` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __div__               | x, y                                  | object      | `/`  operator for old-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __floordiv__          | x, y                                  | object      | `//`  operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __truediv__           | x, y                                  | object      | `/`  operator for new-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __mod__               | x, y                                  | object      | `%` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __divmod__            | x, y                                  | object      | combined div and mod                                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __pow__               | x, y, z                               | object      | `**` operator or pow(x, y, z)                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __neg__               | self                                  | object      | unary `-` operator                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __pos__               | self                                  | object      | unary `+` operator                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __abs__               | self                                  | object      | absolute value                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __nonzero__           | self                                  | int         | convert to boolean                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __invert__            | self                                  | object      | `~` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __lshift__            | x, y                                  | object      | `<<` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __rshift__            | x, y                                  | object      | `>>` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __and__               | x, y                                  | object      | `&` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __or__                | x, y                                  | object      | `|` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __xor__               | x, y                                  | object      | `^` operator                                        |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Numeric conversions
 ^^^^^^^^^^^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __int__               | self                                  | object      | Convert to integer                                  |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __long__              | self                                  | object      | Convert to long integer                             |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __float__             | self                                  | object      | Convert to float                                    |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __oct__               | self                                  | object      | Convert to octal                                    |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __hex__               | self                                  | object      | Convert to hexadecimal                              |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __index__             | self                                  | object      | Convert to sequence index                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 In-place arithmetic operators
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __iadd__              | self, x                               | object      | `+=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __isub__              | self, x                               | object      | `-=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __imul__              | self, x                               | object      | `*=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __idiv__              | self, x                               | object      | `/=` operator for old-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ifloordiv__         | self, x                               | object      | `//=` operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __itruediv__          | self, x                               | object      | `/=` operator for new-style division                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __imod__              | self, x                               | object      | `%=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ipow__              | x, y, z                               | object      | `**=` operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ilshift__           | self, x                               | object      | `<<=` operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __irshift__           | self, x                               | object      | `>>=` operator                                      |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __iand__              | self, x                               | object      | `&=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ior__               | self, x                               | object      | `|=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __ixor__              | self, x                               | object      | `^=` operator                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Sequences and mappings
 ^^^^^^^^^^^^^^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __len__               | self  int                             |             | len(self)                                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getitem__           | self, x                               | object      | self[x]                                             |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __setitem__           | self, x, y                            |             | self[x] = y                                         |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __delitem__           | self, x                               |             | del self[x]                                         |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getslice__          | self, Py_ssize_t i, Py_ssize_t j      | object      | self[i:j]                                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __setslice__          | self, Py_ssize_t i, Py_ssize_t j, x   |             | self[i:j] = x                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __delslice__          | self, Py_ssize_t i, Py_ssize_t j      |             | del self[i:j]                                       |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __contains__          | self, x                               | int         | x in self                                           |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Iterators
 ^^^^^^^^^
 
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __next__              | self                                  | object      | Get next item (called next in Python)               |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Buffer interface
 ^^^^^^^^^^^^^^^^
 
-.. note::
-    The buffer interface is intended for use by C code and is not directly
-    accessible from Python. It is described in the Python/C API Reference Manual
-    under sections 6.6 and 10.6.
-
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __getreadbuffer__     | self, int i, void `**p`               |             |                                                     |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getwritebuffer__    | self, int i, void `**p`               |             |                                                     |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getsegcount__       | self, int `*p`                        |             |                                                     |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __getcharbuffer__     | self, int i, char `**p`               |             |                                                     |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
 Descriptor objects
 ^^^^^^^^^^^^^^^^^^
-
-.. note::
-    Descriptor objects are part of the support mechanism for new-style
-    Python classes. See the discussion of descriptors in the Python documentation.
-    See also :PEP:`252`, "Making Types Look More Like Classes", and :PEP:`253`,
-    "Subtyping Built-In Types".
-
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| Name                  | Parameters                            | Return type |     Description                                     |
-+=======================+=======================================+=============+=====================================================+
-| __get__               | self, instance, class                 | object      |     Get value of attribute                          |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __set__               | self, instance, value                 |             |     Set value of attribute                          |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-| __delete__            | self, instance                        |             |     Delete attribute                                |
-+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
-
-
-
-
-

docs/src/userguide/special_methods.rst

@@ -185,6 +185,8 @@ method called :meth:`__next__`, not next. The Python system will automatically
 supply a next method which calls your :meth:`__next__`. Do *NOT* explicitly
 give your type a :meth:`next` method, or bad things could happen.
 
+.. _special_methods_table:
+
 Special Method Table
 ---------------------