.. _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.

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                                    |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
| __richcmp__           |x, y, int op                           | object      | Rich comparison (no direct Python equivalent)       |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
| __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                                    |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+

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                                |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+