special_methods_table.rst 22.2 KB
Newer Older
Craig Citro's avatar
Craig Citro committed
1 2
.. _special_methods_table:

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
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                                       |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
42 43
| __getattribute__      |self, name                             | object      | Get attribute, unconditionally                      |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
| __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                              |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+
110
| __index__             | self                                  | object      | Convert to sequence index                           |
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+

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.
204
    See also :PEP:`252`, "Making Types Look More Like Classes", and :PEP:`253`,
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
    "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                                |
+-----------------------+---------------------------------------+-------------+-----------------------------------------------------+