From 0addc4378c950a505e6b6e1a650d607ba0ba2e3f Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Mon, 9 Mar 2020 23:27:05 -0400 Subject: [PATCH 01/35] Add cutprefix and cutsuffix methods to str, bytes, and bytearray. --- Lib/test/string_tests.py | 34 +++++++++++++ Objects/bytearrayobject.c | 65 ++++++++++++++++++++++++ Objects/bytesobject.c | 64 ++++++++++++++++++++++++ Objects/clinic/bytearrayobject.c.h | 80 +++++++++++++++++++++++++++++- Objects/clinic/bytesobject.c.h | 80 +++++++++++++++++++++++++++++- Objects/clinic/unicodeobject.c.h | 72 ++++++++++++++++++++++++++- Objects/unicodeobject.c | 56 +++++++++++++++++++++ 7 files changed, 448 insertions(+), 3 deletions(-) diff --git a/Lib/test/string_tests.py b/Lib/test/string_tests.py index 948e2a3c3c56b0..51dd4a3afb0555 100644 --- a/Lib/test/string_tests.py +++ b/Lib/test/string_tests.py @@ -682,6 +682,40 @@ def test_replace_overflow(self): self.checkraises(OverflowError, A2_16, "replace", "A", A2_16) self.checkraises(OverflowError, A2_16, "replace", "AA", A2_16+A2_16) + def test_cutprefix(self): + self.checkequal('am', 'spam', 'cutprefix', 'sp') + self.checkequal('spamspam', 'spamspamspam', 'cutprefix', 'spam') + self.checkequal('spam', 'spam', 'cutprefix', 'python') + self.checkequal('spam', 'spam', 'cutprefix', 'spider') + self.checkequal('spam', 'spam', 'cutprefix', 'spam and eggs') + + self.checkequal('', '', 'cutprefix', '') + self.checkequal('', '', 'cutprefix', 'abcde') + self.checkequal('abcde', 'abcde', 'cutprefix', '') + self.checkequal('', 'abcde', 'cutprefix', 'abcde') + + self.checkraises(TypeError, 'hello', 'cutprefix') + self.checkraises(TypeError, 'hello', 'cutprefix', 42) + self.checkraises(TypeError, 'hello', 'cutprefix', 42, 'h') + self.checkraises(TypeError, 'hello', 'cutprefix', 'h', 42) + + def test_cutsuffix(self): + self.checkequal('sp', 'spam', 'cutsuffix', 'am') + self.checkequal('spamspam', 'spamspamspam', 'cutsuffix', 'spam') + self.checkequal('spam', 'spam', 'cutsuffix', 'python') + self.checkequal('spam', 'spam', 'cutsuffix', 'blam') + self.checkequal('spam', 'spam', 'cutsuffix', 'eggs and spam') + + self.checkequal('', '', 'cutsuffix', '') + self.checkequal('', '', 'cutsuffix', 'abcde') + self.checkequal('abcde', 'abcde', 'cutsuffix', '') + self.checkequal('', 'abcde', 'cutsuffix', 'abcde') + + self.checkraises(TypeError, 'hello', 'cutsuffix') + self.checkraises(TypeError, 'hello', 'cutsuffix', 42) + self.checkraises(TypeError, 'hello', 'cutsuffix', 42, 'h') + self.checkraises(TypeError, 'hello', 'cutsuffix', 'h', 42) + def test_capitalize(self): self.checkequal(' hello ', ' hello ', 'capitalize') self.checkequal('Hello ', 'Hello ','capitalize') diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index d3964358bc59de..1f5395f3817ecf 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1185,6 +1185,69 @@ bytearray_endswith(PyByteArrayObject *self, PyObject *args) return _Py_bytes_endswith(PyByteArray_AS_STRING(self), PyByteArray_GET_SIZE(self), args); } +/*[clinic input] +bytearray.cutprefix as bytearray_cutprefix + + prefix: Py_buffer + / + +Return a copy of the bytearray with a given prefix removed if present. + +If the bytearray starts with the prefix, return b[len(prefix):]. +Otherwise, return a copy of the original bytearray. +[clinic start generated code]*/ + +static PyObject * +bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) +/*[clinic end generated code: output=21632e315d769b4b input=1848afa62344e091]*/ +{ + const char* self_start = PyByteArray_AS_STRING(self); + Py_ssize_t self_len = PyByteArray_GET_SIZE(self); + const char* prefix_start = prefix->buf; + Py_ssize_t prefix_len = prefix->len; + + if (self_len >= prefix_len + && memcmp(self_start, prefix_start, prefix_len) == 0) + { + return PyByteArray_FromStringAndSize(self_start + prefix_len, + self_len - prefix_len); + } + + return PyByteArray_FromStringAndSize(self_start, self_len); +} + +/*[clinic input] +bytearray.cutsuffix as bytearray_cutsuffix + + suffix: Py_buffer + / + +Return a copy of the bytearray with a given suffix removed if present. + +If the bytearray ends with the suffix, return b[:len(b)-len(suffix)]. +Otherwise, return a copy of the original bytearray. +[clinic start generated code]*/ + +static PyObject * +bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) +/*[clinic end generated code: output=9862e6f256b4e5a0 input=8f8c10709806b42b]*/ +{ + const char* self_start = PyByteArray_AS_STRING(self); + Py_ssize_t self_len = PyByteArray_GET_SIZE(self); + const char* suffix_start = suffix->buf; + Py_ssize_t suffix_len = suffix->len; + + if (self_len >= suffix_len + && memcmp(self_start + self_len - suffix_len, + suffix_start, suffix_len) == 0) + { + return PyByteArray_FromStringAndSize(self_start, + self_len - suffix_len); + } + + return PyByteArray_FromStringAndSize(self_start, self_len); +} + /*[clinic input] bytearray.translate @@ -2207,6 +2270,8 @@ bytearray_methods[] = { BYTEARRAY_POP_METHODDEF BYTEARRAY_REMOVE_METHODDEF BYTEARRAY_REPLACE_METHODDEF + BYTEARRAY_CUTPREFIX_METHODDEF + BYTEARRAY_CUTSUFFIX_METHODDEF BYTEARRAY_REVERSE_METHODDEF {"rfind", (PyCFunction)bytearray_rfind, METH_VARARGS, _Py_rfind__doc__}, {"rindex", (PyCFunction)bytearray_rindex, METH_VARARGS, _Py_rindex__doc__}, diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index bd8af72ade5d3d..738ce6f1886d7f 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2181,6 +2181,68 @@ bytes_replace_impl(PyBytesObject *self, Py_buffer *old, Py_buffer *new, /** End DALKE **/ +/*[clinic input] +bytes.cutprefix as bytes_cutprefix + + prefix: Py_buffer + / + +Remove a specified prefix, if present. + +If the bytes starts with the prefix, return b[len(prefix):]. +Otherwise, return the original bytes. +[clinic start generated code]*/ + +static PyObject * +bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) +/*[clinic end generated code: output=5e5ef0cf576a8a9c input=f5409d4eb86164e8]*/ +{ + const char *self_start = PyBytes_AS_STRING(self); + Py_ssize_t self_len = PyBytes_GET_SIZE(self); + const char *prefix_start = prefix->buf; + Py_ssize_t prefix_len = prefix->len; + + if (self_len >= prefix_len + && memcmp(self_start, prefix_start, prefix_len) == 0) + { + return PyBytes_FromStringAndSize(self_start + prefix_len, + self_len - prefix_len); + } + + return PyBytes_FromStringAndSize(self_start, self_len); +} + +/*[clinic input] +bytes.cutsuffix as bytes_cutsuffix + + suffix: Py_buffer + / + +Remove a specified suffix, if present. + +If the bytes ends with the suffix, return b[:len(b)-len(prefix)]. +Otherwise, return the original bytes. +[clinic start generated code]*/ + +static PyObject * +bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) +/*[clinic end generated code: output=303549ce0a999724 input=5e4ee249c40f7bf6]*/ +{ + const char* self_start = PyBytes_AS_STRING(self); + Py_ssize_t self_len = PyBytes_GET_SIZE(self); + const char* suffix_start = suffix->buf; + Py_ssize_t suffix_len = suffix->len; + + if (self_len >= suffix_len + && memcmp(self_start + self_len - suffix_len, + suffix_start, suffix_len) == 0) + { + return PyBytes_FromStringAndSize(self_start, + self_len - suffix_len); + } + + return PyBytes_FromStringAndSize(self_start, self_len); +} static PyObject * bytes_startswith(PyBytesObject *self, PyObject *args) @@ -2420,6 +2482,8 @@ bytes_methods[] = { BYTES_MAKETRANS_METHODDEF BYTES_PARTITION_METHODDEF BYTES_REPLACE_METHODDEF + BYTES_CUTPREFIX_METHODDEF + BYTES_CUTSUFFIX_METHODDEF {"rfind", (PyCFunction)bytes_rfind, METH_VARARGS, _Py_rfind__doc__}, {"rindex", (PyCFunction)bytes_rindex, METH_VARARGS, _Py_rindex__doc__}, STRINGLIB_RJUST_METHODDEF diff --git a/Objects/clinic/bytearrayobject.c.h b/Objects/clinic/bytearrayobject.c.h index 05577077a5f8d4..90a886e9df515f 100644 --- a/Objects/clinic/bytearrayobject.c.h +++ b/Objects/clinic/bytearrayobject.c.h @@ -38,6 +38,84 @@ bytearray_copy(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) return bytearray_copy_impl(self); } +PyDoc_STRVAR(bytearray_cutprefix__doc__, +"cutprefix($self, prefix, /)\n" +"--\n" +"\n" +"Return a copy of the bytearray with a given prefix removed if present.\n" +"\n" +"If the bytearray starts with the prefix, return b[len(prefix):].\n" +"Otherwise, return a copy of the original bytearray."); + +#define BYTEARRAY_CUTPREFIX_METHODDEF \ + {"cutprefix", (PyCFunction)bytearray_cutprefix, METH_O, bytearray_cutprefix__doc__}, + +static PyObject * +bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix); + +static PyObject * +bytearray_cutprefix(PyByteArrayObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + Py_buffer prefix = {NULL, NULL}; + + if (PyObject_GetBuffer(arg, &prefix, PyBUF_SIMPLE) != 0) { + goto exit; + } + if (!PyBuffer_IsContiguous(&prefix, 'C')) { + _PyArg_BadArgument("cutprefix", "argument", "contiguous buffer", arg); + goto exit; + } + return_value = bytearray_cutprefix_impl(self, &prefix); + +exit: + /* Cleanup for prefix */ + if (prefix.obj) { + PyBuffer_Release(&prefix); + } + + return return_value; +} + +PyDoc_STRVAR(bytearray_cutsuffix__doc__, +"cutsuffix($self, suffix, /)\n" +"--\n" +"\n" +"Return a copy of the bytearray with a given suffix removed if present.\n" +"\n" +"If the bytearray ends with the suffix, return b[:len(b)-len(suffix)].\n" +"Otherwise, return a copy of the original bytearray."); + +#define BYTEARRAY_CUTSUFFIX_METHODDEF \ + {"cutsuffix", (PyCFunction)bytearray_cutsuffix, METH_O, bytearray_cutsuffix__doc__}, + +static PyObject * +bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix); + +static PyObject * +bytearray_cutsuffix(PyByteArrayObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + Py_buffer suffix = {NULL, NULL}; + + if (PyObject_GetBuffer(arg, &suffix, PyBUF_SIMPLE) != 0) { + goto exit; + } + if (!PyBuffer_IsContiguous(&suffix, 'C')) { + _PyArg_BadArgument("cutsuffix", "argument", "contiguous buffer", arg); + goto exit; + } + return_value = bytearray_cutsuffix_impl(self, &suffix); + +exit: + /* Cleanup for suffix */ + if (suffix.obj) { + PyBuffer_Release(&suffix); + } + + return return_value; +} + PyDoc_STRVAR(bytearray_translate__doc__, "translate($self, table, /, delete=b\'\')\n" "--\n" @@ -1011,4 +1089,4 @@ bytearray_sizeof(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) { return bytearray_sizeof_impl(self); } -/*[clinic end generated code: output=508dce79cf2dffcc input=a9049054013a1b77]*/ +/*[clinic end generated code: output=e42aa99e5a589150 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index 22024ab155c8ec..d020dfb7619b52 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -526,6 +526,84 @@ bytes_replace(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs) return return_value; } +PyDoc_STRVAR(bytes_cutprefix__doc__, +"cutprefix($self, prefix, /)\n" +"--\n" +"\n" +"Remove a specified prefix, if present.\n" +"\n" +"If the bytes starts with the prefix, return b[len(prefix):].\n" +"Otherwise, return the original bytes."); + +#define BYTES_CUTPREFIX_METHODDEF \ + {"cutprefix", (PyCFunction)bytes_cutprefix, METH_O, bytes_cutprefix__doc__}, + +static PyObject * +bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix); + +static PyObject * +bytes_cutprefix(PyBytesObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + Py_buffer prefix = {NULL, NULL}; + + if (PyObject_GetBuffer(arg, &prefix, PyBUF_SIMPLE) != 0) { + goto exit; + } + if (!PyBuffer_IsContiguous(&prefix, 'C')) { + _PyArg_BadArgument("cutprefix", "argument", "contiguous buffer", arg); + goto exit; + } + return_value = bytes_cutprefix_impl(self, &prefix); + +exit: + /* Cleanup for prefix */ + if (prefix.obj) { + PyBuffer_Release(&prefix); + } + + return return_value; +} + +PyDoc_STRVAR(bytes_cutsuffix__doc__, +"cutsuffix($self, suffix, /)\n" +"--\n" +"\n" +"Remove a specified suffix, if present.\n" +"\n" +"If the bytes ends with the suffix, return b[:len(b)-len(prefix)].\n" +"Otherwise, return the original bytes."); + +#define BYTES_CUTSUFFIX_METHODDEF \ + {"cutsuffix", (PyCFunction)bytes_cutsuffix, METH_O, bytes_cutsuffix__doc__}, + +static PyObject * +bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix); + +static PyObject * +bytes_cutsuffix(PyBytesObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + Py_buffer suffix = {NULL, NULL}; + + if (PyObject_GetBuffer(arg, &suffix, PyBUF_SIMPLE) != 0) { + goto exit; + } + if (!PyBuffer_IsContiguous(&suffix, 'C')) { + _PyArg_BadArgument("cutsuffix", "argument", "contiguous buffer", arg); + goto exit; + } + return_value = bytes_cutsuffix_impl(self, &suffix); + +exit: + /* Cleanup for suffix */ + if (suffix.obj) { + PyBuffer_Release(&suffix); + } + + return return_value; +} + PyDoc_STRVAR(bytes_decode__doc__, "decode($self, /, encoding=\'utf-8\', errors=\'strict\')\n" "--\n" @@ -755,4 +833,4 @@ bytes_hex(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=ca60dfccf8d51e88 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=9e9fe9b5771cea06 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index 0d134064bab091..2e95db8bfd3d52 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -754,6 +754,76 @@ unicode_replace(PyObject *self, PyObject *const *args, Py_ssize_t nargs) return return_value; } +PyDoc_STRVAR(unicode_cutprefix__doc__, +"cutprefix($self, prefix, /)\n" +"--\n" +"\n" +"Remove a specified prefix, if present.\n" +"\n" +"If the string starts with the prefix, return string[len(prefix):].\n" +"Otherwise, return the original string."); + +#define UNICODE_CUTPREFIX_METHODDEF \ + {"cutprefix", (PyCFunction)unicode_cutprefix, METH_O, unicode_cutprefix__doc__}, + +static PyObject * +unicode_cutprefix_impl(PyObject *self, PyObject *prefix); + +static PyObject * +unicode_cutprefix(PyObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + PyObject *prefix; + + if (!PyUnicode_Check(arg)) { + _PyArg_BadArgument("cutprefix", "argument", "str", arg); + goto exit; + } + if (PyUnicode_READY(arg) == -1) { + goto exit; + } + prefix = arg; + return_value = unicode_cutprefix_impl(self, prefix); + +exit: + return return_value; +} + +PyDoc_STRVAR(unicode_cutsuffix__doc__, +"cutsuffix($self, suffix, /)\n" +"--\n" +"\n" +"Remove a specified suffix, if present.\n" +"\n" +"If the string starts with the suffix, return string[len(suffix):].\n" +"Otherwise, return the original string."); + +#define UNICODE_CUTSUFFIX_METHODDEF \ + {"cutsuffix", (PyCFunction)unicode_cutsuffix, METH_O, unicode_cutsuffix__doc__}, + +static PyObject * +unicode_cutsuffix_impl(PyObject *self, PyObject *suffix); + +static PyObject * +unicode_cutsuffix(PyObject *self, PyObject *arg) +{ + PyObject *return_value = NULL; + PyObject *suffix; + + if (!PyUnicode_Check(arg)) { + _PyArg_BadArgument("cutsuffix", "argument", "str", arg); + goto exit; + } + if (PyUnicode_READY(arg) == -1) { + goto exit; + } + suffix = arg; + return_value = unicode_cutsuffix_impl(self, suffix); + +exit: + return return_value; +} + PyDoc_STRVAR(unicode_rjust__doc__, "rjust($self, width, fillchar=\' \', /)\n" "--\n" @@ -1232,4 +1302,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return unicode_sizeof_impl(self); } -/*[clinic end generated code: output=e4ed33400979c7e8 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=94e6d11b96656992 input=a9049054013a1b77]*/ diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 3d99f11ecff6fe..39f6a0b5fbd644 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12757,6 +12757,60 @@ unicode_replace_impl(PyObject *self, PyObject *old, PyObject *new, return replace(self, old, new, count); } +/*[clinic input] +str.cutprefix as unicode_cutprefix + + prefix: unicode + / + +Remove a specified prefix, if present. + +If the string starts with the prefix, return string[len(prefix):]. +Otherwise, return the original string. +[clinic start generated code]*/ + +static PyObject * +unicode_cutprefix_impl(PyObject* self, PyObject* prefix) +/*[clinic end generated code: output=885902e3c7f5fae0 input=52efc288b6160337]*/ +{ + int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); + if (match == -1) { + return NULL; + } + if (match) { + return PyUnicode_Substring(self, PyUnicode_GET_LENGTH(prefix), + PyUnicode_GET_LENGTH(self)); + } + return unicode_result_unchanged(self); +} + +/*[clinic input] +str.cutsuffix as unicode_cutsuffix + + suffix: unicode + / + +Remove a specified suffix, if present. + +If the string starts with the suffix, return string[len(suffix):]. +Otherwise, return the original string. +[clinic start generated code]*/ + +static PyObject * +unicode_cutsuffix_impl(PyObject* self, PyObject* suffix) +/*[clinic end generated code: output=5e5babcd284e6e6e input=7cb8ec5dd6849be0]*/ +{ + int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); + if (match == -1) { + return NULL; + } + if (match) { + return PyUnicode_Substring(self, 0, PyUnicode_GET_LENGTH(self) + - PyUnicode_GET_LENGTH(suffix)); + } + return unicode_result_unchanged(self); +} + static PyObject * unicode_repr(PyObject *unicode) { @@ -14070,6 +14124,8 @@ static PyMethodDef unicode_methods[] = { UNICODE_UPPER_METHODDEF {"startswith", (PyCFunction) unicode_startswith, METH_VARARGS, startswith__doc__}, {"endswith", (PyCFunction) unicode_endswith, METH_VARARGS, endswith__doc__}, + UNICODE_CUTPREFIX_METHODDEF + UNICODE_CUTSUFFIX_METHODDEF UNICODE_ISASCII_METHODDEF UNICODE_ISLOWER_METHODDEF UNICODE_ISUPPER_METHODDEF From 3adb9fadeba51d43f17e7d1cdae16c6589ba2656 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 13:50:39 -0400 Subject: [PATCH 02/35] pep 7: lining up argumenets --- CppProperties.json | 21 + Doc/c-api/call.rst.bak | 411 +++ Doc/c-api/structures.rst.bak | 401 +++ Doc/c-api/type.rst.bak | 209 ++ Doc/c-api/typeobj.rst.bak | 2565 +++++++++++++++++ Doc/library/fractions.rst.bak | 178 ++ Doc/library/os.rst.bak | 4513 ++++++++++++++++++++++++++++++ Doc/library/pty.rst.bak | 114 + Doc/library/stdtypes.rst.bak | 4885 +++++++++++++++++++++++++++++++++ Doc/library/sys.rst.bak | 1652 +++++++++++ Doc/library/typing.rst.bak | 1374 ++++++++++ Doc/tutorial/errors.rst.bak | 474 ++++ Doc/whatsnew/3.8.rst.bak | 2216 +++++++++++++++ Doc/whatsnew/3.9.rst.bak | 540 ++++ Objects/unicodeobject.c | 4 +- 15 files changed, 19555 insertions(+), 2 deletions(-) create mode 100644 CppProperties.json create mode 100644 Doc/c-api/call.rst.bak create mode 100644 Doc/c-api/structures.rst.bak create mode 100644 Doc/c-api/type.rst.bak create mode 100644 Doc/c-api/typeobj.rst.bak create mode 100644 Doc/library/fractions.rst.bak create mode 100644 Doc/library/os.rst.bak create mode 100644 Doc/library/pty.rst.bak create mode 100644 Doc/library/stdtypes.rst.bak create mode 100644 Doc/library/sys.rst.bak create mode 100644 Doc/library/typing.rst.bak create mode 100644 Doc/tutorial/errors.rst.bak create mode 100644 Doc/whatsnew/3.8.rst.bak create mode 100644 Doc/whatsnew/3.9.rst.bak diff --git a/CppProperties.json b/CppProperties.json new file mode 100644 index 00000000000000..659bf4ea9068f8 --- /dev/null +++ b/CppProperties.json @@ -0,0 +1,21 @@ +{ + "configurations": [ + { + "inheritEnvironments": [ + "msvc_x86" + ], + "name": "x86-Debug", + "includePath": [ + "${env.INCLUDE}", + "${workspaceRoot}\\**" + ], + "defines": [ + "WIN32", + "_DEBUG", + "UNICODE", + "_UNICODE" + ], + "intelliSenseMode": "windows-msvc-x86" + } + ] +} \ No newline at end of file diff --git a/Doc/c-api/call.rst.bak b/Doc/c-api/call.rst.bak new file mode 100644 index 00000000000000..0833531b1d5ee1 --- /dev/null +++ b/Doc/c-api/call.rst.bak @@ -0,0 +1,411 @@ +.. highlight:: c + +.. _call: + +Call Protocol +============= + +CPython supports two different calling protocols: +*tp_call* and vectorcall. + +The *tp_call* Protocol +---------------------- + +Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable. +The signature of the slot is:: + + PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs); + +A call is made using a tuple for the positional arguments +and a dict for the keyword arguments, similarly to +``callable(*args, **kwargs)`` in Python code. +*args* must be non-NULL (use an empty tuple if there are no arguments) +but *kwargs* may be *NULL* if there are no keyword arguments. + +This convention is not only used by *tp_call*: +:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` +also pass arguments this way. + +To call an object, use :c:func:`PyObject_Call` or other +:ref:`call API `. + + +.. _vectorcall: + +The Vectorcall Protocol +----------------------- + +.. versionadded:: 3.8 + +The vectorcall protocol was introduced in :pep:`590` as an additional protocol +for making calls more efficient. + +.. warning:: + + The vectorcall API is provisional and expected to become public in + Python 3.9, with a different names and, possibly, changed semantics. + If you use the it, plan for updating your code for Python 3.9. + +As rule of thumb, CPython will prefer the vectorcall for internal calls +if the callable supports it. However, this is not a hard rule. +Additionally, some third-party extensions use *tp_call* directly +(rather than using :c:func:`PyObject_Call`). +Therefore, a class supporting vectorcall must also implement +:c:member:`~PyTypeObject.tp_call`. +Moreover, the callable must behave the same +regardless of which protocol is used. +The recommended way to achieve this is by setting +:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`. +This bears repeating: + +.. warning:: + + A class supporting vectorcall **must** also implement + :c:member:`~PyTypeObject.tp_call` with the same semantics. + +A class should not implement vectorcall if that would be slower +than *tp_call*. For example, if the callee needs to convert +the arguments to an args tuple and kwargs dict anyway, then there is no point +in implementing vectorcall. + +Classes can implement the vectorcall protocol by enabling the +:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting +:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the +object structure where a *vectorcallfunc* appears. +This is a pointer to a function with the following signature: + +.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) + +- *callable* is the object being called. +- *args* is a C array consisting of the positional arguments followed by the + values of the keyword arguments. + This can be *NULL* if there are no arguments. +- *nargsf* is the number of positional arguments plus possibly the + :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag. + To get the actual number of positional arguments from *nargsf*, + use :c:func:`PyVectorcall_NARGS`. +- *kwnames* is a tuple containing the names of the keyword arguments; + in other words, the keys of the kwargs dict. + These names must be strings (instances of ``str`` or a subclass) + and they must be unique. + If there are no keyword arguments, then *kwnames* can instead be *NULL*. + +.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET + + If this flag is set in a vectorcall *nargsf* argument, the callee is allowed + to temporarily change ``args[-1]``. In other words, *args* points to + argument 1 (not 0) in the allocated vector. + The callee must restore the value of ``args[-1]`` before returning. + + For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that + ``args[0]`` may be changed. + + Whenever they can do so cheaply (without additional allocation), callers + are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`. + Doing so will allow callables such as bound methods to make their onward + calls (which include a prepended *self* argument) very efficiently. + +To call an object that implements vectorcall, use a :ref:`call API ` +function as with any other callable. +:c:func:`_PyObject_Vectorcall` will usually be most efficient. + + +Recursion Control +................. + +When using *tp_call*, callees do not need to worry about +:ref:`recursion `: CPython uses +:c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall` +for calls made using *tp_call*. + +For efficiency, this is not the case for calls done using vectorcall: +the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* +if needed. + + +Vectorcall Support API +...................... + +.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf) + + Given a vectorcall *nargsf* argument, return the actual number of + arguments. + Currently equivalent to:: + + (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET) + + However, the function ``PyVectorcall_NARGS`` should be used to allow + for future extensions. + + .. versionadded:: 3.8 + +.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op) + + If *op* does not support the vectorcall protocol (either because the type + does not or because the specific instance does not), return *NULL*. + Otherwise, return the vectorcall function pointer stored in *op*. + This function never raises an exception. + + This is mostly useful to check whether or not *op* supports vectorcall, + which can be done by checking ``_PyVectorcall_Function(op) != NULL``. + + .. versionadded:: 3.8 + +.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict) + + Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword + arguments given in a tuple and dict, respectively. + + This is a specialized function, intended to be put in the + :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``. + It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag + and it does not fall back to ``tp_call``. + + .. versionadded:: 3.8 + + +.. _capi-call: + +Object Calling API +------------------ + +Various functions are available for calling a Python object. +Each converts its arguments to a convention supported by the called object – +either *tp_call* or vectorcall. +In order to do as litle conversion as possible, pick one that best fits +the format of data you have available. + +The following table summarizes the available functions; +please see individual documentation for details. + ++------------------------------------------+------------------+--------------------+---------------+ +| Function | callable | args | kwargs | ++==========================================+==================+====================+===============+ +| :c:func:`PyObject_Call` | ``PyObject *`` | tuple | dict/``NULL`` | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallFunction` | ``PyObject *`` | format | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallMethod` | obj + ``char*`` | format | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallFunctionObjArgs` | ``PyObject *`` | variadic | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` | ++------------------------------------------+------------------+--------------------+---------------+ +| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall | ++------------------------------------------+------------------+--------------------+---------------+ + + +.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs) + + Call a callable Python object *callable*, with arguments given by the + tuple *args*, and named arguments given by the dictionary *kwargs*. + + *args* must not be *NULL*; use an empty tuple if no arguments are needed. + If no named arguments are needed, *kwargs* can be *NULL*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: + ``callable(*args, **kwargs)``. + + +.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable) + + Call a callable Python object *callable* without any arguments. It is the + most efficient way to call a callable Python object without any argument. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. versionadded:: 3.9 + + +.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg) + + Call a callable Python object *callable* with exactly 1 positional argument + *arg* and no keyword arguments. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. versionadded:: 3.9 + + +.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args) + + Call a callable Python object *callable*, with arguments given by the + tuple *args*. If no arguments are needed, then *args* can be *NULL*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: ``callable(*args)``. + + +.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...) + + Call a callable Python object *callable*, with a variable number of C arguments. + The C arguments are described using a :c:func:`Py_BuildValue` style format + string. The format can be *NULL*, indicating that no arguments are provided. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: ``callable(*args)``. + + Note that if you only pass :c:type:`PyObject \*` args, + :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. + + .. versionchanged:: 3.4 + The type of *format* was changed from ``char *``. + + +.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...) + + Call the method named *name* of object *obj* with a variable number of C + arguments. The C arguments are described by a :c:func:`Py_BuildValue` format + string that should produce a tuple. + + The format can be *NULL*, indicating that no arguments are provided. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: + ``obj.name(arg1, arg2, ...)``. + + Note that if you only pass :c:type:`PyObject \*` args, + :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. + + .. versionchanged:: 3.4 + The types of *name* and *format* were changed from ``char *``. + + +.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) + + Call a callable Python object *callable*, with a variable number of + :c:type:`PyObject \*` arguments. The arguments are provided as a variable number + of parameters followed by *NULL*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + This is the equivalent of the Python expression: + ``callable(arg1, arg2, ...)``. + + +.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL) + + Call a method of the Python object *obj*, where the name of the method is given as a + Python string object in *name*. It is called with a variable number of + :c:type:`PyObject \*` arguments. The arguments are provided as a variable number + of parameters followed by *NULL*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + +.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name) + + Call a method of the Python object *obj* without arguments, + where the name of the method is given as a Python string object in *name*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. versionadded:: 3.9 + + +.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg) + + Call a method of the Python object *obj* with a single positional argument + *arg*, where the name of the method is given as a Python string object in + *name*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. versionadded:: 3.9 + + +.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) + + Call a callable Python object *callable*. + The arguments are the same as for :c:type:`vectorcallfunc`. + If *callable* supports vectorcall_, this directly calls + the vectorcall function stored in *callable*. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. note:: + + This function is provisional and expected to become public in Python 3.9, + with a different name and, possibly, changed semantics. + If you use the function, plan for updating your code for Python 3.9. + + .. versionadded:: 3.8 + +.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict) + + Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol, + but with keyword arguments passed as a dictionary *kwdict*. + The *args* array contains only the positional arguments. + + Regardless of which protocol is used internally, + a conversion of arguments needs to be done. + Therefore, this function should only be used if the caller + already has a dictionary ready to use for the keyword arguments, + but not a tuple for the positional arguments. + + .. note:: + + This function is provisional and expected to become public in Python 3.9, + with a different name and, possibly, changed semantics. + If you use the function, plan for updating your code for Python 3.9. + + .. versionadded:: 3.8 + +.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames) + + Call a method using the vectorcall calling convention. The name of the method + is given as a Python string *name*. The object whose method is called is + *args[0]*, and the *args* array starting at *args[1]* represents the arguments + of the call. There must be at least one positional argument. + *nargsf* is the number of positional arguments including *args[0]*, + plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may + temporarily be changed. Keyword arguments can be passed just like in + :c:func:`_PyObject_Vectorcall`. + + If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, + this will call the unbound method object with the full + *args* vector as arguments. + + Return the result of the call on success, or raise an exception and return + *NULL* on failure. + + .. versionadded:: 3.9 + + +Call Support API +---------------- + +.. c:function:: int PyCallable_Check(PyObject *o) + + Determine if the object *o* is callable. Return ``1`` if the object is callable + and ``0`` otherwise. This function always succeeds. diff --git a/Doc/c-api/structures.rst.bak b/Doc/c-api/structures.rst.bak new file mode 100644 index 00000000000000..0c661389021eff --- /dev/null +++ b/Doc/c-api/structures.rst.bak @@ -0,0 +1,401 @@ +.. highlight:: c + +.. _common-structs: + +Common Object Structures +======================== + +There are a large number of structures which are used in the definition of +object types for Python. This section describes these structures and how they +are used. + + +Base object types and macros +---------------------------- + +All Python objects ultimately share a small number of fields at the beginning +of the object's representation in memory. These are represented by the +:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn, +by the expansions of some macros also used, whether directly or indirectly, in +the definition of all other Python objects. + + +.. c:type:: PyObject + + All object types are extensions of this type. This is a type which + contains the information Python needs to treat a pointer to an object as an + object. In a normal "release" build, it contains only the object's + reference count and a pointer to the corresponding type object. + Nothing is actually declared to be a :c:type:`PyObject`, but every pointer + to a Python object can be cast to a :c:type:`PyObject*`. Access to the + members must be done by using the macros :c:macro:`Py_REFCNT` and + :c:macro:`Py_TYPE`. + + +.. c:type:: PyVarObject + + This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size` + field. This is only used for objects that have some notion of *length*. + This type does not often appear in the Python/C API. + Access to the members must be done by using the macros + :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`. + + +.. c:macro:: PyObject_HEAD + + This is a macro used when declaring new types which represent objects + without a varying length. The PyObject_HEAD macro expands to:: + + PyObject ob_base; + + See documentation of :c:type:`PyObject` above. + + +.. c:macro:: PyObject_VAR_HEAD + + This is a macro used when declaring new types which represent objects + with a length that varies from instance to instance. + The PyObject_VAR_HEAD macro expands to:: + + PyVarObject ob_base; + + See documentation of :c:type:`PyVarObject` above. + + +.. c:macro:: Py_TYPE(o) + + This macro is used to access the :attr:`ob_type` member of a Python object. + It expands to:: + + (((PyObject*)(o))->ob_type) + + +.. c:macro:: Py_REFCNT(o) + + This macro is used to access the :attr:`ob_refcnt` member of a Python + object. + It expands to:: + + (((PyObject*)(o))->ob_refcnt) + + +.. c:macro:: Py_SIZE(o) + + This macro is used to access the :attr:`ob_size` member of a Python object. + It expands to:: + + (((PyVarObject*)(o))->ob_size) + + +.. c:macro:: PyObject_HEAD_INIT(type) + + This is a macro which expands to initialization values for a new + :c:type:`PyObject` type. This macro expands to:: + + _PyObject_EXTRA_INIT + 1, type, + + +.. c:macro:: PyVarObject_HEAD_INIT(type, size) + + This is a macro which expands to initialization values for a new + :c:type:`PyVarObject` type, including the :attr:`ob_size` field. + This macro expands to:: + + _PyObject_EXTRA_INIT + 1, type, size, + + +Implementing functions and methods +---------------------------------- + +.. c:type:: PyCFunction + + Type of the functions used to implement most Python callables in C. + Functions of this type take two :c:type:`PyObject\*` parameters and return + one such value. If the return value is ``NULL``, an exception shall have + been set. If not ``NULL``, the return value is interpreted as the return + value of the function as exposed in Python. The function must return a new + reference. + + +.. c:type:: PyCFunctionWithKeywords + + Type of the functions used to implement Python callables in C + with signature :const:`METH_VARARGS | METH_KEYWORDS`. + + +.. c:type:: _PyCFunctionFast + + Type of the functions used to implement Python callables in C + with signature :const:`METH_FASTCALL`. + + +.. c:type:: _PyCFunctionFastWithKeywords + + Type of the functions used to implement Python callables in C + with signature :const:`METH_FASTCALL | METH_KEYWORDS`. + + +.. c:type:: PyMethodDef + + Structure used to describe a method of an extension type. This structure has + four fields: + + +------------------+---------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+===============+===============================+ + | :attr:`ml_name` | const char \* | name of the method | + +------------------+---------------+-------------------------------+ + | :attr:`ml_meth` | PyCFunction | pointer to the C | + | | | implementation | + +------------------+---------------+-------------------------------+ + | :attr:`ml_flags` | int | flag bits indicating how the | + | | | call should be constructed | + +------------------+---------------+-------------------------------+ + | :attr:`ml_doc` | const char \* | points to the contents of the | + | | | docstring | + +------------------+---------------+-------------------------------+ + +The :attr:`ml_meth` is a C function pointer. The functions may be of different +types, but they always return :c:type:`PyObject\*`. If the function is not of +the :c:type:`PyCFunction`, the compiler will require a cast in the method table. +Even though :c:type:`PyCFunction` defines the first parameter as +:c:type:`PyObject\*`, it is common that the method implementation uses the +specific C type of the *self* object. + +The :attr:`ml_flags` field is a bitfield which can include the following flags. +The individual flags indicate either a calling convention or a binding +convention. + +There are four basic calling conventions for positional arguments +and two of them can be combined with :const:`METH_KEYWORDS` to support +also keyword arguments. So there are a total of 6 calling conventions: + +.. data:: METH_VARARGS + + This is the typical calling convention, where the methods have the type + :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values. + The first one is the *self* object for methods; for module functions, it is + the module object. The second parameter (often called *args*) is a tuple + object representing all arguments. This parameter is typically processed + using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. + + +.. data:: METH_VARARGS | METH_KEYWORDS + + Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. + The function expects three parameters: *self*, *args*, *kwargs* where + *kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` + if there are no keyword arguments. The parameters are typically processed + using :c:func:`PyArg_ParseTupleAndKeywords`. + + +.. data:: METH_FASTCALL + + Fast calling convention supporting only positional arguments. + The methods have the type :c:type:`_PyCFunctionFast`. + The first parameter is *self*, the second parameter is a C array + of :c:type:`PyObject\*` values indicating the arguments and the third + parameter is the number of arguments (the length of the array). + + This is not part of the :ref:`limited API `. + + .. versionadded:: 3.7 + + +.. data:: METH_FASTCALL | METH_KEYWORDS + + Extension of :const:`METH_FASTCALL` supporting also keyword arguments, + with methods of type :c:type:`_PyCFunctionFastWithKeywords`. + Keyword arguments are passed the same way as in the + :ref:`vectorcall protocol `: + there is an additional fourth :c:type:`PyObject\*` parameter + which is a tuple representing the names of the keyword arguments + (which are guaranteed to be strings) + or possibly ``NULL`` if there are no keywords. The values of the keyword + arguments are stored in the *args* array, after the positional arguments. + + This is not part of the :ref:`limited API `. + + .. versionadded:: 3.7 + + +.. data:: METH_NOARGS + + Methods without parameters don't need to check whether arguments are given if + they are listed with the :const:`METH_NOARGS` flag. They need to be of type + :c:type:`PyCFunction`. The first parameter is typically named *self* and will + hold a reference to the module or object instance. In all cases the second + parameter will be ``NULL``. + + +.. data:: METH_O + + Methods with a single object argument can be listed with the :const:`METH_O` + flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. + They have the type :c:type:`PyCFunction`, with the *self* parameter, and a + :c:type:`PyObject\*` parameter representing the single argument. + + +These two constants are not used to indicate the calling convention but the +binding when use with methods of classes. These may not be used for functions +defined for modules. At most one of these flags may be set for any given +method. + + +.. data:: METH_CLASS + + .. index:: builtin: classmethod + + The method will be passed the type object as the first parameter rather + than an instance of the type. This is used to create *class methods*, + similar to what is created when using the :func:`classmethod` built-in + function. + + +.. data:: METH_STATIC + + .. index:: builtin: staticmethod + + The method will be passed ``NULL`` as the first parameter rather than an + instance of the type. This is used to create *static methods*, similar to + what is created when using the :func:`staticmethod` built-in function. + +One other constant controls whether a method is loaded in place of another +definition with the same method name. + + +.. data:: METH_COEXIST + + The method will be loaded in place of existing definitions. Without + *METH_COEXIST*, the default is to skip repeated definitions. Since slot + wrappers are loaded before the method table, the existence of a + *sq_contains* slot, for example, would generate a wrapped method named + :meth:`__contains__` and preclude the loading of a corresponding + PyCFunction with the same name. With the flag defined, the PyCFunction + will be loaded in place of the wrapper object and will co-exist with the + slot. This is helpful because calls to PyCFunctions are optimized more + than wrapper object calls. + + +Accessing attributes of extension types +--------------------------------------- + +.. c:type:: PyMemberDef + + Structure which describes an attribute of a type which corresponds to a C + struct member. Its fields are: + + +------------------+---------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+===============+===============================+ + | :attr:`name` | const char \* | name of the member | + +------------------+---------------+-------------------------------+ + | :attr:`!type` | int | the type of the member in the | + | | | C struct | + +------------------+---------------+-------------------------------+ + | :attr:`offset` | Py_ssize_t | the offset in bytes that the | + | | | member is located on the | + | | | type's object struct | + +------------------+---------------+-------------------------------+ + | :attr:`flags` | int | flag bits indicating if the | + | | | field should be read-only or | + | | | writable | + +------------------+---------------+-------------------------------+ + | :attr:`doc` | const char \* | points to the contents of the | + | | | docstring | + +------------------+---------------+-------------------------------+ + + :attr:`!type` can be one of many ``T_`` macros corresponding to various C + types. When the member is accessed in Python, it will be converted to the + equivalent Python type. + + =============== ================== + Macro name C type + =============== ================== + T_SHORT short + T_INT int + T_LONG long + T_FLOAT float + T_DOUBLE double + T_STRING const char \* + T_OBJECT PyObject \* + T_OBJECT_EX PyObject \* + T_CHAR char + T_BYTE char + T_UBYTE unsigned char + T_UINT unsigned int + T_USHORT unsigned short + T_ULONG unsigned long + T_BOOL char + T_LONGLONG long long + T_ULONGLONG unsigned long long + T_PYSSIZET Py_ssize_t + =============== ================== + + :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that + :c:macro:`T_OBJECT` returns ``None`` if the member is ``NULL`` and + :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use + :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` + handles use of the :keyword:`del` statement on that attribute more correctly + than :c:macro:`T_OBJECT`. + + :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for + read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies + :c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8. + Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` + members can be deleted. (They are set to ``NULL``). + + .. _pymemberdef-offsets: + + Heap allocated types (created using :c:func:`PyType_FromSpec` or similar), + ``PyMemberDef`` may contain definitions for the special members + ``__dictoffset__`` and ``__weaklistoffset__``, corresponding to + :c:member:`~PyTypeObject.tp_dictoffset` and + :c:member:`~PyTypeObject.tp_weaklistoffset` in type objects. + These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example:: + + static PyMemberDef spam_type_members[] = { + {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY}, + {NULL} /* Sentinel */ + }; + +.. c:type:: PyGetSetDef + + Structure to define property-like access for a type. See also description of + the :c:member:`PyTypeObject.tp_getset` slot. + + +-------------+------------------+-----------------------------------+ + | Field | C Type | Meaning | + +=============+==================+===================================+ + | name | const char \* | attribute name | + +-------------+------------------+-----------------------------------+ + | get | getter | C Function to get the attribute | + +-------------+------------------+-----------------------------------+ + | set | setter | optional C function to set or | + | | | delete the attribute, if omitted | + | | | the attribute is readonly | + +-------------+------------------+-----------------------------------+ + | doc | const char \* | optional docstring | + +-------------+------------------+-----------------------------------+ + | closure | void \* | optional function pointer, | + | | | providing additional data for | + | | | getter and setter | + +-------------+------------------+-----------------------------------+ + + The ``get`` function takes one :c:type:`PyObject\*` parameter (the + instance) and a function pointer (the associated ``closure``):: + + typedef PyObject *(*getter)(PyObject *, void *); + + It should return a new reference on success or ``NULL`` with a set exception + on failure. + + ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and + the value to be set) and a function pointer (the associated ``closure``):: + + typedef int (*setter)(PyObject *, PyObject *, void *); + + In case the attribute should be deleted the second parameter is ``NULL``. + Should return ``0`` on success or ``-1`` with a set exception on failure. diff --git a/Doc/c-api/type.rst.bak b/Doc/c-api/type.rst.bak new file mode 100644 index 00000000000000..41956b7dca5032 --- /dev/null +++ b/Doc/c-api/type.rst.bak @@ -0,0 +1,209 @@ +.. highlight:: c + +.. _typeobjects: + +Type Objects +------------ + +.. index:: object: type + + +.. c:type:: PyTypeObject + + The C structure of the objects used to describe built-in types. + + +.. c:var:: PyObject* PyType_Type + + This is the type object for type objects; it is the same object as + :class:`type` in the Python layer. + + +.. c:function:: int PyType_Check(PyObject *o) + + Return true if the object *o* is a type object, including instances of types + derived from the standard type object. Return false in all other cases. + + +.. c:function:: int PyType_CheckExact(PyObject *o) + + Return true if the object *o* is a type object, but not a subtype of the + standard type object. Return false in all other cases. + + +.. c:function:: unsigned int PyType_ClearCache() + + Clear the internal lookup cache. Return the current version tag. + +.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type) + + Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily + meant for use with `Py_LIMITED_API`; the individual flag bits are + guaranteed to be stable across Python releases, but access to + :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. + + .. versionadded:: 3.2 + + .. versionchanged:: 3.4 + The return type is now ``unsigned long`` rather than ``long``. + + +.. c:function:: void PyType_Modified(PyTypeObject *type) + + Invalidate the internal lookup cache for the type and all of its + subtypes. This function must be called after any manual + modification of the attributes or base classes of the type. + + +.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature) + + Return true if the type object *o* sets the feature *feature*. Type features + are denoted by single bit flags. + + +.. c:function:: int PyType_IS_GC(PyTypeObject *o) + + Return true if the type object includes support for the cycle detector; this + tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. + + +.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) + + Return true if *a* is a subtype of *b*. + + This function only checks for actual subtypes, which means that + :meth:`~class.__subclasscheck__` is not called on *b*. Call + :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass` + would do. + + +.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use + Python's default memory allocation mechanism to allocate a new instance and + initialize all its contents to ``NULL``. + +.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) + + Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a + new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot. + +.. c:function:: int PyType_Ready(PyTypeObject *type) + + Finalize a type object. This should be called on all type objects to finish + their initialization. This function is responsible for adding inherited slots + from a type's base class. Return ``0`` on success, or return ``-1`` and sets an + exception on error. + +.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot) + + Return the function pointer stored in the given slot. If the + result is ``NULL``, this indicates that either the slot is ``NULL``, + or that the function was called with invalid parameters. + Callers will typically cast the result pointer into the appropriate + function type. + + See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument. + + An exception is raised if *type* is not a heap type. + + .. versionadded:: 3.4 + + +Creating Heap-Allocated Types +............................. + +The following functions and structs are used to create +:ref:`heap types `. + +.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases) + + Creates and returns a heap type object from the *spec* + (:const:`Py_TPFLAGS_HEAPTYPE`). + + If *bases* is a tuple, the created heap type contains all types contained + in it as base types. + + If *bases* is ``NULL``, the *Py_tp_base* slot is used instead. + If that also is ``NULL``, the new type derives from :class:`object`. + + This function calls :c:func:`PyType_Ready` on the new type. + + .. versionadded:: 3.3 + +.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec) + + Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``. + +.. c:type:: PyType_Spec + + Structure defining a type's behavior. + + .. c:member:: const char* PyType_Spec.name + + Name of the type, used to set :c:member:`PyTypeObject.tp_name`. + + .. c:member:: int PyType_Spec.basicsize + .. c:member:: int PyType_Spec.itemsize + + Size of the instance in bytes, used to set + :c:member:`PyTypeObject.tp_basicsize` and + :c:member:`PyTypeObject.tp_itemsize`. + + .. c:member:: int PyType_Spec.flags + + Type flags, used to set :c:member:`PyTypeObject.tp_flags`. + + If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, + :c:func:`PyType_FromSpecWithBases` sets it automatically. + + .. c:member:: PyType_Slot *PyType_Spec.slots + + Array of :c:type:`PyType_Slot` structures. + Terminated by the special slot value ``{0, NULL}``. + +.. c:type:: PyType_Slot + + Structure defining optional functionality of a type, containing a slot ID + and a value pointer. + + .. c:member:: int PyType_Slot.slot + + A slot ID. + + Slot IDs are named like the field names of the structures + :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`, + :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and + :c:type:`PyAsyncMethods` with an added ``Py_`` prefix. + For example, use: + + * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc` + * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add` + * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length` + + The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`: + + * :c:member:`~PyTypeObject.tp_dict` + * :c:member:`~PyTypeObject.tp_mro` + * :c:member:`~PyTypeObject.tp_cache` + * :c:member:`~PyTypeObject.tp_subclasses` + * :c:member:`~PyTypeObject.tp_weaklist` + * :c:member:`~PyTypeObject.tp_vectorcall` + * :c:member:`~PyTypeObject.tp_weaklistoffset` + (see :ref:`PyMemberDef `) + * :c:member:`~PyTypeObject.tp_dictoffset` + (see :ref:`PyMemberDef `) + * :c:member:`~PyTypeObject.tp_vectorcall_offset` + * :c:member:`~PyBufferProcs.bf_getbuffer` + * :c:member:`~PyBufferProcs.bf_releasebuffer` + + Setting :c:data:`Py_tp_bases` may be problematic on some platforms. + To avoid issues, use the *bases* argument of + :py:func:`PyType_FromSpecWithBases` instead. + + .. c:member:: void *PyType_Slot.pfunc + + The desired value of the slot. In most cases, this is a pointer + to a function. + + May not be ``NULL``. diff --git a/Doc/c-api/typeobj.rst.bak b/Doc/c-api/typeobj.rst.bak new file mode 100644 index 00000000000000..a8a779ef6165a8 --- /dev/null +++ b/Doc/c-api/typeobj.rst.bak @@ -0,0 +1,2565 @@ +.. highlight:: c + +.. _type-structs: + +Type Objects +============ + +Perhaps one of the most important structures of the Python object system is the +structure that defines a new type: the :c:type:`PyTypeObject` structure. Type +objects can be handled using any of the :c:func:`PyObject_\*` or +:c:func:`PyType_\*` functions, but do not offer much that's interesting to most +Python applications. These objects are fundamental to how objects behave, so +they are very important to the interpreter itself and to any extension module +that implements new types. + +Type objects are fairly large compared to most of the standard types. The reason +for the size is that each type object stores a large number of values, mostly C +function pointers, each of which implements a small part of the type's +functionality. The fields of the type object are examined in detail in this +section. The fields will be described in the order in which they occur in the +structure. + +In addition to the following quick reference, the :ref:`typedef-examples` +section provides at-a-glance insight into the meaning and use of +:c:type:`PyTypeObject`. + + +Quick Reference +--------------- + +.. _tp-slots-table: + +"tp slots" +^^^^^^^^^^ + +.. table:: + :widths: 18,18,18,1,1,1,1 + + +------------------------------------------------+-----------------------------------+-------------------+---------------+ + | PyTypeObject Slot [#slots]_ | :ref:`Type ` | special | Info [#cols]_ | + | | | methods/attrs +---+---+---+---+ + | | | | O | T | D | I | + +================================================+===================================+===================+===+===+===+===+ + | :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | + | | | __getattr__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | __setattr__, | | | | G | + | | | __delattr__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | :ref:`sub-slots` | | | | % | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | __repr__ | X | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | :ref:`sub-slots` | | | | % | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | :ref:`sub-slots` | | | | % | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | :ref:`sub-slots` | | | | % | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | __hash__ | X | | | G | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | __call__ | | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | __str__ | X | | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | __getattribute__, | X | X | | G | + | | | __getattr__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | __setattr__, | X | X | | G | + | | | __delattr__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | | % | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_flags` | unsigned long | | X | X | | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_doc` | const char * | __doc__ | X | X | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | | X | | G | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | | X | | G | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | __lt__, | X | | | G | + | | | __le__, | | | | | + | | | __eq__, | | | | | + | | | __ne__, | | | | | + | | | __gt__, | | | | | + | | | __ge__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | __next__ | | | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | | X | X | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | | X | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | | X | X | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | __base__ | | | X | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | __dict__ | | | ? | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | __get__ | | | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | + | | | __delete__ | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | | X | | ? | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | __new__ | X | X | ? | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | | X | X | ? | ? | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | | X | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | __bases__ | | | ~ | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | __mro__ | | | ~ | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | __subclasses__ | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | __del__ | | | | X | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + | :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | | + +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ + +.. [#slots] + A slot name in parentheses indicates it is (effectively) deprecated. + Names in angle brackets should be treated as read-only. + Names in square brackets are for internal use only. + "" (as a prefix) means the field is required (must be non-``NULL``). +.. [#cols] Columns: + + **"O"**: set on :c:type:`PyBaseObject_Type` + + **"T"**: set on :c:type:`PyType_Type` + + **"D"**: default (if slot is set to ``NULL``) + + .. code-block:: none + + X - PyType_Ready sets this value if it is NULL + ~ - PyType_Ready always sets this value (it should be NULL) + ? - PyType_Ready may set this value depending on other slots + + Also see the inheritance column ("I"). + + **"I"**: inheritance + + .. code-block:: none + + X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value + % - the slots of the sub-struct are inherited individually + G - inherited, but only in combination with other slots; see the slot's description + ? - it's complicated; see the slot's description + + Note that some slots are effectively inherited through the normal + attribute lookup chain. + +.. _sub-slots: + +sub-slots +^^^^^^^^^ + +.. table:: + :widths: 26,17,12 + + +---------------------------------------------------------+-----------------------------------+--------------+ + | Slot | :ref:`Type ` | special | + | | | methods | + +=========================================================+===================================+==============+ + | :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyAsyncMethods.am_anext` | :c:type:`unaryfunc` | __anext__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_add` | :c:type:`binaryfunc` | __add__ | + | | | __radd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ | + | | | __rsub__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __sub__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ | + | | | __rmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __mul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ | + | | | __rmod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __mod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ | + | | | __rdivmod__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ | + | | | __rpow__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __pow__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ | + | | | __rlshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __lshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ | + | | | __rrshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __rshift__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ | + | | | __rand__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __and__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ | + | | | __rxor__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __xor__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ | + | | | __ror__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __or__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_reserved` | void * | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __truediv__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_index` | :c:type:`unaryfunc` | __index__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | + | | | __rmatmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, | + | | | __delitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ | + | | | __delitem__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ | + +---------------------------------------------------------+-----------------------------------+--------------+ + | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | | + +---------------------------------------------------------+-----------------------------------+--------------+ + | :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | | + +---------------------------------------------------------+-----------------------------------+--------------+ + +.. _slot-typedefs-table: + +slot typedefs +^^^^^^^^^^^^^ + ++-----------------------------+-----------------------------+----------------------+ +| typedef | Parameter Types | Return Type | ++=============================+=============================+======================+ +| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyTypeObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`destructor` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`freefunc` | void * | void | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`traverseproc` | .. line-block:: | int | +| | | | +| | void * | | +| | :c:type:`visitproc` | | +| | void * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`initproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`setattrfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | const char * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getattrofunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`setattrofunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`descrsetfunc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`getbufferproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`Py_buffer` * | | +| | int | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`releasebufferproc` | .. line-block:: | void | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`Py_buffer` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`inquiry` | void * | int | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`ssizeobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | Py_ssize_t | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ +| :c:type:`objobjargproc` | .. line-block:: | int | +| | | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | +| | :c:type:`PyObject` * | | ++-----------------------------+-----------------------------+----------------------+ + +See :ref:`slot-typedefs` below for more detail. + + +PyTypeObject Definition +----------------------- + +The structure definition for :c:type:`PyTypeObject` can be found in +:file:`Include/object.h`. For convenience of reference, this repeats the +definition found there: + +.. XXX Drop this? + +.. literalinclude:: ../includes/typestruct.h + + +PyObject Slots +-------------- + +The type object structure extends the :c:type:`PyVarObject` structure. The +:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, +usually called from a class statement). Note that :c:data:`PyType_Type` (the +metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e. +type objects) *must* have the :attr:`ob_size` field. + + +.. c:member:: PyObject* PyObject._ob_next + PyObject* PyObject._ob_prev + + These fields are only present when the macro ``Py_TRACE_REFS`` is defined. + Their initialization to ``NULL`` is taken care of by the ``PyObject_HEAD_INIT`` + macro. For statically allocated objects, these fields always remain ``NULL``. + For dynamically allocated objects, these two fields are used to link the object + into a doubly-linked list of *all* live objects on the heap. This could be used + for various debugging purposes; currently the only use is to print the objects + that are still alive at the end of a run when the environment variable + :envvar:`PYTHONDUMPREFS` is set. + + **Inheritance:** + + These fields are not inherited by subtypes. + + +.. c:member:: Py_ssize_t PyObject.ob_refcnt + + This is the type object's reference count, initialized to ``1`` by the + ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, + the type's instances (objects whose :attr:`ob_type` points back to the type) do + *not* count as references. But for dynamically allocated type objects, the + instances *do* count as references. + + **Inheritance:** + + This field is not inherited by subtypes. + + +.. c:member:: PyTypeObject* PyObject.ob_type + + This is the type's type, in other words its metatype. It is initialized by the + argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be + ``&PyType_Type``. However, for dynamically loadable extension modules that must + be usable on Windows (at least), the compiler complains that this is not a valid + initializer. Therefore, the convention is to pass ``NULL`` to the + ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the + start of the module's initialization function, before doing anything else. This + is typically done like this:: + + Foo_Type.ob_type = &PyType_Type; + + This should be done before any instances of the type are created. + :c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so, + initializes it to the :attr:`ob_type` field of the base class. + :c:func:`PyType_Ready` will not change this field if it is non-zero. + + **Inheritance:** + + This field is inherited by subtypes. + + +PyVarObject Slots +----------------- + +.. c:member:: Py_ssize_t PyVarObject.ob_size + + For statically allocated type objects, this should be initialized to zero. For + dynamically allocated type objects, this field has a special internal meaning. + + **Inheritance:** + + This field is not inherited by subtypes. + + +PyTypeObject Slots +------------------ + +Each slot has a section describing inheritance. If :c:func:`PyType_Ready` +may set a value when the field is set to ``NULL`` then there will also be +a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type` +and :c:type:`PyType_Type` effectively act as defaults.) + +.. c:member:: const char* PyTypeObject.tp_name + + Pointer to a NUL-terminated string containing the name of the type. For types + that are accessible as module globals, the string should be the full module + name, followed by a dot, followed by the type name; for built-in types, it + should be just the type name. If the module is a submodule of a package, the + full package name is part of the full module name. For example, a type named + :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P` + should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``. + + For dynamically allocated type objects, this should just be the type name, and + the module name explicitly stored in the type dict as the value for key + ``'__module__'``. + + For statically allocated type objects, the tp_name field should contain a dot. + Everything before the last dot is made accessible as the :attr:`__module__` + attribute, and everything after the last dot is made accessible as the + :attr:`~definition.__name__` attribute. + + If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the + :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined + (unless explicitly set in the dictionary, as explained above). This means your + type will be impossible to pickle. Additionally, it will not be listed in + module documentations created with pydoc. + + This field must not be ``NULL``. It is the only required field + in :c:func:`PyTypeObject` (other than potentially + :c:member:`~PyTypeObject.tp_itemsize`). + + **Inheritance:** + + This field is not inherited by subtypes. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize + Py_ssize_t PyTypeObject.tp_itemsize + + These fields allow calculating the size in bytes of instances of the type. + + There are two kinds of types: types with fixed-length instances have a zero + :c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero + :c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all + instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`. + + For a type with variable-length instances, the instances must have an + :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N + times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of + N is typically stored in the instance's :attr:`ob_size` field. There are + exceptions: for example, ints use a negative :attr:`ob_size` to indicate a + negative number, and N is ``abs(ob_size)`` there. Also, the presence of an + :attr:`ob_size` field in the instance layout doesn't mean that the instance + structure is variable-length (for example, the structure for the list type has + fixed-length instances, yet those instances have a meaningful :attr:`ob_size` + field). + + The basic size includes the fields in the instance declared by the macro + :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to + declare the instance struct) and this in turn includes the :attr:`_ob_prev` and + :attr:`_ob_next` fields if they are present. This means that the only correct + way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the + ``sizeof`` operator on the struct used to declare the instance layout. + The basic size does not include the GC header size. + + A note about alignment: if the variable items require a particular alignment, + this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example: + suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is + ``sizeof(double)``. It is the programmer's responsibility that + :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the + alignment requirement for ``double``). + + For any type with variable-length instances, this field must not be ``NULL``. + + **Inheritance:** + + These fields are inherited separately by subtypes. If the base type has a + non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set + :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this + depends on the implementation of the base type). + + +.. c:member:: destructor PyTypeObject.tp_dealloc + + A pointer to the instance destructor function. This function must be defined + unless the type guarantees that its instances will never be deallocated (as is + the case for the singletons ``None`` and ``Ellipsis``). The function signature is:: + + void tp_dealloc(PyObject *self); + + The destructor function is called by the :c:func:`Py_DECREF` and + :c:func:`Py_XDECREF` macros when the new reference count is zero. At this point, + the instance is still in existence, but there are no references to it. The + destructor function should free all references which the instance owns, free all + memory buffers owned by the instance (using the freeing function corresponding + to the allocation function used to allocate the buffer), and call the type's + :c:member:`~PyTypeObject.tp_free` function. If the type is not subtypable + (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is + permissible to call the object deallocator directly instead of via + :c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the + instance; this is normally :c:func:`PyObject_Del` if the instance was allocated + using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or + :c:func:`PyObject_GC_Del` if the instance was allocated using + :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. + + Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the + deallocator should decrement the reference count for its type object after + calling the type deallocator. In order to avoid dangling pointers, the + recommended way to achieve this is: + + .. code-block:: c + + static void foo_dealloc(foo_object *self) { + PyTypeObject *tp = Py_TYPE(self); + // free references and buffers here + tp->tp_free(self); + Py_DECREF(tp); + } + + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_vectorcall_offset + + An optional offset to a per-instance function that implements calling + the object using the :ref:`vectorcall protocol `, + a more efficient alternative + of the simpler :c:member:`~PyTypeObject.tp_call`. + + This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL` + is set. If so, this must be a positive integer containing the offset in the + instance of a :c:type:`vectorcallfunc` pointer. + + The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves + as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance + falls back to :c:member:`~PyTypeObject.tp_call`. + + Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set + :c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent + with the *vectorcallfunc* function. + This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`. + + .. warning:: + + It is not recommended for :ref:`heap types ` to implement + the vectorcall protocol. + When a user sets :attr:`__call__` in Python code, only *tp_call* is updated, + likely making it inconsistent with the vectorcall function. + + .. note:: + + The semantics of the ``tp_vectorcall_offset`` slot are provisional and + expected to be finalized in Python 3.9. + If you use vectorcall, plan for updating your code for Python 3.9. + + .. versionchanged:: 3.8 + + Before version 3.8, this slot was named ``tp_print``. + In Python 2.x, it was used for printing to a file. + In Python 3.0 to 3.7, it was unused. + + **Inheritance:** + + This field is always inherited. + However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not + always inherited. If it's not, then the subclass won't use + :ref:`vectorcall `, except when + :c:func:`PyVectorcall_Call` is explicitly called. + This is in particular the case for `heap types`_ + (including subclasses defined in Python). + + +.. c:member:: getattrfunc PyTypeObject.tp_getattr + + An optional pointer to the get-attribute-string function. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string + instead of a Python string object to give the attribute name. + + **Inheritance:** + + Group: :attr:`tp_getattr`, :attr:`tp_getattro` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype + inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when + the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``. + + +.. c:member:: setattrfunc PyTypeObject.tp_setattr + + An optional pointer to the function for setting and deleting attributes. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string + instead of a Python string object to give the attribute name. + + **Inheritance:** + + Group: :attr:`tp_setattr`, :attr:`tp_setattro` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype + inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when + the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``. + + +.. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async + + Pointer to an additional structure that contains fields relevant only to + objects which implement :term:`awaitable` and :term:`asynchronous iterator` + protocols at the C-level. See :ref:`async-structs` for details. + + .. versionadded:: 3.5 + Formerly known as ``tp_compare`` and ``tp_reserved``. + + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, + but the contained fields are inherited individually. + + +.. c:member:: reprfunc PyTypeObject.tp_repr + + .. index:: builtin: repr + + An optional pointer to a function that implements the built-in function + :func:`repr`. + + The signature is the same as for :c:func:`PyObject_Repr`:: + + PyObject *tp_repr(PyObject *self); + + The function must return a string or a Unicode object. Ideally, + this function should return a string that, when passed to + :func:`eval`, given a suitable environment, returns an object with the + same value. If this is not feasible, it should return a string starting with + ``'<'`` and ending with ``'>'`` from which both the type and the value of the + object can be deduced. + + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + When this field is not set, a string of the form ``<%s object at %p>`` is + returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's + memory address. + + +.. c:member:: PyNumberMethods* PyTypeObject.tp_as_number + + Pointer to an additional structure that contains fields relevant only to + objects which implement the number protocol. These fields are documented in + :ref:`number-structs`. + + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are + inherited individually. + + +.. c:member:: PySequenceMethods* PyTypeObject.tp_as_sequence + + Pointer to an additional structure that contains fields relevant only to + objects which implement the sequence protocol. These fields are documented + in :ref:`sequence-structs`. + + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields + are inherited individually. + + +.. c:member:: PyMappingMethods* PyTypeObject.tp_as_mapping + + Pointer to an additional structure that contains fields relevant only to + objects which implement the mapping protocol. These fields are documented in + :ref:`mapping-structs`. + + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields + are inherited individually. + + +.. c:member:: hashfunc PyTypeObject.tp_hash + + .. index:: builtin: hash + + An optional pointer to a function that implements the built-in function + :func:`hash`. + + The signature is the same as for :c:func:`PyObject_Hash`:: + + Py_hash_t tp_hash(PyObject *); + + The value ``-1`` should not be returned as a + normal return value; when an error occurs during the computation of the hash + value, the function should set an exception and return ``-1``. + + When this field is not set (*and* :attr:`tp_richcompare` is not set), + an attempt to take the hash of the object raises :exc:`TypeError`. + This is the same as setting it to :c:func:`PyObject_HashNotImplemented`. + + This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to + block inheritance of the hash method from a parent type. This is interpreted + as the equivalent of ``__hash__ = None`` at the Python level, causing + ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note + that the converse is also true - setting ``__hash__ = None`` on a class at + the Python level will result in the ``tp_hash`` slot being set to + :c:func:`PyObject_HashNotImplemented`. + + **Inheritance:** + + Group: :attr:`tp_hash`, :attr:`tp_richcompare` + + This field is inherited by subtypes together with + :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of + :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's + :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both ``NULL``. + + +.. c:member:: ternaryfunc PyTypeObject.tp_call + + An optional pointer to a function that implements calling the object. This + should be ``NULL`` if the object is not callable. The signature is the same as + for :c:func:`PyObject_Call`:: + + PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs); + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: reprfunc PyTypeObject.tp_str + + An optional pointer to a function that implements the built-in operation + :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the + constructor for that type. This constructor calls :c:func:`PyObject_Str` to do + the actual work, and :c:func:`PyObject_Str` will call this handler.) + + The signature is the same as for :c:func:`PyObject_Str`:: + + PyObject *tp_str(PyObject *self); + + The function must return a string or a Unicode object. It should be a "friendly" string + representation of the object, as this is the representation that will be used, + among other things, by the :func:`print` function. + + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + When this field is not set, :c:func:`PyObject_Repr` is called to return a string + representation. + + +.. c:member:: getattrofunc PyTypeObject.tp_getattro + + An optional pointer to the get-attribute function. + + The signature is the same as for :c:func:`PyObject_GetAttr`:: + + PyObject *tp_getattro(PyObject *self, PyObject *attr); + + It is usually convenient to set this field to :c:func:`PyObject_GenericGetAttr`, + which implements the normal way of looking for object attributes. + + **Inheritance:** + + Group: :attr:`tp_getattr`, :attr:`tp_getattro` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype + inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when + the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``. + + **Default:** + + :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`. + + +.. c:member:: setattrofunc PyTypeObject.tp_setattro + + An optional pointer to the function for setting and deleting attributes. + + The signature is the same as for :c:func:`PyObject_SetAttr`:: + + int tp_setattro(PyObject *self, PyObject *attr, PyObject *value); + + In addition, setting *value* to ``NULL`` to delete an attribute must be + supported. It is usually convenient to set this field to + :c:func:`PyObject_GenericSetAttr`, which implements the normal + way of setting object attributes. + + **Inheritance:** + + Group: :attr:`tp_setattr`, :attr:`tp_setattro` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype + inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when + the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``. + + **Default:** + + :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`. + + +.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer + + Pointer to an additional structure that contains fields relevant only to objects + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. + + **Inheritance:** + + The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, + but the contained fields are inherited individually. + + +.. c:member:: unsigned long PyTypeObject.tp_flags + + This field is a bit mask of various flags. Some flags indicate variant + semantics for certain situations; others are used to indicate that certain + fields in the type object (or in the extension structures referenced via + :c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and + :c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if + such a flag bit is clear, the type fields it guards must not be accessed and + must be considered to have a zero or ``NULL`` value instead. + + **Inheritance:** + + Inheritance of this field is complicated. Most flag bits are inherited + individually, i.e. if the base type has a flag bit set, the subtype inherits + this flag bit. The flag bits that pertain to extension structures are strictly + inherited if the extension structure is inherited, i.e. the base type's value of + the flag bit is copied into the subtype together with a pointer to the extension + structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with + the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the + :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the + :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have + ``NULL`` values. + + .. XXX are most flag bits *really* inherited individually? + + **Default:** + + :c:type:`PyBaseObject_Type` uses + ``Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE``. + + **Bit Masks:** + + The following bit masks are currently defined; these can be ORed together using + the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro + :c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and + checks whether ``tp->tp_flags & f`` is non-zero. + + .. data:: Py_TPFLAGS_HEAPTYPE + + This bit is set when the type object itself is allocated on the heap, for + example, types created dynamically using :c:func:`PyType_FromSpec`. In this + case, the :attr:`ob_type` field of its instances is considered a reference to + the type, and the type object is INCREF'ed when a new instance is created, and + DECREF'ed when an instance is destroyed (this does not apply to instances of + subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or + DECREF'ed). + + **Inheritance:** + + ??? + + + .. data:: Py_TPFLAGS_BASETYPE + + This bit is set when the type can be used as the base type of another type. If + this bit is clear, the type cannot be subtyped (similar to a "final" class in + Java). + + **Inheritance:** + + ??? + + + .. data:: Py_TPFLAGS_READY + + This bit is set when the type object has been fully initialized by + :c:func:`PyType_Ready`. + + **Inheritance:** + + ??? + + + .. data:: Py_TPFLAGS_READYING + + This bit is set while :c:func:`PyType_Ready` is in the process of initializing + the type object. + + **Inheritance:** + + ??? + + + .. data:: Py_TPFLAGS_HAVE_GC + + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :c:func:`PyObject_GC_New` and + destroyed using :c:func:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in + the type object. + + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + + The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited + together with the :attr:`tp_traverse` and :attr:`tp_clear` + fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is + clear in the subtype and the :attr:`tp_traverse` and + :attr:`tp_clear` fields in the subtype exist and have ``NULL`` + values. + + + .. data:: Py_TPFLAGS_DEFAULT + + This is a bitmask of all the bits that pertain to the existence of certain + fields in the type object and its extension structures. Currently, it includes + the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, + :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. + + **Inheritance:** + + ??? + + + .. data:: Py_TPFLAGS_METHOD_DESCRIPTOR + + This bit indicates that objects behave like unbound methods. + + If this flag is set for ``type(meth)``, then: + + - ``meth.__get__(obj, cls)(*args, **kwds)`` (with ``obj`` not None) + must be equivalent to ``meth(obj, *args, **kwds)``. + + - ``meth.__get__(None, cls)(*args, **kwds)`` + must be equivalent to ``meth(*args, **kwds)``. + + This flag enables an optimization for typical method calls like + ``obj.meth()``: it avoids creating a temporary "bound method" object for + ``obj.meth``. + + .. versionadded:: 3.8 + + **Inheritance:** + + This flag is never inherited by heap types. + For extension types, it is inherited whenever + :c:member:`~PyTypeObject.tp_descr_get` is inherited. + + + .. XXX Document more flags here? + + + .. data:: Py_TPFLAGS_LONG_SUBCLASS + .. data:: Py_TPFLAGS_LIST_SUBCLASS + .. data:: Py_TPFLAGS_TUPLE_SUBCLASS + .. data:: Py_TPFLAGS_BYTES_SUBCLASS + .. data:: Py_TPFLAGS_UNICODE_SUBCLASS + .. data:: Py_TPFLAGS_DICT_SUBCLASS + .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS + .. data:: Py_TPFLAGS_TYPE_SUBCLASS + + These flags are used by functions such as + :c:func:`PyLong_Check` to quickly determine if a type is a subclass + of a built-in type; such specific checks are faster than a generic + check, like :c:func:`PyObject_IsInstance`. Custom types that inherit + from built-ins should have their :c:member:`~PyTypeObject.tp_flags` + set appropriately, or the code that interacts with such types + will behave differently depending on what kind of check is used. + + + .. data:: Py_TPFLAGS_HAVE_FINALIZE + + This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the + type structure. + + .. versionadded:: 3.4 + + .. deprecated:: 3.8 + This flag isn't necessary anymore, as the interpreter assumes the + :c:member:`~PyTypeObject.tp_finalize` slot is always present in the + type structure. + + + .. data:: _Py_TPFLAGS_HAVE_VECTORCALL + + This bit is set when the class implements + the :ref:`vectorcall protocol `. + See :c:member:`~PyTypeObject.tp_vectorcall_offset` for details. + + **Inheritance:** + + This bit is inherited for *static* subtypes if + :c:member:`~PyTypeObject.tp_call` is also inherited. + `Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``. + + .. note:: + + This flag is provisional and expected to become public in Python 3.9, + with a different name and, possibly, changed semantics. + If you use vectorcall, plan for updating your code for Python 3.9. + + .. versionadded:: 3.8 + + +.. c:member:: const char* PyTypeObject.tp_doc + + An optional pointer to a NUL-terminated C string giving the docstring for this + type object. This is exposed as the :attr:`__doc__` attribute on the type and + instances of the type. + + **Inheritance:** + + This field is *not* inherited by subtypes. + + +.. c:member:: traverseproc PyTypeObject.tp_traverse + + An optional pointer to a traversal function for the garbage collector. This is + only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: + + int tp_traverse(PyObject *self, visitproc visit, void *arg); + + More information about Python's garbage collection scheme can be found + in section :ref:`supporting-cycle-detection`. + + The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect + reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function + simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python + objects. For example, this is function :c:func:`local_traverse` from the + :mod:`_thread` extension module:: + + static int + local_traverse(localobject *self, visitproc visit, void *arg) + { + Py_VISIT(self->args); + Py_VISIT(self->kw); + Py_VISIT(self->dict); + return 0; + } + + Note that :c:func:`Py_VISIT` is called only on those members that can participate + in reference cycles. Although there is also a ``self->key`` member, it can only + be ``NULL`` or a Python string and therefore cannot be part of a reference cycle. + + On the other hand, even if you know a member can never be part of a cycle, as a + debugging aid you may want to visit it anyway just so the :mod:`gc` module's + :func:`~gc.get_referents` function will include it. + + Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to + :c:func:`local_traverse` to have these specific names; don't name them just + anything. + + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and + :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in + the subtype. + + +.. c:member:: inquiry PyTypeObject.tp_clear + + An optional pointer to a clear function for the garbage collector. This is only + used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: + + int tp_clear(PyObject *); + + The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic + garbage detected by the garbage collector. Taken together, all :c:member:`~PyTypeObject.tp_clear` + functions in the system must combine to break all reference cycles. This is + subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, + the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` function, because it's + possible to prove that no reference cycle can be composed entirely of tuples. + Therefore the :c:member:`~PyTypeObject.tp_clear` functions of other types must be sufficient to + break any cycle containing a tuple. This isn't immediately obvious, and there's + rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`. + + Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to + those of its members that may be Python objects, and set its pointers to those + members to ``NULL``, as in the following example:: + + static int + local_clear(localobject *self) + { + Py_CLEAR(self->key); + Py_CLEAR(self->args); + Py_CLEAR(self->kw); + Py_CLEAR(self->dict); + return 0; + } + + The :c:func:`Py_CLEAR` macro should be used, because clearing references is + delicate: the reference to the contained object must not be decremented until + after the pointer to the contained object is set to ``NULL``. This is because + decrementing the reference count may cause the contained object to become trash, + triggering a chain of reclamation activity that may include invoking arbitrary + Python code (due to finalizers, or weakref callbacks, associated with the + contained object). If it's possible for such code to reference *self* again, + it's important that the pointer to the contained object be ``NULL`` at that time, + so that *self* knows the contained object can no longer be used. The + :c:func:`Py_CLEAR` macro performs the operations in a safe order. + + Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles, + it's not necessary to clear contained objects like Python strings or Python + integers, which can't participate in reference cycles. On the other hand, it may + be convenient to clear all contained Python objects, and write the type's + :c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:`~PyTypeObject.tp_clear`. + + More information about Python's garbage collection scheme can be found in + section :ref:`supporting-cycle-detection`. + + **Inheritance:** + + Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and + :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in + the subtype. + + +.. c:member:: richcmpfunc PyTypeObject.tp_richcompare + + An optional pointer to the rich comparison function, whose signature is:: + + PyObject *tp_richcompare(PyObject *self, PyObject *other, int op); + + The first parameter is guaranteed to be an instance of the type + that is defined by :c:type:`PyTypeObject`. + + The function should return the result of the comparison (usually ``Py_True`` + or ``Py_False``). If the comparison is undefined, it must return + ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and + set an exception condition. + + The following constants are defined to be used as the third argument for + :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: + + +----------------+------------+ + | Constant | Comparison | + +================+============+ + | :const:`Py_LT` | ``<`` | + +----------------+------------+ + | :const:`Py_LE` | ``<=`` | + +----------------+------------+ + | :const:`Py_EQ` | ``==`` | + +----------------+------------+ + | :const:`Py_NE` | ``!=`` | + +----------------+------------+ + | :const:`Py_GT` | ``>`` | + +----------------+------------+ + | :const:`Py_GE` | ``>=`` | + +----------------+------------+ + + The following macro is defined to ease writing rich comparison functions: + + .. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) + + Return ``Py_True`` or ``Py_False`` from the function, depending on the + result of a comparison. + VAL_A and VAL_B must be orderable by C comparison operators (for example, + they may be C ints or floats). The third argument specifies the requested + operation, as for :c:func:`PyObject_RichCompare`. + + The return value's reference count is properly incremented. + + On error, sets an exception and returns ``NULL`` from the function. + + .. versionadded:: 3.7 + + **Inheritance:** + + Group: :attr:`tp_hash`, :attr:`tp_richcompare` + + This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`: + a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when + the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both + ``NULL``. + + **Default:** + + :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare` + implementation, which may be inherited. However, if only + :attr:`tp_hash` is defined, not even the inherited function is used + and instances of the type will not be able to participate in any + comparisons. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset + + If the instances of this type are weakly referenceable, this field is greater + than zero and contains the offset in the instance structure of the weak + reference list head (ignoring the GC header, if present); this offset is used by + :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The + instance structure needs to include a field of type :c:type:`PyObject\*` which is + initialized to ``NULL``. + + Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for + weak references to the type object itself. + + **Inheritance:** + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype uses a different weak + reference list head than the base type. Since the list head is always found via + :c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`~object.__slots__` declaration, + and none of its base types are weakly referenceable, the type is made weakly + referenceable by adding a weak reference list head slot to the instance layout + and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset. + + When a type's :attr:`__slots__` declaration contains a slot named + :attr:`__weakref__`, that slot becomes the weak reference list head for + instances of the type, and the slot's offset is stored in the type's + :c:member:`~PyTypeObject.tp_weaklistoffset`. + + When a type's :attr:`__slots__` declaration does not contain a slot named + :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its + base type. + + +.. c:member:: getiterfunc PyTypeObject.tp_iter + + An optional pointer to a function that returns an iterator for the object. Its + presence normally signals that the instances of this type are iterable (although + sequences may be iterable without this function). + + This function has the same signature as :c:func:`PyObject_GetIter`:: + + PyObject *tp_iter(PyObject *self); + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: iternextfunc PyTypeObject.tp_iternext + + An optional pointer to a function that returns the next item in an iterator. + The signature is:: + + PyObject *tp_iternext(PyObject *self); + + When the iterator is exhausted, it must return ``NULL``; a :exc:`StopIteration` + exception may or may not be set. When another error occurs, it must return + ``NULL`` too. Its presence signals that the instances of this type are + iterators. + + Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that + function should return the iterator instance itself (not a new iterator + instance). + + This function has the same signature as :c:func:`PyIter_Next`. + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods + + An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMethodDef` + structures, declaring regular methods of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor. + + **Inheritance:** + + This field is not inherited by subtypes (methods are inherited through a + different mechanism). + + +.. c:member:: struct PyMemberDef* PyTypeObject.tp_members + + An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMemberDef` + structures, declaring regular data members (fields or slots) of instances of + this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor. + + **Inheritance:** + + This field is not inherited by subtypes (members are inherited through a + different mechanism). + + +.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset + + An optional pointer to a static ``NULL``-terminated array of :c:type:`PyGetSetDef` + structures, declaring computed attributes of instances of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor. + + **Inheritance:** + + This field is not inherited by subtypes (computed attributes are inherited + through a different mechanism). + + +.. c:member:: PyTypeObject* PyTypeObject.tp_base + + An optional pointer to a base type from which type properties are inherited. At + this level, only single inheritance is supported; multiple inheritance require + dynamically creating a type object by calling the metatype. + + .. note:: + + .. from Modules/xxmodule.c + + Slot initialization is subject to the rules of initializing globals. + C99 requires the initializers to be "address constants". Function + designators like :c:func:`PyType_GenericNew`, with implicit conversion + to a pointer, are valid C99 address constants. + + However, the unary '&' operator applied to a non-static variable + like :c:func:`PyBaseObject_Type` is not required to produce an address + constant. Compilers may support this (gcc does), MSVC does not. + Both compilers are strictly standard conforming in this particular + behavior. + + Consequently, :c:member:`~PyTypeObject.tp_base` should be set in + the extension module's init function. + + **Inheritance:** + + This field is not inherited by subtypes (obviously). + + **Default:** + + This field defaults to ``&PyBaseObject_Type`` (which to Python + programmers is known as the type :class:`object`). + + +.. c:member:: PyObject* PyTypeObject.tp_dict + + The type's dictionary is stored here by :c:func:`PyType_Ready`. + + This field should normally be initialized to ``NULL`` before PyType_Ready is + called; it may also be initialized to a dictionary containing initial attributes + for the type. Once :c:func:`PyType_Ready` has initialized the type, extra + attributes for the type may be added to this dictionary only if they don't + correspond to overloaded operations (like :meth:`__add__`). + + **Inheritance:** + + This field is not inherited by subtypes (though the attributes defined in here + are inherited through a different mechanism). + + **Default:** + + If this field is ``NULL``, :c:func:`PyType_Ready` will assign a new + dictionary to it. + + .. warning:: + + It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify + :c:member:`~PyTypeObject.tp_dict` with the dictionary C-API. + + +.. c:member:: descrgetfunc PyTypeObject.tp_descr_get + + An optional pointer to a "descriptor get" function. + + The function signature is:: + + PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); + + .. XXX explain more? + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: descrsetfunc PyTypeObject.tp_descr_set + + An optional pointer to a function for setting and deleting + a descriptor's value. + + The function signature is:: + + int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); + + The *value* argument is set to ``NULL`` to delete the value. + + .. XXX explain more? + + **Inheritance:** + + This field is inherited by subtypes. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset + + If the instances of this type have a dictionary containing instance variables, + this field is non-zero and contains the offset in the instances of the type of + the instance variable dictionary; this offset is used by + :c:func:`PyObject_GenericGetAttr`. + + Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is the dictionary for + attributes of the type object itself. + + If the value of this field is greater than zero, it specifies the offset from + the start of the instance structure. If the value is less than zero, it + specifies the offset from the *end* of the instance structure. A negative + offset is more expensive to use, and should only be used when the instance + structure contains a variable-length part. This is used for example to add an + instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note + that the :c:member:`~PyTypeObject.tp_basicsize` field should account for the dictionary added to + the end in that case, even though the dictionary is not included in the basic + object layout. On a system with a pointer size of 4 bytes, + :c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is + at the very end of the structure. + + The real dictionary offset in an instance can be computed from a negative + :c:member:`~PyTypeObject.tp_dictoffset` as follows:: + + dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset + if dictoffset is not aligned on sizeof(void*): + round up to sizeof(void*) + + where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are + taken from the type object, and :attr:`ob_size` is taken from the instance. The + absolute value is taken because ints use the sign of :attr:`ob_size` to + store the sign of the number. (There's never a need to do this calculation + yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.) + + **Inheritance:** + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype instances store the + dictionary at a difference offset than the base type. Since the dictionary is + always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`~object.__slots__` declaration, + and none of its base types has an instance variable dictionary, a dictionary + slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to + that slot's offset. + + When a type defined by a class statement has a :attr:`__slots__` declaration, + the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type. + + (Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does + not have the expected effect, it just causes confusion. Maybe this should be + added as a feature just like :attr:`__weakref__` though.) + + **Default:** + + This slot has no default. For static types, if the field is + ``NULL`` then no :attr:`__dict__` gets created for instances. + + +.. c:member:: initproc PyTypeObject.tp_init + + An optional pointer to an instance initialization function. + + This function corresponds to the :meth:`__init__` method of classes. Like + :meth:`__init__`, it is possible to create an instance without calling + :meth:`__init__`, and it is possible to reinitialize an instance by calling its + :meth:`__init__` method again. + + The function signature is:: + + int tp_init(PyObject *self, PyObject *args, PyObject *kwds); + + The self argument is the instance to be initialized; the *args* and *kwds* + arguments represent positional and keyword arguments of the call to + :meth:`__init__`. + + The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called when an instance is + created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function + has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an + instance of some other type that is not a subtype of the original type, no + :c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a + subtype of the original type, the subtype's :c:member:`~PyTypeObject.tp_init` is called. + + Returns ``0`` on success, ``-1`` and sets an exception on error. + + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + For static types this field does not have a default. + + +.. c:member:: allocfunc PyTypeObject.tp_alloc + + An optional pointer to an instance allocation function. + + The function signature is:: + + PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems); + + **Inheritance:** + + This field is inherited by static subtypes, but not by dynamic + subtypes (subtypes created by a class statement). + + **Default:** + + For dynamic subtypes, this field is always set to + :c:func:`PyType_GenericAlloc`, to force a standard heap + allocation strategy. + + For static subtypes, :c:type:`PyBaseObject_Type` uses + :c:func:`PyType_GenericAlloc`. That is the recommended value + for all statically defined types. + + +.. c:member:: newfunc PyTypeObject.tp_new + + An optional pointer to an instance creation function. + + The function signature is:: + + PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds); + + The *subtype* argument is the type of the object being created; the *args* and + *kwds* arguments represent positional and keyword arguments of the call to the + type. Note that *subtype* doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new` + function is called; it may be a subtype of that type (but not an unrelated + type). + + The :c:member:`~PyTypeObject.tp_new` function should call ``subtype->tp_alloc(subtype, nitems)`` + to allocate space for the object, and then do only as much further + initialization as is absolutely necessary. Initialization that can safely be + ignored or repeated should be placed in the :c:member:`~PyTypeObject.tp_init` handler. A good + rule of thumb is that for immutable types, all initialization should take place + in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be + deferred to :c:member:`~PyTypeObject.tp_init`. + + **Inheritance:** + + This field is inherited by subtypes, except it is not inherited by static types + whose :c:member:`~PyTypeObject.tp_base` is ``NULL`` or ``&PyBaseObject_Type``. + + **Default:** + + For static types this field has no default. This means if the + slot is defined as ``NULL``, the type cannot be called to create new + instances; presumably there is some other way to create + instances, like a factory function. + + +.. c:member:: freefunc PyTypeObject.tp_free + + An optional pointer to an instance deallocation function. Its signature is:: + + void tp_free(void *self); + + An initializer that is compatible with this signature is :c:func:`PyObject_Free`. + + **Inheritance:** + + This field is inherited by static subtypes, but not by dynamic + subtypes (subtypes created by a class statement) + + **Default:** + + In dynamic subtypes, this field is set to a deallocator suitable to + match :c:func:`PyType_GenericAlloc` and the value of the + :const:`Py_TPFLAGS_HAVE_GC` flag bit. + + For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del. + + +.. c:member:: inquiry PyTypeObject.tp_is_gc + + An optional pointer to a function called by the garbage collector. + + The garbage collector needs to know whether a particular object is collectible + or not. Normally, it is sufficient to look at the object's type's + :c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But + some types have a mixture of statically and dynamically allocated instances, and + the statically allocated instances are not collectible. Such types should + define this function; it should return ``1`` for a collectible instance, and + ``0`` for a non-collectible instance. The signature is:: + + int tp_is_gc(PyObject *self); + + (The only example of this are types themselves. The metatype, + :c:data:`PyType_Type`, defines this function to distinguish between statically + and dynamically allocated types.) + + **Inheritance:** + + This field is inherited by subtypes. + + **Default:** + + This slot has no default. If this field is ``NULL``, + :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. + + +.. c:member:: PyObject* PyTypeObject.tp_bases + + Tuple of base types. + + This is set for types created by a class statement. It should be ``NULL`` for + statically defined types. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_mro + + Tuple containing the expanded set of base types, starting with the type itself + and ending with :class:`object`, in Method Resolution Order. + + + **Inheritance:** + + This field is not inherited; it is calculated fresh by + :c:func:`PyType_Ready`. + + +.. c:member:: PyObject* PyTypeObject.tp_cache + + Unused. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_subclasses + + List of weak references to subclasses. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_weaklist + + Weak reference list head, for weak references to this type object. Not + inherited. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: destructor PyTypeObject.tp_del + + This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead. + + +.. c:member:: unsigned int PyTypeObject.tp_version_tag + + Used to index into the method cache. Internal use only. + + **Inheritance:** + + This field is not inherited. + + +.. c:member:: destructor PyTypeObject.tp_finalize + + An optional pointer to an instance finalization function. Its signature is:: + + void tp_finalize(PyObject *self); + + If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when + finalizing an instance. It is called either from the garbage + collector (if the instance is part of an isolated reference cycle) or + just before the object is deallocated. Either way, it is guaranteed + to be called before attempting to break reference cycles, ensuring + that it finds the object in a sane state. + + :c:member:`~PyTypeObject.tp_finalize` should not mutate the current exception status; + therefore, a recommended way to write a non-trivial finalizer is:: + + static void + local_finalize(PyObject *self) + { + PyObject *error_type, *error_value, *error_traceback; + + /* Save the current exception, if any. */ + PyErr_Fetch(&error_type, &error_value, &error_traceback); + + /* ... */ + + /* Restore the saved exception. */ + PyErr_Restore(error_type, error_value, error_traceback); + } + + For this field to be taken into account (even through inheritance), + you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. + + **Inheritance:** + + This field is inherited by subtypes. + + .. versionadded:: 3.4 + + .. seealso:: "Safe object finalization" (:pep:`442`) + + +.. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall + + Vectorcall function to use for calls of this type object. + In other words, it is used to implement + :ref:`vectorcall ` for ``type.__call__``. + If ``tp_vectorcall`` is ``NULL``, the default call implementation + using :attr:`__new__` and :attr:`__init__` is used. + + **Inheritance:** + + This field is never inherited. + + .. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9) + + +Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from +any Python thread, not just the thread which created the object (if the object +becomes part of a refcount cycle, that cycle might be collected by a garbage +collection on any thread). This is not a problem for Python API calls, since +the thread on which tp_dealloc is called will own the Global Interpreter Lock +(GIL). However, if the object being destroyed in turn destroys objects from some +other C or C++ library, care should be taken to ensure that destroying those +objects on the thread which called tp_dealloc will not violate any assumptions +of the library. + + +.. _heap-types: + +Heap Types +---------- + +Traditionally, types defined in C code are *static*, that is, +a static :c:type:`PyTypeObject` structure is defined directly in code +and initialized using :c:func:`PyType_Ready`. + +This results in types that are limited relative to types defined in Python: + +* Static types are limited to one base, i.e. they cannot use multiple + inheritance. +* Static type objects (but not necessarily their instances) are immutable. + It is not possible to add or modify the type object's attributes from Python. +* Static type objects are shared across + :ref:`sub-interpreters `, so they should not + include any subinterpreter-specific state. + +Also, since :c:type:`PyTypeObject` is not part of the :ref:`stable ABI `, +any extension modules using static types must be compiled for a specific +Python minor version. + +An alternative to static types is *heap-allocated types*, or *heap types* +for short, which correspond closely to classes created by Python's +``class`` statement. + +This is done by filling a :c:type:`PyType_Spec` structure and calling +:c:func:`PyType_FromSpecWithBases`. + + +.. _number-structs: + +Number Object Structures +======================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PyNumberMethods + + This structure holds pointers to the functions which an object uses to + implement the number protocol. Each function is used by the function of + similar name documented in the :ref:`number` section. + + .. XXX Drop the definition? + + Here is the structure definition:: + + typedef struct { + binaryfunc nb_add; + binaryfunc nb_subtract; + binaryfunc nb_multiply; + binaryfunc nb_remainder; + binaryfunc nb_divmod; + ternaryfunc nb_power; + unaryfunc nb_negative; + unaryfunc nb_positive; + unaryfunc nb_absolute; + inquiry nb_bool; + unaryfunc nb_invert; + binaryfunc nb_lshift; + binaryfunc nb_rshift; + binaryfunc nb_and; + binaryfunc nb_xor; + binaryfunc nb_or; + unaryfunc nb_int; + void *nb_reserved; + unaryfunc nb_float; + + binaryfunc nb_inplace_add; + binaryfunc nb_inplace_subtract; + binaryfunc nb_inplace_multiply; + binaryfunc nb_inplace_remainder; + ternaryfunc nb_inplace_power; + binaryfunc nb_inplace_lshift; + binaryfunc nb_inplace_rshift; + binaryfunc nb_inplace_and; + binaryfunc nb_inplace_xor; + binaryfunc nb_inplace_or; + + binaryfunc nb_floor_divide; + binaryfunc nb_true_divide; + binaryfunc nb_inplace_floor_divide; + binaryfunc nb_inplace_true_divide; + + unaryfunc nb_index; + + binaryfunc nb_matrix_multiply; + binaryfunc nb_inplace_matrix_multiply; + } PyNumberMethods; + + .. note:: + + Binary and ternary functions must check the type of all their operands, + and implement the necessary conversions (at least one of the operands is + an instance of the defined type). If the operation is not defined for the + given operands, binary and ternary functions must return + ``Py_NotImplemented``, if another error occurred they must return ``NULL`` + and set an exception. + + .. note:: + + The :c:data:`nb_reserved` field should always be ``NULL``. It + was previously called :c:data:`nb_long`, and was renamed in + Python 3.0.1. + +.. c:member:: binaryfunc PyNumberMethods.nb_add +.. c:member:: binaryfunc PyNumberMethods.nb_subtract +.. c:member:: binaryfunc PyNumberMethods.nb_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_remainder +.. c:member:: binaryfunc PyNumberMethods.nb_divmod +.. c:member:: ternaryfunc PyNumberMethods.nb_power +.. c:member:: unaryfunc PyNumberMethods.nb_negative +.. c:member:: unaryfunc PyNumberMethods.nb_positive +.. c:member:: unaryfunc PyNumberMethods.nb_absolute +.. c:member:: inquiry PyNumberMethods.nb_bool +.. c:member:: unaryfunc PyNumberMethods.nb_invert +.. c:member:: binaryfunc PyNumberMethods.nb_lshift +.. c:member:: binaryfunc PyNumberMethods.nb_rshift +.. c:member:: binaryfunc PyNumberMethods.nb_and +.. c:member:: binaryfunc PyNumberMethods.nb_xor +.. c:member:: binaryfunc PyNumberMethods.nb_or +.. c:member:: unaryfunc PyNumberMethods.nb_int +.. c:member:: void *PyNumberMethods.nb_reserved +.. c:member:: unaryfunc PyNumberMethods.nb_float +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_add +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder +.. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_and +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_or +.. c:member:: binaryfunc PyNumberMethods.nb_floor_divide +.. c:member:: binaryfunc PyNumberMethods.nb_true_divide +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide +.. c:member:: unaryfunc PyNumberMethods.nb_index +.. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply +.. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply + + +.. _mapping-structs: + +Mapping Object Structures +========================= + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PyMappingMethods + + This structure holds pointers to the functions which an object uses to + implement the mapping protocol. It has three members: + +.. c:member:: lenfunc PyMappingMethods.mp_length + + This function is used by :c:func:`PyMapping_Size` and + :c:func:`PyObject_Size`, and has the same signature. This slot may be set to + ``NULL`` if the object has no defined length. + +.. c:member:: binaryfunc PyMappingMethods.mp_subscript + + This function is used by :c:func:`PyObject_GetItem` and + :c:func:`PySequence_GetSlice`, and has the same signature as + :c:func:`!PyObject_GetItem`. This slot must be filled for the + :c:func:`PyMapping_Check` function to return ``1``, it can be ``NULL`` + otherwise. + +.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript + + This function is used by :c:func:`PyObject_SetItem`, + :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and + :c:func:`PyObject_DelSlice`. It has the same signature as + :c:func:`!PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete + an item. If this slot is ``NULL``, the object does not support item + assignment and deletion. + + +.. _sequence-structs: + +Sequence Object Structures +========================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PySequenceMethods + + This structure holds pointers to the functions which an object uses to + implement the sequence protocol. + +.. c:member:: lenfunc PySequenceMethods.sq_length + + This function is used by :c:func:`PySequence_Size` and + :c:func:`PyObject_Size`, and has the same signature. It is also used for + handling negative indices via the :c:member:`~PySequenceMethods.sq_item` + and the :c:member:`~PySequenceMethods.sq_ass_item` slots. + +.. c:member:: binaryfunc PySequenceMethods.sq_concat + + This function is used by :c:func:`PySequence_Concat` and has the same + signature. It is also used by the ``+`` operator, after trying the numeric + addition via the :c:member:`~PyNumberMethods.nb_add` slot. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat + + This function is used by :c:func:`PySequence_Repeat` and has the same + signature. It is also used by the ``*`` operator, after trying numeric + multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_item + + This function is used by :c:func:`PySequence_GetItem` and has the same + signature. It is also used by :c:func:`PyObject_GetItem`, after trying + the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. + This slot must be filled for the :c:func:`PySequence_Check` + function to return ``1``, it can be ``NULL`` otherwise. + + Negative indexes are handled as follows: if the :attr:`sq_length` slot is + filled, it is called and the sequence length is used to compute a positive + index which is passed to :attr:`sq_item`. If :attr:`sq_length` is ``NULL``, + the index is passed as is to the function. + +.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item + + This function is used by :c:func:`PySequence_SetItem` and has the same + signature. It is also used by :c:func:`PyObject_SetItem` and + :c:func:`PyObject_DelItem`, after trying the item assignment and deletion + via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot. + This slot may be left to ``NULL`` if the object does not support + item assignment and deletion. + +.. c:member:: objobjproc PySequenceMethods.sq_contains + + This function may be used by :c:func:`PySequence_Contains` and has the same + signature. This slot may be left to ``NULL``, in this case + :c:func:`!PySequence_Contains` simply traverses the sequence until it + finds a match. + +.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat + + This function is used by :c:func:`PySequence_InPlaceConcat` and has the same + signature. It should modify its first operand, and return it. This slot + may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat` + will fall back to :c:func:`PySequence_Concat`. It is also used by the + augmented assignment ``+=``, after trying numeric in-place addition + via the :c:member:`~PyNumberMethods.nb_inplace_add` slot. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat + + This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same + signature. It should modify its first operand, and return it. This slot + may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat` + will fall back to :c:func:`PySequence_Repeat`. It is also used by the + augmented assignment ``*=``, after trying numeric in-place multiplication + via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot. + + +.. _buffer-structs: + +Buffer Object Structures +======================== + +.. sectionauthor:: Greg J. Stein +.. sectionauthor:: Benjamin Peterson +.. sectionauthor:: Stefan Krah + +.. c:type:: PyBufferProcs + + This structure holds pointers to the functions required by the + :ref:`Buffer protocol `. The protocol defines how + an exporter object can expose its internal data to consumer objects. + +.. c:member:: getbufferproc PyBufferProcs.bf_getbuffer + + The signature of this function is:: + + int (PyObject *exporter, Py_buffer *view, int flags); + + Handle a request to *exporter* to fill in *view* as specified by *flags*. + Except for point (3), an implementation of this function MUST take these + steps: + + (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, + set :c:data:`view->obj` to ``NULL`` and return ``-1``. + + (2) Fill in the requested fields. + + (3) Increment an internal counter for the number of exports. + + (4) Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`. + + (5) Return ``0``. + + If *exporter* is part of a chain or tree of buffer providers, two main + schemes can be used: + + * Re-export: Each member of the tree acts as the exporting object and + sets :c:data:`view->obj` to a new reference to itself. + + * Redirect: The buffer request is redirected to the root object of the + tree. Here, :c:data:`view->obj` will be a new reference to the root + object. + + The individual fields of *view* are described in section + :ref:`Buffer structure `, the rules how an exporter + must react to specific requests are in section + :ref:`Buffer request types `. + + All memory pointed to in the :c:type:`Py_buffer` structure belongs to + the exporter and must remain valid until there are no consumers left. + :c:member:`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, + :c:member:`~Py_buffer.strides`, :c:member:`~Py_buffer.suboffsets` + and :c:member:`~Py_buffer.internal` + are read-only for the consumer. + + :c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple + bytes buffer while dealing correctly with all request types. + + :c:func:`PyObject_GetBuffer` is the interface for the consumer that + wraps this function. + +.. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer + + The signature of this function is:: + + void (PyObject *exporter, Py_buffer *view); + + Handle a request to release the resources of the buffer. If no resources + need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be + ``NULL``. Otherwise, a standard implementation of this function will take + these optional steps: + + (1) Decrement an internal counter for the number of exports. + + (2) If the counter is ``0``, free all memory associated with *view*. + + The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep + track of buffer-specific resources. This field is guaranteed to remain + constant, while a consumer MAY pass a copy of the original buffer as the + *view* argument. + + + This function MUST NOT decrement :c:data:`view->obj`, since that is + done automatically in :c:func:`PyBuffer_Release` (this scheme is + useful for breaking reference cycles). + + + :c:func:`PyBuffer_Release` is the interface for the consumer that + wraps this function. + + +.. _async-structs: + + +Async Object Structures +======================= + +.. sectionauthor:: Yury Selivanov + +.. versionadded:: 3.5 + +.. c:type:: PyAsyncMethods + + This structure holds pointers to the functions required to implement + :term:`awaitable` and :term:`asynchronous iterator` objects. + + Here is the structure definition:: + + typedef struct { + unaryfunc am_await; + unaryfunc am_aiter; + unaryfunc am_anext; + } PyAsyncMethods; + +.. c:member:: unaryfunc PyAsyncMethods.am_await + + The signature of this function is:: + + PyObject *am_await(PyObject *self); + + The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must + return ``1`` for it. + + This slot may be set to ``NULL`` if an object is not an :term:`awaitable`. + +.. c:member:: unaryfunc PyAsyncMethods.am_aiter + + The signature of this function is:: + + PyObject *am_aiter(PyObject *self); + + Must return an :term:`awaitable` object. See :meth:`__anext__` for details. + + This slot may be set to ``NULL`` if an object does not implement + asynchronous iteration protocol. + +.. c:member:: unaryfunc PyAsyncMethods.am_anext + + The signature of this function is:: + + PyObject *am_anext(PyObject *self); + + Must return an :term:`awaitable` object. See :meth:`__anext__` for details. + This slot may be set to ``NULL``. + + +.. _slot-typedefs: + +Slot Type typedefs +================== + +.. c:type:: PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems) + + The purpose of this function is to separate memory allocation from memory + initialization. It should return a pointer to a block of memory of adequate + length for the instance, suitably aligned, and initialized to zeros, but with + :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If + the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field + should be initialized to *nitems* and the length of the allocated memory block + should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of + ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block + should be :c:member:`~PyTypeObject.tp_basicsize`. + + This function should not do any other instance initialization, not even to + allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`. + +.. c:type:: void (*destructor)(PyObject *) + +.. c:type:: void (*freefunc)(void *) + + See :c:member:`~PyTypeObject.tp_free`. + +.. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *) + + See :c:member:`~PyTypeObject.tp_new`. + +.. c:type:: int (*initproc)(PyObject *, PyObject *, PyObject *) + + See :c:member:`~PyTypeObject.tp_init`. + +.. c:type:: PyObject *(*reprfunc)(PyObject *) + + See :c:member:`~PyTypeObject.tp_repr`. + +.. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr) + + Return the value of the named attribute for the object. + +.. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value) + + Set the value of the named attribute for the object. + The value argument is set to ``NULL`` to delete the attribute. + +.. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr) + + Return the value of the named attribute for the object. + + See :c:member:`~PyTypeObject.tp_getattro`. + +.. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) + + Set the value of the named attribute for the object. + The value argument is set to ``NULL`` to delete the attribute. + + See :c:member:`~PyTypeObject.tp_setattro`. + +.. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *) + + See :c:member:`~PyTypeObject.tp_descrget`. + +.. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *) + + See :c:member:`~PyTypeObject.tp_descrset`. + +.. c:type:: Py_hash_t (*hashfunc)(PyObject *) + + See :c:member:`~PyTypeObject.tp_hash`. + +.. c:type:: PyObject *(*richcmpfunc)(PyObject *, PyObject *, int) + + See :c:member:`~PyTypeObject.tp_richcompare`. + +.. c:type:: PyObject *(*getiterfunc)(PyObject *) + + See :c:member:`~PyTypeObject.tp_iter`. + +.. c:type:: PyObject *(*iternextfunc)(PyObject *) + + See :c:member:`~PyTypeObject.tp_iternext`. + +.. c:type:: Py_ssize_t (*lenfunc)(PyObject *) + +.. c:type:: int (*getbufferproc)(PyObject *, Py_buffer *, int) + +.. c:type:: void (*releasebufferproc)(PyObject *, Py_buffer *) + +.. c:type:: PyObject *(*unaryfunc)(PyObject *) + +.. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *) + +.. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *) + +.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t) + +.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t) + +.. c:type:: int (*objobjproc)(PyObject *, PyObject *) + +.. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) + + +.. _typedef-examples: + +Examples +======== + +The following are simple examples of Python type definitions. They +include common usage you may encounter. Some demonstrate tricky corner +cases. For more examples, practical info, and a tutorial, see +:ref:`defining-new-types` and :ref:`new-types-topics`. + +A basic static type:: + + typedef struct { + PyObject_HEAD + const char *data; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_new = myobj_new, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + }; + +You may also find older code (especially in the CPython code base) +with a more verbose initializer:: + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + "mymod.MyObject", /* tp_name */ + sizeof(MyObject), /* tp_basicsize */ + 0, /* tp_itemsize */ + (destructor)myobj_dealloc, /* tp_dealloc */ + 0, /* tp_vectorcall_offset */ + 0, /* tp_getattr */ + 0, /* tp_setattr */ + 0, /* tp_as_async */ + (reprfunc)myobj_repr, /* tp_repr */ + 0, /* tp_as_number */ + 0, /* tp_as_sequence */ + 0, /* tp_as_mapping */ + 0, /* tp_hash */ + 0, /* tp_call */ + 0, /* tp_str */ + 0, /* tp_getattro */ + 0, /* tp_setattro */ + 0, /* tp_as_buffer */ + 0, /* tp_flags */ + "My objects", /* tp_doc */ + 0, /* tp_traverse */ + 0, /* tp_clear */ + 0, /* tp_richcompare */ + 0, /* tp_weaklistoffset */ + 0, /* tp_iter */ + 0, /* tp_iternext */ + 0, /* tp_methods */ + 0, /* tp_members */ + 0, /* tp_getset */ + 0, /* tp_base */ + 0, /* tp_dict */ + 0, /* tp_descr_get */ + 0, /* tp_descr_set */ + 0, /* tp_dictoffset */ + 0, /* tp_init */ + 0, /* tp_alloc */ + myobj_new, /* tp_new */ + }; + +A type that supports weakrefs, instance dicts, and hashing:: + + typedef struct { + PyObject_HEAD + const char *data; + PyObject *inst_dict; + PyObject *weakreflist; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject), + .tp_doc = "My objects", + .tp_weaklistoffset = offsetof(MyObject, weakreflist), + .tp_dictoffset = offsetof(MyObject, inst_dict), + .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, + .tp_new = myobj_new, + .tp_traverse = (traverseproc)myobj_traverse, + .tp_clear = (inquiry)myobj_clear, + .tp_alloc = PyType_GenericNew, + .tp_dealloc = (destructor)myobj_dealloc, + .tp_repr = (reprfunc)myobj_repr, + .tp_hash = (hashfunc)myobj_hash, + .tp_richcompare = PyBaseObject_Type.tp_richcompare, + }; + +A str subclass that cannot be subclassed and cannot be called +to create instances (e.g. uses a separate factory func):: + + typedef struct { + PyUnicodeObject raw; + char *extra; + } MyStr; + + static PyTypeObject MyStr_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyStr", + .tp_basicsize = sizeof(MyStr), + .tp_base = NULL, // set to &PyUnicode_Type in module init + .tp_doc = "my custom str", + .tp_flags = Py_TPFLAGS_DEFAULT, + .tp_new = NULL, + .tp_repr = (reprfunc)myobj_repr, + }; + +The simplest static type (with fixed-length instances):: + + typedef struct { + PyObject_HEAD + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + }; + +The simplest static type (with variable-length instances):: + + typedef struct { + PyObject_VAR_HEAD + const char *data[1]; + } MyObject; + + static PyTypeObject MyObject_Type = { + PyVarObject_HEAD_INIT(NULL, 0) + .tp_name = "mymod.MyObject", + .tp_basicsize = sizeof(MyObject) - sizeof(char *), + .tp_itemsize = sizeof(char *), + }; diff --git a/Doc/library/fractions.rst.bak b/Doc/library/fractions.rst.bak new file mode 100644 index 00000000000000..d3a42762e3ff8d --- /dev/null +++ b/Doc/library/fractions.rst.bak @@ -0,0 +1,178 @@ +:mod:`fractions` --- Rational numbers +===================================== + +.. module:: fractions + :synopsis: Rational numbers. + +.. moduleauthor:: Jeffrey Yasskin +.. sectionauthor:: Jeffrey Yasskin + +**Source code:** :source:`Lib/fractions.py` + +-------------- + +The :mod:`fractions` module provides support for rational number arithmetic. + + +A Fraction instance can be constructed from a pair of integers, from +another rational number, or from a string. + +.. class:: Fraction(numerator=0, denominator=1) + Fraction(other_fraction) + Fraction(float) + Fraction(decimal) + Fraction(string) + + The first version requires that *numerator* and *denominator* are instances + of :class:`numbers.Rational` and returns a new :class:`Fraction` instance + with value ``numerator/denominator``. If *denominator* is :const:`0`, it + raises a :exc:`ZeroDivisionError`. The second version requires that + *other_fraction* is an instance of :class:`numbers.Rational` and returns a + :class:`Fraction` instance with the same value. The next two versions accept + either a :class:`float` or a :class:`decimal.Decimal` instance, and return a + :class:`Fraction` instance with exactly the same value. Note that due to the + usual issues with binary floating-point (see :ref:`tut-fp-issues`), the + argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so + ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect. + (But see the documentation for the :meth:`limit_denominator` method below.) + The last version of the constructor expects a string or unicode instance. + The usual form for this instance is:: + + [sign] numerator ['/' denominator] + + where the optional ``sign`` may be either '+' or '-' and + ``numerator`` and ``denominator`` (if present) are strings of + decimal digits. In addition, any string that represents a finite + value and is accepted by the :class:`float` constructor is also + accepted by the :class:`Fraction` constructor. In either form the + input string may also have leading and/or trailing whitespace. + Here are some examples:: + + >>> from fractions import Fraction + >>> Fraction(16, -10) + Fraction(-8, 5) + >>> Fraction(123) + Fraction(123, 1) + >>> Fraction() + Fraction(0, 1) + >>> Fraction('3/7') + Fraction(3, 7) + >>> Fraction(' -3/7 ') + Fraction(-3, 7) + >>> Fraction('1.414213 \t\n') + Fraction(1414213, 1000000) + >>> Fraction('-.125') + Fraction(-1, 8) + >>> Fraction('7e-6') + Fraction(7, 1000000) + >>> Fraction(2.25) + Fraction(9, 4) + >>> Fraction(1.1) + Fraction(2476979795053773, 2251799813685248) + >>> from decimal import Decimal + >>> Fraction(Decimal('1.1')) + Fraction(11, 10) + + + The :class:`Fraction` class inherits from the abstract base class + :class:`numbers.Rational`, and implements all of the methods and + operations from that class. :class:`Fraction` instances are hashable, + and should be treated as immutable. In addition, + :class:`Fraction` has the following properties and methods: + + .. versionchanged:: 3.2 + The :class:`Fraction` constructor now accepts :class:`float` and + :class:`decimal.Decimal` instances. + + + .. attribute:: numerator + + Numerator of the Fraction in lowest term. + + .. attribute:: denominator + + Denominator of the Fraction in lowest term. + + + .. method:: as_integer_ratio() + + Return a tuple of two integers, whose ratio is equal + to the Fraction and with a positive denominator. + + .. versionadded:: 3.8 + + .. method:: from_float(flt) + + This class method constructs a :class:`Fraction` representing the exact + value of *flt*, which must be a :class:`float`. Beware that + ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. + + .. note:: + + From Python 3.2 onwards, you can also construct a + :class:`Fraction` instance directly from a :class:`float`. + + + .. method:: from_decimal(dec) + + This class method constructs a :class:`Fraction` representing the exact + value of *dec*, which must be a :class:`decimal.Decimal` instance. + + .. note:: + + From Python 3.2 onwards, you can also construct a + :class:`Fraction` instance directly from a :class:`decimal.Decimal` + instance. + + + .. method:: limit_denominator(max_denominator=1000000) + + Finds and returns the closest :class:`Fraction` to ``self`` that has + denominator at most max_denominator. This method is useful for finding + rational approximations to a given floating-point number: + + >>> from fractions import Fraction + >>> Fraction('3.1415926535897932').limit_denominator(1000) + Fraction(355, 113) + + or for recovering a rational number that's represented as a float: + + >>> from math import pi, cos + >>> Fraction(cos(pi/3)) + Fraction(4503599627370497, 9007199254740992) + >>> Fraction(cos(pi/3)).limit_denominator() + Fraction(1, 2) + >>> Fraction(1.1).limit_denominator() + Fraction(11, 10) + + + .. method:: __floor__() + + Returns the greatest :class:`int` ``<= self``. This method can + also be accessed through the :func:`math.floor` function: + + >>> from math import floor + >>> floor(Fraction(355, 113)) + 3 + + + .. method:: __ceil__() + + Returns the least :class:`int` ``>= self``. This method can + also be accessed through the :func:`math.ceil` function. + + + .. method:: __round__() + __round__(ndigits) + + The first version returns the nearest :class:`int` to ``self``, + rounding half to even. The second version rounds ``self`` to the + nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if + ``ndigits`` is negative), again rounding half toward even. This + method can also be accessed through the :func:`round` function. + + +.. seealso:: + + Module :mod:`numbers` + The abstract base classes making up the numeric tower. diff --git a/Doc/library/os.rst.bak b/Doc/library/os.rst.bak new file mode 100644 index 00000000000000..f59423c6f2d4ee --- /dev/null +++ b/Doc/library/os.rst.bak @@ -0,0 +1,4513 @@ +:mod:`os` --- Miscellaneous operating system interfaces +======================================================= + +.. module:: os + :synopsis: Miscellaneous operating system interfaces. + +**Source code:** :source:`Lib/os.py` + +-------------- + +This module provides a portable way of using operating system dependent +functionality. If you just want to read or write a file see :func:`open`, if +you want to manipulate paths, see the :mod:`os.path` module, and if you want to +read all the lines in all the files on the command line see the :mod:`fileinput` +module. For creating temporary files and directories see the :mod:`tempfile` +module, and for high-level file and directory handling see the :mod:`shutil` +module. + +Notes on the availability of these functions: + +* The design of all built-in operating system dependent modules of Python is + such that as long as the same functionality is available, it uses the same + interface; for example, the function ``os.stat(path)`` returns stat + information about *path* in the same format (which happens to have originated + with the POSIX interface). + +* Extensions peculiar to a particular operating system are also available + through the :mod:`os` module, but using them is of course a threat to + portability. + +* All functions accepting path or file names accept both bytes and string + objects, and result in an object of the same type, if a path or file name is + returned. + +* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported. + +.. note:: + + All functions in this module raise :exc:`OSError` (or subclasses thereof) in + the case of invalid or inaccessible file names and paths, or other arguments + that have the correct type, but are not accepted by the operating system. + +.. exception:: error + + An alias for the built-in :exc:`OSError` exception. + + +.. data:: name + + The name of the operating system dependent module imported. The following + names have currently been registered: ``'posix'``, ``'nt'``, + ``'java'``. + + .. seealso:: + :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives + system-dependent version information. + + The :mod:`platform` module provides detailed checks for the + system's identity. + + +.. _os-filenames: +.. _filesystem-encoding: + +File Names, Command Line Arguments, and Environment Variables +------------------------------------------------------------- + +In Python, file names, command line arguments, and environment variables are +represented using the string type. On some systems, decoding these strings to +and from bytes is necessary before passing them to the operating system. Python +uses the file system encoding to perform this conversion (see +:func:`sys.getfilesystemencoding`). + +.. versionchanged:: 3.1 + On some systems, conversion using the file system encoding may fail. In this + case, Python uses the :ref:`surrogateescape encoding error handler + `, which means that undecodable bytes are replaced by a + Unicode character U+DCxx on decoding, and these are again translated to the + original byte on encoding. + + +The file system encoding must guarantee to successfully decode all bytes +below 128. If the file system encoding fails to provide this guarantee, API +functions may raise UnicodeErrors. + + +.. _os-procinfo: + +Process Parameters +------------------ + +These functions and data items provide information and operate on the current +process and user. + + +.. function:: ctermid() + + Return the filename corresponding to the controlling terminal of the process. + + .. availability:: Unix. + + +.. data:: environ + + A :term:`mapping` object representing the string environment. For example, + ``environ['HOME']`` is the pathname of your home directory (on some platforms), + and is equivalent to ``getenv("HOME")`` in C. + + This mapping is captured the first time the :mod:`os` module is imported, + typically during Python startup as part of processing :file:`site.py`. Changes + to the environment made after this time are not reflected in ``os.environ``, + except for changes made by modifying ``os.environ`` directly. + + This mapping may be used to modify the environment as well as query the + environment. :func:`putenv` will be called automatically when the mapping + is modified. + + On Unix, keys and values use :func:`sys.getfilesystemencoding` and + ``'surrogateescape'`` error handler. Use :data:`environb` if you would like + to use a different encoding. + + .. note:: + + Calling :func:`putenv` directly does not change ``os.environ``, so it's better + to modify ``os.environ``. + + .. note:: + + On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may + cause memory leaks. Refer to the system documentation for + :c:func:`putenv`. + + You can delete items in this mapping to unset environment variables. + :func:`unsetenv` will be called automatically when an item is deleted from + ``os.environ``, and when one of the :meth:`pop` or :meth:`clear` methods is + called. + + +.. data:: environb + + Bytes version of :data:`environ`: a :term:`mapping` object representing the + environment as byte strings. :data:`environ` and :data:`environb` are + synchronized (modify :data:`environb` updates :data:`environ`, and vice + versa). + + :data:`environb` is only available if :data:`supports_bytes_environ` is + ``True``. + + .. versionadded:: 3.2 + + +.. function:: chdir(path) + fchdir(fd) + getcwd() + :noindex: + + These functions are described in :ref:`os-file-dir`. + + +.. function:: fsencode(filename) + + Encode :term:`path-like ` *filename* to the filesystem + encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on + Windows; return :class:`bytes` unchanged. + + :func:`fsdecode` is the reverse function. + + .. versionadded:: 3.2 + + .. versionchanged:: 3.6 + Support added to accept objects implementing the :class:`os.PathLike` + interface. + + +.. function:: fsdecode(filename) + + Decode the :term:`path-like ` *filename* from the + filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'`` + on Windows; return :class:`str` unchanged. + + :func:`fsencode` is the reverse function. + + .. versionadded:: 3.2 + + .. versionchanged:: 3.6 + Support added to accept objects implementing the :class:`os.PathLike` + interface. + + +.. function:: fspath(path) + + Return the file system representation of the path. + + If :class:`str` or :class:`bytes` is passed in, it is returned unchanged. + Otherwise :meth:`~os.PathLike.__fspath__` is called and its value is + returned as long as it is a :class:`str` or :class:`bytes` object. + In all other cases, :exc:`TypeError` is raised. + + .. versionadded:: 3.6 + + +.. class:: PathLike + + An :term:`abstract base class` for objects representing a file system path, + e.g. :class:`pathlib.PurePath`. + + .. versionadded:: 3.6 + + .. abstractmethod:: __fspath__() + + Return the file system path representation of the object. + + The method should only return a :class:`str` or :class:`bytes` object, + with the preference being for :class:`str`. + + +.. function:: getenv(key, default=None) + + Return the value of the environment variable *key* if it exists, or + *default* if it doesn't. *key*, *default* and the result are str. + + On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding` + and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you + would like to use a different encoding. + + .. availability:: most flavors of Unix, Windows. + + +.. function:: getenvb(key, default=None) + + Return the value of the environment variable *key* if it exists, or + *default* if it doesn't. *key*, *default* and the result are bytes. + + :func:`getenvb` is only available if :data:`supports_bytes_environ` + is ``True``. + + .. availability:: most flavors of Unix. + + .. versionadded:: 3.2 + + +.. function:: get_exec_path(env=None) + + Returns the list of directories that will be searched for a named + executable, similar to a shell, when launching a process. + *env*, when specified, should be an environment variable dictionary + to lookup the PATH in. + By default, when *env* is ``None``, :data:`environ` is used. + + .. versionadded:: 3.2 + + +.. function:: getegid() + + Return the effective group id of the current process. This corresponds to the + "set id" bit on the file being executed in the current process. + + .. availability:: Unix. + + +.. function:: geteuid() + + .. index:: single: user; effective id + + Return the current process's effective user id. + + .. availability:: Unix. + + +.. function:: getgid() + + .. index:: single: process; group + + Return the real group id of the current process. + + .. availability:: Unix. + + +.. function:: getgrouplist(user, group) + + Return list of group ids that *user* belongs to. If *group* is not in the + list, it is included; typically, *group* is specified as the group ID + field from the password record for *user*. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: getgroups() + + Return list of supplemental group ids associated with the current process. + + .. availability:: Unix. + + .. note:: + + On Mac OS X, :func:`getgroups` behavior differs somewhat from + other Unix platforms. If the Python interpreter was built with a + deployment target of :const:`10.5` or earlier, :func:`getgroups` returns + the list of effective group ids associated with the current user process; + this list is limited to a system-defined number of entries, typically 16, + and may be modified by calls to :func:`setgroups` if suitably privileged. + If built with a deployment target greater than :const:`10.5`, + :func:`getgroups` returns the current group access list for the user + associated with the effective user id of the process; the group access + list may change over the lifetime of the process, it is not affected by + calls to :func:`setgroups`, and its length is not limited to 16. The + deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be + obtained with :func:`sysconfig.get_config_var`. + + +.. function:: getlogin() + + Return the name of the user logged in on the controlling terminal of the + process. For most purposes, it is more useful to use + :func:`getpass.getuser` since the latter checks the environment variables + :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, and + falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the + current real user id. + + .. availability:: Unix, Windows. + + +.. function:: getpgid(pid) + + Return the process group id of the process with process id *pid*. If *pid* is 0, + the process group id of the current process is returned. + + .. availability:: Unix. + +.. function:: getpgrp() + + .. index:: single: process; group + + Return the id of the current process group. + + .. availability:: Unix. + + +.. function:: getpid() + + .. index:: single: process; id + + Return the current process id. + + +.. function:: getppid() + + .. index:: single: process; id of parent + + Return the parent's process id. When the parent process has exited, on Unix + the id returned is the one of the init process (1), on Windows it is still + the same id, which may be already reused by another process. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.2 + Added support for Windows. + + +.. function:: getpriority(which, who) + + .. index:: single: process; scheduling priority + + Get program scheduling priority. The value *which* is one of + :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* + is interpreted relative to *which* (a process identifier for + :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a + user ID for :const:`PRIO_USER`). A zero value for *who* denotes + (respectively) the calling process, the process group of the calling process, + or the real user ID of the calling process. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. data:: PRIO_PROCESS + PRIO_PGRP + PRIO_USER + + Parameters for the :func:`getpriority` and :func:`setpriority` functions. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: getresuid() + + Return a tuple (ruid, euid, suid) denoting the current process's + real, effective, and saved user ids. + + .. availability:: Unix. + + .. versionadded:: 3.2 + + +.. function:: getresgid() + + Return a tuple (rgid, egid, sgid) denoting the current process's + real, effective, and saved group ids. + + .. availability:: Unix. + + .. versionadded:: 3.2 + + +.. function:: getuid() + + .. index:: single: user; id + + Return the current process's real user id. + + .. availability:: Unix. + + +.. function:: initgroups(username, gid) + + Call the system initgroups() to initialize the group access list with all of + the groups of which the specified username is a member, plus the specified + group id. + + .. availability:: Unix. + + .. versionadded:: 3.2 + + +.. function:: putenv(key, value) + + .. index:: single: environment variables; setting + + Set the environment variable named *key* to the string *value*. Such + changes to the environment affect subprocesses started with :func:`os.system`, + :func:`popen` or :func:`fork` and :func:`execv`. + + Assignments to items in ``os.environ`` are automatically translated into + corresponding calls to :func:`putenv`; however, calls to :func:`putenv` + don't update ``os.environ``, so it is actually preferable to assign to items + of ``os.environ``. + + .. note:: + + On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may + cause memory leaks. Refer to the system documentation for :c:func:`putenv`. + + .. versionchanged:: 3.9 + The function is now always available. + + +.. function:: setegid(egid) + + Set the current process's effective group id. + + .. availability:: Unix. + + +.. function:: seteuid(euid) + + Set the current process's effective user id. + + .. availability:: Unix. + + +.. function:: setgid(gid) + + Set the current process' group id. + + .. availability:: Unix. + + +.. function:: setgroups(groups) + + Set the list of supplemental group ids associated with the current process to + *groups*. *groups* must be a sequence, and each element must be an integer + identifying a group. This operation is typically available only to the superuser. + + .. availability:: Unix. + + .. note:: On Mac OS X, the length of *groups* may not exceed the + system-defined maximum number of effective group ids, typically 16. + See the documentation for :func:`getgroups` for cases where it may not + return the same group list set by calling setgroups(). + +.. function:: setpgrp() + + Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on + which version is implemented (if any). See the Unix manual for the semantics. + + .. availability:: Unix. + + +.. function:: setpgid(pid, pgrp) + + Call the system call :c:func:`setpgid` to set the process group id of the + process with id *pid* to the process group with id *pgrp*. See the Unix manual + for the semantics. + + .. availability:: Unix. + + +.. function:: setpriority(which, who, priority) + + .. index:: single: process; scheduling priority + + Set program scheduling priority. The value *which* is one of + :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* + is interpreted relative to *which* (a process identifier for + :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a + user ID for :const:`PRIO_USER`). A zero value for *who* denotes + (respectively) the calling process, the process group of the calling process, + or the real user ID of the calling process. + *priority* is a value in the range -20 to 19. The default priority is 0; + lower priorities cause more favorable scheduling. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: setregid(rgid, egid) + + Set the current process's real and effective group ids. + + .. availability:: Unix. + + +.. function:: setresgid(rgid, egid, sgid) + + Set the current process's real, effective, and saved group ids. + + .. availability:: Unix. + + .. versionadded:: 3.2 + + +.. function:: setresuid(ruid, euid, suid) + + Set the current process's real, effective, and saved user ids. + + .. availability:: Unix. + + .. versionadded:: 3.2 + + +.. function:: setreuid(ruid, euid) + + Set the current process's real and effective user ids. + + .. availability:: Unix. + + +.. function:: getsid(pid) + + Call the system call :c:func:`getsid`. See the Unix manual for the semantics. + + .. availability:: Unix. + + +.. function:: setsid() + + Call the system call :c:func:`setsid`. See the Unix manual for the semantics. + + .. availability:: Unix. + + +.. function:: setuid(uid) + + .. index:: single: user; id, setting + + Set the current process's user id. + + .. availability:: Unix. + + +.. placed in this section since it relates to errno.... a little weak +.. function:: strerror(code) + + Return the error message corresponding to the error code in *code*. + On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown + error number, :exc:`ValueError` is raised. + + +.. data:: supports_bytes_environ + + ``True`` if the native OS type of the environment is bytes (eg. ``False`` on + Windows). + + .. versionadded:: 3.2 + + +.. function:: umask(mask) + + Set the current numeric umask and return the previous umask. + + +.. function:: uname() + + .. index:: + single: gethostname() (in module socket) + single: gethostbyaddr() (in module socket) + + Returns information identifying the current operating system. + The return value is an object with five attributes: + + * :attr:`sysname` - operating system name + * :attr:`nodename` - name of machine on network (implementation-defined) + * :attr:`release` - operating system release + * :attr:`version` - operating system version + * :attr:`machine` - hardware identifier + + For backwards compatibility, this object is also iterable, behaving + like a five-tuple containing :attr:`sysname`, :attr:`nodename`, + :attr:`release`, :attr:`version`, and :attr:`machine` + in that order. + + Some systems truncate :attr:`nodename` to 8 characters or to the + leading component; a better way to get the hostname is + :func:`socket.gethostname` or even + ``socket.gethostbyaddr(socket.gethostname())``. + + .. availability:: recent flavors of Unix. + + .. versionchanged:: 3.3 + Return type changed from a tuple to a tuple-like object + with named attributes. + + +.. function:: unsetenv(key) + + .. index:: single: environment variables; deleting + + Unset (delete) the environment variable named *key*. Such changes to the + environment affect subprocesses started with :func:`os.system`, :func:`popen` or + :func:`fork` and :func:`execv`. + + Deletion of items in ``os.environ`` is automatically translated into a + corresponding call to :func:`unsetenv`; however, calls to :func:`unsetenv` + don't update ``os.environ``, so it is actually preferable to delete items of + ``os.environ``. + + .. versionchanged:: 3.9 + The function is now always available and is also available on Windows. + + +.. _os-newstreams: + +File Object Creation +-------------------- + +These functions create new :term:`file objects `. (See also +:func:`~os.open` for opening file descriptors.) + + +.. function:: fdopen(fd, *args, **kwargs) + + Return an open file object connected to the file descriptor *fd*. This is an + alias of the :func:`open` built-in function and accepts the same arguments. + The only difference is that the first argument of :func:`fdopen` must always + be an integer. + + +.. _os-fd-ops: + +File Descriptor Operations +-------------------------- + +These functions operate on I/O streams referenced using file descriptors. + +File descriptors are small integers corresponding to a file that has been opened +by the current process. For example, standard input is usually file descriptor +0, standard output is 1, and standard error is 2. Further files opened by a +process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" +is slightly deceptive; on Unix platforms, sockets and pipes are also referenced +by file descriptors. + +The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor +associated with a :term:`file object` when required. Note that using the file +descriptor directly will bypass the file object methods, ignoring aspects such +as internal buffering of data. + + +.. function:: close(fd) + + Close file descriptor *fd*. + + .. note:: + + This function is intended for low-level I/O and must be applied to a file + descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file + object" returned by the built-in function :func:`open` or by :func:`popen` or + :func:`fdopen`, use its :meth:`~io.IOBase.close` method. + + +.. function:: closerange(fd_low, fd_high) + + Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), + ignoring errors. Equivalent to (but much faster than):: + + for fd in range(fd_low, fd_high): + try: + os.close(fd) + except OSError: + pass + + +.. function:: copy_file_range(src, dst, count, offset_src=None, offset_dst=None) + + Copy *count* bytes from file descriptor *src*, starting from offset + *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*. + If *offset_src* is None, then *src* is read from the current position; + respectively for *offset_dst*. The files pointed by *src* and *dst* + must reside in the same filesystem, otherwise an :exc:`OSError` is + raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`. + + This copy is done without the additional cost of transferring data + from the kernel to user space and then back into the kernel. Additionally, + some filesystems could implement extra optimizations. The copy is done as if + both files are opened as binary. + + The return value is the amount of bytes copied. This could be less than the + amount requested. + + .. availability:: Linux kernel >= 4.5 or glibc >= 2.27. + + .. versionadded:: 3.8 + + +.. function:: device_encoding(fd) + + Return a string describing the encoding of the device associated with *fd* + if it is connected to a terminal; else return :const:`None`. + + +.. function:: dup(fd) + + Return a duplicate of file descriptor *fd*. The new file descriptor is + :ref:`non-inheritable `. + + On Windows, when duplicating a standard stream (0: stdin, 1: stdout, + 2: stderr), the new file descriptor is :ref:`inheritable + `. + + .. versionchanged:: 3.4 + The new file descriptor is now non-inheritable. + + +.. function:: dup2(fd, fd2, inheritable=True) + + Duplicate file descriptor *fd* to *fd2*, closing the latter first if + necessary. Return *fd2*. The new file descriptor is :ref:`inheritable + ` by default or non-inheritable if *inheritable* + is ``False``. + + .. versionchanged:: 3.4 + Add the optional *inheritable* parameter. + + .. versionchanged:: 3.7 + Return *fd2* on success. Previously, ``None`` was always returned. + + +.. function:: fchmod(fd, mode) + + Change the mode of the file given by *fd* to the numeric *mode*. See the + docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this + is equivalent to ``os.chmod(fd, mode)``. + + .. availability:: Unix. + + +.. function:: fchown(fd, uid, gid) + + Change the owner and group id of the file given by *fd* to the numeric *uid* + and *gid*. To leave one of the ids unchanged, set it to -1. See + :func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid, + gid)``. + + .. availability:: Unix. + + +.. function:: fdatasync(fd) + + Force write of file with filedescriptor *fd* to disk. Does not force update of + metadata. + + .. availability:: Unix. + + .. note:: + This function is not available on MacOS. + + +.. function:: fpathconf(fd, name) + + Return system configuration information relevant to an open file. *name* + specifies the configuration value to retrieve; it may be a string which is the + name of a defined system value; these names are specified in a number of + standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define + additional names as well. The names known to the host operating system are + given in the ``pathconf_names`` dictionary. For configuration variables not + included in that mapping, passing an integer for *name* is also accepted. + + If *name* is a string and is not known, :exc:`ValueError` is raised. If a + specific value for *name* is not supported by the host system, even if it is + included in ``pathconf_names``, an :exc:`OSError` is raised with + :const:`errno.EINVAL` for the error number. + + As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``. + + .. availability:: Unix. + + +.. function:: fstat(fd) + + Get the status of the file descriptor *fd*. Return a :class:`stat_result` + object. + + As of Python 3.3, this is equivalent to ``os.stat(fd)``. + + .. seealso:: + + The :func:`.stat` function. + + +.. function:: fstatvfs(fd) + + Return information about the filesystem containing the file associated with + file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is + equivalent to ``os.statvfs(fd)``. + + .. availability:: Unix. + + +.. function:: fsync(fd) + + Force write of file with filedescriptor *fd* to disk. On Unix, this calls the + native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function. + + If you're starting with a buffered Python :term:`file object` *f*, first do + ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal + buffers associated with *f* are written to disk. + + .. availability:: Unix, Windows. + + +.. function:: ftruncate(fd, length) + + Truncate the file corresponding to file descriptor *fd*, so that it is at + most *length* bytes in size. As of Python 3.3, this is equivalent to + ``os.truncate(fd, length)``. + + .. audit-event:: os.truncate fd,length os.ftruncate + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.5 + Added support for Windows + + +.. function:: get_blocking(fd) + + Get the blocking mode of the file descriptor: ``False`` if the + :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared. + + See also :func:`set_blocking` and :meth:`socket.socket.setblocking`. + + .. availability:: Unix. + + .. versionadded:: 3.5 + + +.. function:: isatty(fd) + + Return ``True`` if the file descriptor *fd* is open and connected to a + tty(-like) device, else ``False``. + + +.. function:: lockf(fd, cmd, len) + + Apply, test or remove a POSIX lock on an open file descriptor. + *fd* is an open file descriptor. + *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`, + :data:`F_ULOCK` or :data:`F_TEST`. + *len* specifies the section of the file to lock. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. data:: F_LOCK + F_TLOCK + F_ULOCK + F_TEST + + Flags that specify what action :func:`lockf` will take. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: lseek(fd, pos, how) + + Set the current position of file descriptor *fd* to position *pos*, modified + by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the + beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the + current position; :const:`SEEK_END` or ``2`` to set it relative to the end of + the file. Return the new cursor position in bytes, starting from the beginning. + + +.. data:: SEEK_SET + SEEK_CUR + SEEK_END + + Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, + respectively. + + .. versionadded:: 3.3 + Some operating systems could support additional values, like + :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`. + + +.. function:: open(path, flags, mode=0o777, *, dir_fd=None) + + Open the file *path* and set various flags according to *flags* and possibly + its mode according to *mode*. When computing *mode*, the current umask value + is first masked out. Return the file descriptor for the newly opened file. + The new file descriptor is :ref:`non-inheritable `. + + For a description of the flag and mode values, see the C run-time documentation; + flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in + the :mod:`os` module. In particular, on Windows adding + :const:`O_BINARY` is needed to open files in binary mode. + + This function can support :ref:`paths relative to directory descriptors + ` with the *dir_fd* parameter. + + .. audit-event:: open path,mode,flags os.open + + .. versionchanged:: 3.4 + The new file descriptor is now non-inheritable. + + .. note:: + + This function is intended for low-level I/O. For normal usage, use the + built-in function :func:`open`, which returns a :term:`file object` with + :meth:`~file.read` and :meth:`~file.write` methods (and many more). To + wrap a file descriptor in a file object, use :func:`fdopen`. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.5 + If the system call is interrupted and the signal handler does not raise an + exception, the function now retries the system call instead of raising an + :exc:`InterruptedError` exception (see :pep:`475` for the rationale). + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + +The following constants are options for the *flags* parameter to the +:func:`~os.open` function. They can be combined using the bitwise OR operator +``|``. Some of them are not available on all platforms. For descriptions of +their availability and use, consult the :manpage:`open(2)` manual page on Unix +or `the MSDN `_ on Windows. + + +.. data:: O_RDONLY + O_WRONLY + O_RDWR + O_APPEND + O_CREAT + O_EXCL + O_TRUNC + + The above constants are available on Unix and Windows. + + +.. data:: O_DSYNC + O_RSYNC + O_SYNC + O_NDELAY + O_NONBLOCK + O_NOCTTY + O_CLOEXEC + + The above constants are only available on Unix. + + .. versionchanged:: 3.3 + Add :data:`O_CLOEXEC` constant. + +.. data:: O_BINARY + O_NOINHERIT + O_SHORT_LIVED + O_TEMPORARY + O_RANDOM + O_SEQUENTIAL + O_TEXT + + The above constants are only available on Windows. + + +.. data:: O_ASYNC + O_DIRECT + O_DIRECTORY + O_NOFOLLOW + O_NOATIME + O_PATH + O_TMPFILE + O_SHLOCK + O_EXLOCK + + The above constants are extensions and not present if they are not defined by + the C library. + + .. versionchanged:: 3.4 + Add :data:`O_PATH` on systems that support it. + Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11 + or newer. + + +.. function:: openpty() + + .. index:: module: pty + + Open a new pseudo-terminal pair. Return a pair of file descriptors + ``(master, slave)`` for the pty and the tty, respectively. The new file + descriptors are :ref:`non-inheritable `. For a (slightly) more + portable approach, use the :mod:`pty` module. + + .. availability:: some flavors of Unix. + + .. versionchanged:: 3.4 + The new file descriptors are now non-inheritable. + + +.. function:: pipe() + + Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for + reading and writing, respectively. The new file descriptor is + :ref:`non-inheritable `. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.4 + The new file descriptors are now non-inheritable. + + +.. function:: pipe2(flags) + + Create a pipe with *flags* set atomically. + *flags* can be constructed by ORing together one or more of these values: + :data:`O_NONBLOCK`, :data:`O_CLOEXEC`. + Return a pair of file descriptors ``(r, w)`` usable for reading and writing, + respectively. + + .. availability:: some flavors of Unix. + + .. versionadded:: 3.3 + + +.. function:: posix_fallocate(fd, offset, len) + + Ensures that enough disk space is allocated for the file specified by *fd* + starting from *offset* and continuing for *len* bytes. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: posix_fadvise(fd, offset, len, advice) + + Announces an intention to access data in a specific pattern thus allowing + the kernel to make optimizations. + The advice applies to the region of the file specified by *fd* starting at + *offset* and continuing for *len* bytes. + *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`, + :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`, + :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. data:: POSIX_FADV_NORMAL + POSIX_FADV_SEQUENTIAL + POSIX_FADV_RANDOM + POSIX_FADV_NOREUSE + POSIX_FADV_WILLNEED + POSIX_FADV_DONTNEED + + Flags that can be used in *advice* in :func:`posix_fadvise` that specify + the access pattern that is likely to be used. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: pread(fd, n, offset) + + Read at most *n* bytes from file descriptor *fd* at a position of *offset*, + leaving the file offset unchanged. + + Return a bytestring containing the bytes read. If the end of the file + referred to by *fd* has been reached, an empty bytes object is returned. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: preadv(fd, buffers, offset, flags=0) + + Read from a file descriptor *fd* at a position of *offset* into mutable + :term:`bytes-like objects ` *buffers*, leaving the file + offset unchanged. Transfer data into each buffer until it is full and then + move on to the next buffer in the sequence to hold the rest of the data. + + The flags argument contains a bitwise OR of zero or more of the following + flags: + + - :data:`RWF_HIPRI` + - :data:`RWF_NOWAIT` + + Return the total number of bytes actually read which can be less than the + total capacity of all the objects. + + The operating system may set a limit (:func:`sysconf` value + ``'SC_IOV_MAX'``) on the number of buffers that can be used. + + Combine the functionality of :func:`os.readv` and :func:`os.pread`. + + .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, + OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer. + + .. versionadded:: 3.7 + + +.. data:: RWF_NOWAIT + + Do not wait for data which is not immediately available. If this flag is + specified, the system call will return instantly if it would have to read + data from the backing storage or wait for a lock. + + If some data was successfully read, it will return the number of bytes read. + If no bytes were read, it will return ``-1`` and set errno to + :data:`errno.EAGAIN`. + + .. availability:: Linux 4.14 and newer. + + .. versionadded:: 3.7 + + +.. data:: RWF_HIPRI + + High priority read/write. Allows block-based filesystems to use polling + of the device, which provides lower latency, but may use additional + resources. + + Currently, on Linux, this feature is usable only on a file descriptor opened + using the :data:`O_DIRECT` flag. + + .. availability:: Linux 4.6 and newer. + + .. versionadded:: 3.7 + + +.. function:: pwrite(fd, str, offset) + + Write the bytestring in *str* to file descriptor *fd* at position of + *offset*, leaving the file offset unchanged. + + Return the number of bytes actually written. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: pwritev(fd, buffers, offset, flags=0) + + Write the *buffers* contents to file descriptor *fd* at a offset *offset*, + leaving the file offset unchanged. *buffers* must be a sequence of + :term:`bytes-like objects `. Buffers are processed in + array order. Entire contents of the first buffer is written before + proceeding to the second, and so on. + + The flags argument contains a bitwise OR of zero or more of the following + flags: + + - :data:`RWF_DSYNC` + - :data:`RWF_SYNC` + + Return the total number of bytes actually written. + + The operating system may set a limit (:func:`sysconf` value + ``'SC_IOV_MAX'``) on the number of buffers that can be used. + + Combine the functionality of :func:`os.writev` and :func:`os.pwrite`. + + .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, + OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer. + + .. versionadded:: 3.7 + + +.. data:: RWF_DSYNC + + Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This + flag effect applies only to the data range written by the system call. + + .. availability:: Linux 4.7 and newer. + + .. versionadded:: 3.7 + + +.. data:: RWF_SYNC + + Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This + flag effect applies only to the data range written by the system call. + + .. availability:: Linux 4.7 and newer. + + .. versionadded:: 3.7 + + +.. function:: read(fd, n) + + Read at most *n* bytes from file descriptor *fd*. + + Return a bytestring containing the bytes read. If the end of the file + referred to by *fd* has been reached, an empty bytes object is returned. + + .. note:: + + This function is intended for low-level I/O and must be applied to a file + descriptor as returned by :func:`os.open` or :func:`pipe`. To read a + "file object" returned by the built-in function :func:`open` or by + :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its + :meth:`~file.read` or :meth:`~file.readline` methods. + + .. versionchanged:: 3.5 + If the system call is interrupted and the signal handler does not raise an + exception, the function now retries the system call instead of raising an + :exc:`InterruptedError` exception (see :pep:`475` for the rationale). + + +.. function:: sendfile(out_fd, in_fd, offset, count) + sendfile(out_fd, in_fd, offset, count, [headers], [trailers], flags=0) + + Copy *count* bytes from file descriptor *in_fd* to file descriptor *out_fd* + starting at *offset*. + Return the number of bytes sent. When EOF is reached return ``0``. + + The first function notation is supported by all platforms that define + :func:`sendfile`. + + On Linux, if *offset* is given as ``None``, the bytes are read from the + current position of *in_fd* and the position of *in_fd* is updated. + + The second case may be used on Mac OS X and FreeBSD where *headers* and + *trailers* are arbitrary sequences of buffers that are written before and + after the data from *in_fd* is written. It returns the same as the first case. + + On Mac OS X and FreeBSD, a value of ``0`` for *count* specifies to send until + the end of *in_fd* is reached. + + All platforms support sockets as *out_fd* file descriptor, and some platforms + allow other types (e.g. regular file, pipe) as well. + + Cross-platform applications should not use *headers*, *trailers* and *flags* + arguments. + + .. availability:: Unix. + + .. note:: + + For a higher-level wrapper of :func:`sendfile`, see + :meth:`socket.socket.sendfile`. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.9 + Parameters *out* and *in* was renamed to *out_fd* and *in_fd*. + + +.. function:: set_blocking(fd, blocking) + + Set the blocking mode of the specified file descriptor. Set the + :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise. + + See also :func:`get_blocking` and :meth:`socket.socket.setblocking`. + + .. availability:: Unix. + + .. versionadded:: 3.5 + + +.. data:: SF_NODISKIO + SF_MNOWAIT + SF_SYNC + + Parameters to the :func:`sendfile` function, if the implementation supports + them. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: readv(fd, buffers) + + Read from a file descriptor *fd* into a number of mutable :term:`bytes-like + objects ` *buffers*. Transfer data into each buffer until + it is full and then move on to the next buffer in the sequence to hold the + rest of the data. + + Return the total number of bytes actually read which can be less than the + total capacity of all the objects. + + The operating system may set a limit (:func:`sysconf` value + ``'SC_IOV_MAX'``) on the number of buffers that can be used. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: tcgetpgrp(fd) + + Return the process group associated with the terminal given by *fd* (an open + file descriptor as returned by :func:`os.open`). + + .. availability:: Unix. + + +.. function:: tcsetpgrp(fd, pg) + + Set the process group associated with the terminal given by *fd* (an open file + descriptor as returned by :func:`os.open`) to *pg*. + + .. availability:: Unix. + + +.. function:: ttyname(fd) + + Return a string which specifies the terminal device associated with + file descriptor *fd*. If *fd* is not associated with a terminal device, an + exception is raised. + + .. availability:: Unix. + + +.. function:: write(fd, str) + + Write the bytestring in *str* to file descriptor *fd*. + + Return the number of bytes actually written. + + .. note:: + + This function is intended for low-level I/O and must be applied to a file + descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file + object" returned by the built-in function :func:`open` or by :func:`popen` or + :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its + :meth:`~file.write` method. + + .. versionchanged:: 3.5 + If the system call is interrupted and the signal handler does not raise an + exception, the function now retries the system call instead of raising an + :exc:`InterruptedError` exception (see :pep:`475` for the rationale). + + +.. function:: writev(fd, buffers) + + Write the contents of *buffers* to file descriptor *fd*. *buffers* must be + a sequence of :term:`bytes-like objects `. Buffers are + processed in array order. Entire contents of the first buffer is written + before proceeding to the second, and so on. + + Returns the total number of bytes actually written. + + The operating system may set a limit (:func:`sysconf` value + ``'SC_IOV_MAX'``) on the number of buffers that can be used. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. _terminal-size: + +Querying the size of a terminal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.3 + +.. function:: get_terminal_size(fd=STDOUT_FILENO) + + Return the size of the terminal window as ``(columns, lines)``, + tuple of type :class:`terminal_size`. + + The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard + output) specifies which file descriptor should be queried. + + If the file descriptor is not connected to a terminal, an :exc:`OSError` + is raised. + + :func:`shutil.get_terminal_size` is the high-level function which + should normally be used, ``os.get_terminal_size`` is the low-level + implementation. + + .. availability:: Unix, Windows. + +.. class:: terminal_size + + A subclass of tuple, holding ``(columns, lines)`` of the terminal window size. + + .. attribute:: columns + + Width of the terminal window in characters. + + .. attribute:: lines + + Height of the terminal window in characters. + + +.. _fd_inheritance: + +Inheritance of File Descriptors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.4 + +A file descriptor has an "inheritable" flag which indicates if the file descriptor +can be inherited by child processes. Since Python 3.4, file descriptors +created by Python are non-inheritable by default. + +On UNIX, non-inheritable file descriptors are closed in child processes at the +execution of a new program, other file descriptors are inherited. + +On Windows, non-inheritable handles and file descriptors are closed in child +processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout +and stderr), which are always inherited. Using :func:`spawn\* ` functions, +all inheritable handles and all inheritable file descriptors are inherited. +Using the :mod:`subprocess` module, all file descriptors except standard +streams are closed, and inheritable handles are only inherited if the +*close_fds* parameter is ``False``. + +.. function:: get_inheritable(fd) + + Get the "inheritable" flag of the specified file descriptor (a boolean). + +.. function:: set_inheritable(fd, inheritable) + + Set the "inheritable" flag of the specified file descriptor. + +.. function:: get_handle_inheritable(handle) + + Get the "inheritable" flag of the specified handle (a boolean). + + .. availability:: Windows. + +.. function:: set_handle_inheritable(handle, inheritable) + + Set the "inheritable" flag of the specified handle. + + .. availability:: Windows. + + +.. _os-file-dir: + +Files and Directories +--------------------- + +On some Unix platforms, many of these functions support one or more of these +features: + +.. _path_fd: + +* **specifying a file descriptor:** + Normally the *path* argument provided to functions in the :mod:`os` module + must be a string specifying a file path. However, some functions now + alternatively accept an open file descriptor for their *path* argument. + The function will then operate on the file referred to by the descriptor. + (For POSIX systems, Python will call the variant of the function prefixed + with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).) + + You can check whether or not *path* can be specified as a file descriptor + for a particular function on your platform using :data:`os.supports_fd`. + If this functionality is unavailable, using it will raise a + :exc:`NotImplementedError`. + + If the function also supports *dir_fd* or *follow_symlinks* arguments, it's + an error to specify one of those when supplying *path* as a file descriptor. + +.. _dir_fd: + +* **paths relative to directory descriptors:** If *dir_fd* is not ``None``, it + should be a file descriptor referring to a directory, and the path to operate + on should be relative; path will then be relative to that directory. If the + path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call + the variant of the function with an ``at`` suffix and possibly prefixed with + ``f`` (e.g. call ``faccessat`` instead of ``access``). + + You can check whether or not *dir_fd* is supported for a particular function + on your platform using :data:`os.supports_dir_fd`. If it's unavailable, + using it will raise a :exc:`NotImplementedError`. + +.. _follow_symlinks: + +* **not following symlinks:** If *follow_symlinks* is + ``False``, and the last element of the path to operate on is a symbolic link, + the function will operate on the symbolic link itself rather than the file + pointed to by the link. (For POSIX systems, Python will call the ``l...`` + variant of the function.) + + You can check whether or not *follow_symlinks* is supported for a particular + function on your platform using :data:`os.supports_follow_symlinks`. + If it's unavailable, using it will raise a :exc:`NotImplementedError`. + + + +.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True) + + Use the real uid/gid to test for access to *path*. Note that most operations + will use the effective uid/gid, therefore this routine can be used in a + suid/sgid environment to test if the invoking user has the specified access to + *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it + can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and + :const:`X_OK` to test permissions. Return :const:`True` if access is allowed, + :const:`False` if not. See the Unix man page :manpage:`access(2)` for more + information. + + This function can support specifying :ref:`paths relative to directory + descriptors ` and :ref:`not following symlinks `. + + If *effective_ids* is ``True``, :func:`access` will perform its access + checks using the effective uid/gid instead of the real uid/gid. + *effective_ids* may not be supported on your platform; you can check whether + or not it is available using :data:`os.supports_effective_ids`. If it is + unavailable, using it will raise a :exc:`NotImplementedError`. + + .. note:: + + Using :func:`access` to check if a user is authorized to e.g. open a file + before actually doing so using :func:`open` creates a security hole, + because the user might exploit the short time interval between checking + and opening the file to manipulate it. It's preferable to use :term:`EAFP` + techniques. For example:: + + if os.access("myfile", os.R_OK): + with open("myfile") as fp: + return fp.read() + return "some default data" + + is better written as:: + + try: + fp = open("myfile") + except PermissionError: + return "some default data" + else: + with fp: + return fp.read() + + .. note:: + + I/O operations may fail even when :func:`access` indicates that they would + succeed, particularly for operations on network filesystems which may have + permissions semantics beyond the usual POSIX permission-bit model. + + .. versionchanged:: 3.3 + Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. data:: F_OK + R_OK + W_OK + X_OK + + Values to pass as the *mode* parameter of :func:`access` to test the + existence, readability, writability and executability of *path*, + respectively. + + +.. function:: chdir(path) + + .. index:: single: directory; changing + + Change the current working directory to *path*. + + This function can support :ref:`specifying a file descriptor `. The + descriptor must refer to an opened directory, not an open file. + + This function can raise :exc:`OSError` and subclasses such as + :exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`. + + .. versionadded:: 3.3 + Added support for specifying *path* as a file descriptor + on some platforms. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: chflags(path, flags, *, follow_symlinks=True) + + Set the flags of *path* to the numeric *flags*. *flags* may take a combination + (bitwise OR) of the following values (as defined in the :mod:`stat` module): + + * :data:`stat.UF_NODUMP` + * :data:`stat.UF_IMMUTABLE` + * :data:`stat.UF_APPEND` + * :data:`stat.UF_OPAQUE` + * :data:`stat.UF_NOUNLINK` + * :data:`stat.UF_COMPRESSED` + * :data:`stat.UF_HIDDEN` + * :data:`stat.SF_ARCHIVED` + * :data:`stat.SF_IMMUTABLE` + * :data:`stat.SF_APPEND` + * :data:`stat.SF_NOUNLINK` + * :data:`stat.SF_SNAPSHOT` + + This function can support :ref:`not following symlinks `. + + .. availability:: Unix. + + .. versionadded:: 3.3 + The *follow_symlinks* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True) + + Change the mode of *path* to the numeric *mode*. *mode* may take one of the + following values (as defined in the :mod:`stat` module) or bitwise ORed + combinations of them: + + * :data:`stat.S_ISUID` + * :data:`stat.S_ISGID` + * :data:`stat.S_ENFMT` + * :data:`stat.S_ISVTX` + * :data:`stat.S_IREAD` + * :data:`stat.S_IWRITE` + * :data:`stat.S_IEXEC` + * :data:`stat.S_IRWXU` + * :data:`stat.S_IRUSR` + * :data:`stat.S_IWUSR` + * :data:`stat.S_IXUSR` + * :data:`stat.S_IRWXG` + * :data:`stat.S_IRGRP` + * :data:`stat.S_IWGRP` + * :data:`stat.S_IXGRP` + * :data:`stat.S_IRWXO` + * :data:`stat.S_IROTH` + * :data:`stat.S_IWOTH` + * :data:`stat.S_IXOTH` + + This function can support :ref:`specifying a file descriptor `, + :ref:`paths relative to directory descriptors ` and :ref:`not + following symlinks `. + + .. note:: + + Although Windows supports :func:`chmod`, you can only set the file's + read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` + constants or a corresponding integer value). All other bits are ignored. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor, + and the *dir_fd* and *follow_symlinks* arguments. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) + + Change the owner and group id of *path* to the numeric *uid* and *gid*. To + leave one of the ids unchanged, set it to -1. + + This function can support :ref:`specifying a file descriptor `, + :ref:`paths relative to directory descriptors ` and :ref:`not + following symlinks `. + + See :func:`shutil.chown` for a higher-level function that accepts names in + addition to numeric ids. + + .. availability:: Unix. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor, + and the *dir_fd* and *follow_symlinks* arguments. + + .. versionchanged:: 3.6 + Supports a :term:`path-like object`. + + +.. function:: chroot(path) + + Change the root directory of the current process to *path*. + + .. availability:: Unix. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: fchdir(fd) + + Change the current working directory to the directory represented by the file + descriptor *fd*. The descriptor must refer to an opened directory, not an + open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``. + + .. availability:: Unix. + + +.. function:: getcwd() + + Return a string representing the current working directory. + + +.. function:: getcwdb() + + Return a bytestring representing the current working directory. + + .. versionchanged:: 3.8 + The function now uses the UTF-8 encoding on Windows, rather than the ANSI + code page: see :pep:`529` for the rationale. The function is no longer + deprecated on Windows. + + +.. function:: lchflags(path, flags) + + Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do + not follow symbolic links. As of Python 3.3, this is equivalent to + ``os.chflags(path, flags, follow_symlinks=False)``. + + .. availability:: Unix. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: lchmod(path, mode) + + Change the mode of *path* to the numeric *mode*. If path is a symlink, this + affects the symlink rather than the target. See the docs for :func:`chmod` + for possible values of *mode*. As of Python 3.3, this is equivalent to + ``os.chmod(path, mode, follow_symlinks=False)``. + + .. availability:: Unix. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + +.. function:: lchown(path, uid, gid) + + Change the owner and group id of *path* to the numeric *uid* and *gid*. This + function will not follow symbolic links. As of Python 3.3, this is equivalent + to ``os.chown(path, uid, gid, follow_symlinks=False)``. + + .. availability:: Unix. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True) + + Create a hard link pointing to *src* named *dst*. + + This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to + supply :ref:`paths relative to directory descriptors `, and :ref:`not + following symlinks `. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.2 + Added Windows support. + + .. versionadded:: 3.3 + Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + + +.. function:: listdir(path='.') + + Return a list containing the names of the entries in the directory given by + *path*. The list is in arbitrary order, and does not include the special + entries ``'.'`` and ``'..'`` even if they are present in the directory. + + *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` + (directly or indirectly through the :class:`PathLike` interface), + the filenames returned will also be of type ``bytes``; + in all other circumstances, they will be of type ``str``. + + This function can also support :ref:`specifying a file descriptor + `; the file descriptor must refer to a directory. + + .. audit-event:: os.listdir path os.listdir + + .. note:: + To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`. + + .. seealso:: + + The :func:`scandir` function returns directory entries along with + file attribute information, giving better performance for many + common use cases. + + .. versionchanged:: 3.2 + The *path* parameter became optional. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: lstat(path, \*, dir_fd=None) + + Perform the equivalent of an :c:func:`lstat` system call on the given path. + Similar to :func:`~os.stat`, but does not follow symbolic links. Return a + :class:`stat_result` object. + + On platforms that do not support symbolic links, this is an alias for + :func:`~os.stat`. + + As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd, + follow_symlinks=False)``. + + This function can also support :ref:`paths relative to directory descriptors + `. + + .. seealso:: + + The :func:`.stat` function. + + .. versionchanged:: 3.2 + Added support for Windows 6.0 (Vista) symbolic links. + + .. versionchanged:: 3.3 + Added the *dir_fd* parameter. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + + .. versionchanged:: 3.8 + On Windows, now opens reparse points that represent another path + (name surrogates), including symbolic links and directory junctions. + Other kinds of reparse points are resolved by the operating system as + for :func:`~os.stat`. + + +.. function:: mkdir(path, mode=0o777, *, dir_fd=None) + + Create a directory named *path* with numeric mode *mode*. + + If the directory already exists, :exc:`FileExistsError` is raised. + + .. _mkdir_modebits: + + On some systems, *mode* is ignored. Where it is used, the current umask + value is first masked out. If bits other than the last 9 (i.e. the last 3 + digits of the octal representation of the *mode*) are set, their meaning is + platform-dependent. On some platforms, they are ignored and you should call + :func:`chmod` explicitly to set them. + + This function can also support :ref:`paths relative to directory descriptors + `. + + It is also possible to create temporary directories; see the + :mod:`tempfile` module's :func:`tempfile.mkdtemp` function. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: makedirs(name, mode=0o777, exist_ok=False) + + .. index:: + single: directory; creating + single: UNC paths; and os.makedirs() + + Recursive directory creation function. Like :func:`mkdir`, but makes all + intermediate-level directories needed to contain the leaf directory. + + The *mode* parameter is passed to :func:`mkdir` for creating the leaf + directory; see :ref:`the mkdir() description ` for how it + is interpreted. To set the file permission bits of any newly-created parent + directories you can set the umask before invoking :func:`makedirs`. The + file permission bits of existing parent directories are not changed. + + If *exist_ok* is ``False`` (the default), an :exc:`FileExistsError` is + raised if the target directory already exists. + + .. note:: + + :func:`makedirs` will become confused if the path elements to create + include :data:`pardir` (eg. ".." on UNIX systems). + + This function handles UNC paths correctly. + + .. versionadded:: 3.2 + The *exist_ok* parameter. + + .. versionchanged:: 3.4.1 + + Before Python 3.4.1, if *exist_ok* was ``True`` and the directory existed, + :func:`makedirs` would still raise an error if *mode* did not match the + mode of the existing directory. Since this behavior was impossible to + implement safely, it was removed in Python 3.4.1. See :issue:`21082`. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. versionchanged:: 3.7 + The *mode* argument no longer affects the file permission bits of + newly-created intermediate-level directories. + + +.. function:: mkfifo(path, mode=0o666, *, dir_fd=None) + + Create a FIFO (a named pipe) named *path* with numeric mode *mode*. + The current umask value is first masked out from the mode. + + This function can also support :ref:`paths relative to directory descriptors + `. + + FIFOs are pipes that can be accessed like regular files. FIFOs exist until they + are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as + rendezvous between "client" and "server" type processes: the server opens the + FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo` + doesn't open the FIFO --- it just creates the rendezvous point. + + .. availability:: Unix. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: mknod(path, mode=0o600, device=0, *, dir_fd=None) + + Create a filesystem node (file, device special file or named pipe) named + *path*. *mode* specifies both the permissions to use and the type of node + to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, + ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are + available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``, + *device* defines the newly created device special file (probably using + :func:`os.makedev`), otherwise it is ignored. + + This function can also support :ref:`paths relative to directory descriptors + `. + + .. availability:: Unix. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: major(device) + + Extract the device major number from a raw device number (usually the + :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). + + +.. function:: minor(device) + + Extract the device minor number from a raw device number (usually the + :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). + + +.. function:: makedev(major, minor) + + Compose a raw device number from the major and minor device numbers. + + +.. function:: pathconf(path, name) + + Return system configuration information relevant to a named file. *name* + specifies the configuration value to retrieve; it may be a string which is the + name of a defined system value; these names are specified in a number of + standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define + additional names as well. The names known to the host operating system are + given in the ``pathconf_names`` dictionary. For configuration variables not + included in that mapping, passing an integer for *name* is also accepted. + + If *name* is a string and is not known, :exc:`ValueError` is raised. If a + specific value for *name* is not supported by the host system, even if it is + included in ``pathconf_names``, an :exc:`OSError` is raised with + :const:`errno.EINVAL` for the error number. + + This function can support :ref:`specifying a file descriptor + `. + + .. availability:: Unix. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. data:: pathconf_names + + Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to + the integer values defined for those names by the host operating system. This + can be used to determine the set of names known to the system. + + .. availability:: Unix. + + +.. function:: readlink(path, *, dir_fd=None) + + Return a string representing the path to which the symbolic link points. The + result may be either an absolute or relative pathname; if it is relative, it + may be converted to an absolute pathname using + ``os.path.join(os.path.dirname(path), result)``. + + If the *path* is a string object (directly or indirectly through a + :class:`PathLike` interface), the result will also be a string object, + and the call may raise a UnicodeDecodeError. If the *path* is a bytes + object (direct or indirectly), the result will be a bytes object. + + This function can also support :ref:`paths relative to directory descriptors + `. + + When trying to resolve a path that may contain links, use + :func:`~os.path.realpath` to properly handle recursion and platform + differences. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.2 + Added support for Windows 6.0 (Vista) symbolic links. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` on Unix. + + .. versionchanged:: 3.8 + Accepts a :term:`path-like object` and a bytes object on Windows. + + .. versionchanged:: 3.8 + Added support for directory junctions, and changed to return the + substitution path (which typically includes ``\\?\`` prefix) rather + than the optional "print name" field that was previously returned. + +.. function:: remove(path, *, dir_fd=None) + + Remove (delete) the file *path*. If *path* is a directory, an + :exc:`IsADirectoryError` is raised. Use :func:`rmdir` to remove directories. + + This function can support :ref:`paths relative to directory descriptors + `. + + On Windows, attempting to remove a file that is in use causes an exception to + be raised; on Unix, the directory entry is removed but the storage allocated + to the file is not made available until the original file is no longer in use. + + This function is semantically identical to :func:`unlink`. + + .. versionadded:: 3.3 + The *dir_fd* argument. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: removedirs(name) + + .. index:: single: directory; deleting + + Remove directories recursively. Works like :func:`rmdir` except that, if the + leaf directory is successfully removed, :func:`removedirs` tries to + successively remove every parent directory mentioned in *path* until an error + is raised (which is ignored, because it generally means that a parent directory + is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove + the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if + they are empty. Raises :exc:`OSError` if the leaf directory could not be + successfully removed. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) + + Rename the file or directory *src* to *dst*. If *dst* exists, the operation + will fail with an :exc:`OSError` subclass in a number of cases: + + On Windows, if *dst* exists a :exc:`FileExistsError` is always raised. + + On Unix, if *src* is a file and *dst* is a directory or vice-versa, an + :exc:`IsADirectoryError` or a :exc:`NotADirectoryError` will be raised + respectively. If both are directories and *dst* is empty, *dst* will be + silently replaced. If *dst* is a non-empty directory, an :exc:`OSError` + is raised. If both are files, *dst* it will be replaced silently if the user + has permission. The operation may fail on some Unix flavors if *src* and + *dst* are on different filesystems. If successful, the renaming will be an + atomic operation (this is a POSIX requirement). + + This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to + supply :ref:`paths relative to directory descriptors `. + + If you want cross-platform overwriting of the destination, use :func:`replace`. + + .. versionadded:: 3.3 + The *src_dir_fd* and *dst_dir_fd* arguments. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + + +.. function:: renames(old, new) + + Recursive directory or file renaming function. Works like :func:`rename`, except + creation of any intermediate directories needed to make the new pathname good is + attempted first. After the rename, directories corresponding to rightmost path + segments of the old name will be pruned away using :func:`removedirs`. + + .. note:: + + This function can fail with the new directory structure made if you lack + permissions needed to remove the leaf directory or file. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *old* and *new*. + + +.. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None) + + Rename the file or directory *src* to *dst*. If *dst* is a directory, + :exc:`OSError` will be raised. If *dst* exists and is a file, it will + be replaced silently if the user has permission. The operation may fail + if *src* and *dst* are on different filesystems. If successful, + the renaming will be an atomic operation (this is a POSIX requirement). + + This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to + supply :ref:`paths relative to directory descriptors `. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + + +.. function:: rmdir(path, *, dir_fd=None) + + Remove (delete) the directory *path*. If the directory does not exist or is + not empty, an :exc:`FileNotFoundError` or an :exc:`OSError` is raised + respectively. In order to remove whole directory trees, + :func:`shutil.rmtree` can be used. + + This function can support :ref:`paths relative to directory descriptors + `. + + .. versionadded:: 3.3 + The *dir_fd* parameter. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: scandir(path='.') + + Return an iterator of :class:`os.DirEntry` objects corresponding to the + entries in the directory given by *path*. The entries are yielded in + arbitrary order, and the special entries ``'.'`` and ``'..'`` are not + included. + + Using :func:`scandir` instead of :func:`listdir` can significantly + increase the performance of code that also needs file type or file + attribute information, because :class:`os.DirEntry` objects expose this + information if the operating system provides it when scanning a directory. + All :class:`os.DirEntry` methods may perform a system call, but + :func:`~os.DirEntry.is_dir` and :func:`~os.DirEntry.is_file` usually only + require a system call for symbolic links; :func:`os.DirEntry.stat` + always requires a system call on Unix but only requires one for + symbolic links on Windows. + + *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` + (directly or indirectly through the :class:`PathLike` interface), + the type of the :attr:`~os.DirEntry.name` and :attr:`~os.DirEntry.path` + attributes of each :class:`os.DirEntry` will be ``bytes``; in all other + circumstances, they will be of type ``str``. + + This function can also support :ref:`specifying a file descriptor + `; the file descriptor must refer to a directory. + + .. audit-event:: os.scandir path os.scandir + + The :func:`scandir` iterator supports the :term:`context manager` protocol + and has the following method: + + .. method:: scandir.close() + + Close the iterator and free acquired resources. + + This is called automatically when the iterator is exhausted or garbage + collected, or when an error happens during iterating. However it + is advisable to call it explicitly or use the :keyword:`with` + statement. + + .. versionadded:: 3.6 + + The following example shows a simple use of :func:`scandir` to display all + the files (excluding directories) in the given *path* that don't start with + ``'.'``. The ``entry.is_file()`` call will generally not make an additional + system call:: + + with os.scandir(path) as it: + for entry in it: + if not entry.name.startswith('.') and entry.is_file(): + print(entry.name) + + .. note:: + + On Unix-based systems, :func:`scandir` uses the system's + `opendir() `_ + and + `readdir() `_ + functions. On Windows, it uses the Win32 + `FindFirstFileW `_ + and + `FindNextFileW `_ + functions. + + .. versionadded:: 3.5 + + .. versionadded:: 3.6 + Added support for the :term:`context manager` protocol and the + :func:`~scandir.close()` method. If a :func:`scandir` iterator is neither + exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted + in its destructor. + + The function accepts a :term:`path-like object`. + + .. versionchanged:: 3.7 + Added support for :ref:`file descriptors ` on Unix. + + +.. class:: DirEntry + + Object yielded by :func:`scandir` to expose the file path and other file + attributes of a directory entry. + + :func:`scandir` will provide as much of this information as possible without + making additional system calls. When a ``stat()`` or ``lstat()`` system call + is made, the ``os.DirEntry`` object will cache the result. + + ``os.DirEntry`` instances are not intended to be stored in long-lived data + structures; if you know the file metadata has changed or if a long time has + elapsed since calling :func:`scandir`, call ``os.stat(entry.path)`` to fetch + up-to-date information. + + Because the ``os.DirEntry`` methods can make operating system calls, they may + also raise :exc:`OSError`. If you need very fine-grained + control over errors, you can catch :exc:`OSError` when calling one of the + ``os.DirEntry`` methods and handle as appropriate. + + To be directly usable as a :term:`path-like object`, ``os.DirEntry`` + implements the :class:`PathLike` interface. + + Attributes and methods on a ``os.DirEntry`` instance are as follows: + + .. attribute:: name + + The entry's base filename, relative to the :func:`scandir` *path* + argument. + + The :attr:`name` attribute will be ``bytes`` if the :func:`scandir` + *path* argument is of type ``bytes`` and ``str`` otherwise. Use + :func:`~os.fsdecode` to decode byte filenames. + + .. attribute:: path + + The entry's full path name: equivalent to ``os.path.join(scandir_path, + entry.name)`` where *scandir_path* is the :func:`scandir` *path* + argument. The path is only absolute if the :func:`scandir` *path* + argument was absolute. If the :func:`scandir` *path* + argument was a :ref:`file descriptor `, the :attr:`path` + attribute is the same as the :attr:`name` attribute. + + The :attr:`path` attribute will be ``bytes`` if the :func:`scandir` + *path* argument is of type ``bytes`` and ``str`` otherwise. Use + :func:`~os.fsdecode` to decode byte filenames. + + .. method:: inode() + + Return the inode number of the entry. + + The result is cached on the ``os.DirEntry`` object. Use + ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date + information. + + On the first, uncached call, a system call is required on Windows but + not on Unix. + + .. method:: is_dir(\*, follow_symlinks=True) + + Return ``True`` if this entry is a directory or a symbolic link pointing + to a directory; return ``False`` if the entry is or points to any other + kind of file, or if it doesn't exist anymore. + + If *follow_symlinks* is ``False``, return ``True`` only if this entry + is a directory (without following symlinks); return ``False`` if the + entry is any other kind of file or if it doesn't exist anymore. + + The result is cached on the ``os.DirEntry`` object, with a separate cache + for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` along + with :func:`stat.S_ISDIR` to fetch up-to-date information. + + On the first, uncached call, no system call is required in most cases. + Specifically, for non-symlinks, neither Windows or Unix require a system + call, except on certain Unix file systems, such as network file systems, + that return ``dirent.d_type == DT_UNKNOWN``. If the entry is a symlink, + a system call will be required to follow the symlink unless + *follow_symlinks* is ``False``. + + This method can raise :exc:`OSError`, such as :exc:`PermissionError`, + but :exc:`FileNotFoundError` is caught and not raised. + + .. method:: is_file(\*, follow_symlinks=True) + + Return ``True`` if this entry is a file or a symbolic link pointing to a + file; return ``False`` if the entry is or points to a directory or other + non-file entry, or if it doesn't exist anymore. + + If *follow_symlinks* is ``False``, return ``True`` only if this entry + is a file (without following symlinks); return ``False`` if the entry is + a directory or other non-file entry, or if it doesn't exist anymore. + + The result is cached on the ``os.DirEntry`` object. Caching, system calls + made, and exceptions raised are as per :func:`~os.DirEntry.is_dir`. + + .. method:: is_symlink() + + Return ``True`` if this entry is a symbolic link (even if broken); + return ``False`` if the entry points to a directory or any kind of file, + or if it doesn't exist anymore. + + The result is cached on the ``os.DirEntry`` object. Call + :func:`os.path.islink` to fetch up-to-date information. + + On the first, uncached call, no system call is required in most cases. + Specifically, neither Windows or Unix require a system call, except on + certain Unix file systems, such as network file systems, that return + ``dirent.d_type == DT_UNKNOWN``. + + This method can raise :exc:`OSError`, such as :exc:`PermissionError`, + but :exc:`FileNotFoundError` is caught and not raised. + + .. method:: stat(\*, follow_symlinks=True) + + Return a :class:`stat_result` object for this entry. This method + follows symbolic links by default; to stat a symbolic link add the + ``follow_symlinks=False`` argument. + + On Unix, this method always requires a system call. On Windows, it + only requires a system call if *follow_symlinks* is ``True`` and the + entry is a reparse point (for example, a symbolic link or directory + junction). + + On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the + :class:`stat_result` are always set to zero. Call :func:`os.stat` to + get these attributes. + + The result is cached on the ``os.DirEntry`` object, with a separate cache + for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` to + fetch up-to-date information. + + Note that there is a nice correspondence between several attributes + and methods of ``os.DirEntry`` and of :class:`pathlib.Path`. In + particular, the ``name`` attribute has the same + meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()`` + and ``stat()`` methods. + + .. versionadded:: 3.5 + + .. versionchanged:: 3.6 + Added support for the :class:`~os.PathLike` interface. Added support + for :class:`bytes` paths on Windows. + + +.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True) + + Get the status of a file or a file descriptor. Perform the equivalent of a + :c:func:`stat` system call on the given path. *path* may be specified as + either a string or bytes -- directly or indirectly through the :class:`PathLike` + interface -- or as an open file descriptor. Return a :class:`stat_result` + object. + + This function normally follows symlinks; to stat a symlink add the argument + ``follow_symlinks=False``, or use :func:`lstat`. + + This function can support :ref:`specifying a file descriptor ` and + :ref:`not following symlinks `. + + On Windows, passing ``follow_symlinks=False`` will disable following all + name-surrogate reparse points, which includes symlinks and directory + junctions. Other types of reparse points that do not resemble links or that + the operating system is unable to follow will be opened directly. When + following a chain of multiple links, this may result in the original link + being returned instead of the non-link that prevented full traversal. To + obtain stat results for the final path in this case, use the + :func:`os.path.realpath` function to resolve the path name as far as + possible and call :func:`lstat` on the result. This does not apply to + dangling symlinks or junction points, which will raise the usual exceptions. + + .. index:: module: stat + + Example:: + + >>> import os + >>> statinfo = os.stat('somefile.txt') + >>> statinfo + os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026, + st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295, + st_mtime=1297230027, st_ctime=1297230027) + >>> statinfo.st_size + 264 + + .. seealso:: + + :func:`fstat` and :func:`lstat` functions. + + .. versionadded:: 3.3 + Added the *dir_fd* and *follow_symlinks* arguments, specifying a file + descriptor instead of a path. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. versionchanged:: 3.8 + On Windows, all reparse points that can be resolved by the operating + system are now followed, and passing ``follow_symlinks=False`` + disables following all name surrogate reparse points. If the operating + system reaches a reparse point that it is not able to follow, *stat* now + returns the information for the original path as if + ``follow_symlinks=False`` had been specified instead of raising an error. + + +.. class:: stat_result + + Object whose attributes correspond roughly to the members of the + :c:type:`stat` structure. It is used for the result of :func:`os.stat`, + :func:`os.fstat` and :func:`os.lstat`. + + Attributes: + + .. attribute:: st_mode + + File mode: file type and file mode bits (permissions). + + .. attribute:: st_ino + + Platform dependent, but if non-zero, uniquely identifies the + file for a given value of ``st_dev``. Typically: + + * the inode number on Unix, + * the `file index + `_ on + Windows + + .. attribute:: st_dev + + Identifier of the device on which this file resides. + + .. attribute:: st_nlink + + Number of hard links. + + .. attribute:: st_uid + + User identifier of the file owner. + + .. attribute:: st_gid + + Group identifier of the file owner. + + .. attribute:: st_size + + Size of the file in bytes, if it is a regular file or a symbolic link. + The size of a symbolic link is the length of the pathname it contains, + without a terminating null byte. + + Timestamps: + + .. attribute:: st_atime + + Time of most recent access expressed in seconds. + + .. attribute:: st_mtime + + Time of most recent content modification expressed in seconds. + + .. attribute:: st_ctime + + Platform dependent: + + * the time of most recent metadata change on Unix, + * the time of creation on Windows, expressed in seconds. + + .. attribute:: st_atime_ns + + Time of most recent access expressed in nanoseconds as an integer. + + .. attribute:: st_mtime_ns + + Time of most recent content modification expressed in nanoseconds as an + integer. + + .. attribute:: st_ctime_ns + + Platform dependent: + + * the time of most recent metadata change on Unix, + * the time of creation on Windows, expressed in nanoseconds as an + integer. + + .. note:: + + The exact meaning and resolution of the :attr:`st_atime`, + :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating + system and the file system. For example, on Windows systems using the FAT + or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and + :attr:`st_atime` has only 1-day resolution. See your operating system + documentation for details. + + Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`, + and :attr:`st_ctime_ns` are always expressed in nanoseconds, many + systems do not provide nanosecond precision. On systems that do + provide nanosecond precision, the floating-point object used to + store :attr:`st_atime`, :attr:`st_mtime`, and :attr:`st_ctime` + cannot preserve all of it, and as such will be slightly inexact. + If you need the exact timestamps you should always use + :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`. + + On some Unix systems (such as Linux), the following attributes may also be + available: + + .. attribute:: st_blocks + + Number of 512-byte blocks allocated for file. + This may be smaller than :attr:`st_size`/512 when the file has holes. + + .. attribute:: st_blksize + + "Preferred" blocksize for efficient file system I/O. Writing to a file in + smaller chunks may cause an inefficient read-modify-rewrite. + + .. attribute:: st_rdev + + Type of device if an inode device. + + .. attribute:: st_flags + + User defined flags for file. + + On other Unix systems (such as FreeBSD), the following attributes may be + available (but may be only filled out if root tries to use them): + + .. attribute:: st_gen + + File generation number. + + .. attribute:: st_birthtime + + Time of file creation. + + On Solaris and derivatives, the following attributes may also be + available: + + .. attribute:: st_fstype + + String that uniquely identifies the type of the filesystem that + contains the file. + + On Mac OS systems, the following attributes may also be available: + + .. attribute:: st_rsize + + Real size of the file. + + .. attribute:: st_creator + + Creator of the file. + + .. attribute:: st_type + + File type. + + On Windows systems, the following attributes are also available: + + .. attribute:: st_file_attributes + + Windows file attributes: ``dwFileAttributes`` member of the + ``BY_HANDLE_FILE_INFORMATION`` structure returned by + :c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*`` + constants in the :mod:`stat` module. + + .. attribute:: st_reparse_tag + + When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT`` + set, this field contains the tag identifying the type of reparse point. + See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module. + + The standard module :mod:`stat` defines functions and constants that are + useful for extracting information from a :c:type:`stat` structure. (On + Windows, some items are filled with dummy values.) + + For backward compatibility, a :class:`stat_result` instance is also + accessible as a tuple of at least 10 integers giving the most important (and + portable) members of the :c:type:`stat` structure, in the order + :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, + :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, + :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by + some implementations. For compatibility with older Python versions, + accessing :class:`stat_result` as a tuple always returns integers. + + .. versionadded:: 3.3 + Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and + :attr:`st_ctime_ns` members. + + .. versionadded:: 3.5 + Added the :attr:`st_file_attributes` member on Windows. + + .. versionchanged:: 3.5 + Windows now returns the file index as :attr:`st_ino` when + available. + + .. versionadded:: 3.7 + Added the :attr:`st_fstype` member to Solaris/derivatives. + + .. versionadded:: 3.8 + Added the :attr:`st_reparse_tag` member on Windows. + + .. versionchanged:: 3.8 + On Windows, the :attr:`st_mode` member now identifies special + files as :const:`S_IFCHR`, :const:`S_IFIFO` or :const:`S_IFBLK` + as appropriate. + +.. function:: statvfs(path) + + Perform a :c:func:`statvfs` system call on the given path. The return value is + an object whose attributes describe the filesystem on the given path, and + correspond to the members of the :c:type:`statvfs` structure, namely: + :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, + :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`, + :attr:`f_flag`, :attr:`f_namemax`, :attr:`f_fsid`. + + Two module-level constants are defined for the :attr:`f_flag` attribute's + bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted + read-only, and if :const:`ST_NOSUID` is set, the semantics of + setuid/setgid bits are disabled or not supported. + + Additional module-level constants are defined for GNU/glibc based systems. + These are :const:`ST_NODEV` (disallow access to device special files), + :const:`ST_NOEXEC` (disallow program execution), :const:`ST_SYNCHRONOUS` + (writes are synced at once), :const:`ST_MANDLOCK` (allow mandatory locks on an FS), + :const:`ST_WRITE` (write on file/directory/symlink), :const:`ST_APPEND` + (append-only file), :const:`ST_IMMUTABLE` (immutable file), :const:`ST_NOATIME` + (do not update access times), :const:`ST_NODIRATIME` (do not update directory access + times), :const:`ST_RELATIME` (update atime relative to mtime/ctime). + + This function can support :ref:`specifying a file descriptor `. + + .. availability:: Unix. + + .. versionchanged:: 3.2 + The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor. + + .. versionchanged:: 3.4 + The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`, + :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`, + :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`, + and :const:`ST_RELATIME` constants were added. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. versionadded:: 3.7 + Added :attr:`f_fsid`. + + +.. data:: supports_dir_fd + + A :class:`set` object indicating which functions in the :mod:`os` + module accept an open file descriptor for their *dir_fd* parameter. + Different platforms provide different features, and the underlying + functionality Python uses to implement the *dir_fd* parameter is not + available on all platforms Python supports. For consistency's sake, + functions that may support *dir_fd* always allow specifying the + parameter, but will throw an exception if the functionality is used + when it's not locally available. (Specifying ``None`` for *dir_fd* + is always supported on all platforms.) + + To check whether a particular function accepts an open file descriptor + for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``. + As an example, this expression evaluates to ``True`` if :func:`os.stat` + accepts open file descriptors for *dir_fd* on the local platform:: + + os.stat in os.supports_dir_fd + + Currently *dir_fd* parameters only work on Unix platforms; + none of them work on Windows. + + .. versionadded:: 3.3 + + +.. data:: supports_effective_ids + + A :class:`set` object indicating whether :func:`os.access` permits + specifying ``True`` for its *effective_ids* parameter on the local platform. + (Specifying ``False`` for *effective_ids* is always supported on all + platforms.) If the local platform supports it, the collection will contain + :func:`os.access`; otherwise it will be empty. + + This expression evaluates to ``True`` if :func:`os.access` supports + ``effective_ids=True`` on the local platform:: + + os.access in os.supports_effective_ids + + Currently *effective_ids* is only supported on Unix platforms; + it does not work on Windows. + + .. versionadded:: 3.3 + + +.. data:: supports_fd + + A :class:`set` object indicating which functions in the + :mod:`os` module permit specifying their *path* parameter as an open file + descriptor on the local platform. Different platforms provide different + features, and the underlying functionality Python uses to accept open file + descriptors as *path* arguments is not available on all platforms Python + supports. + + To determine whether a particular function permits specifying an open file + descriptor for its *path* parameter, use the ``in`` operator on + ``supports_fd``. As an example, this expression evaluates to ``True`` if + :func:`os.chdir` accepts open file descriptors for *path* on your local + platform:: + + os.chdir in os.supports_fd + + .. versionadded:: 3.3 + + +.. data:: supports_follow_symlinks + + A :class:`set` object indicating which functions in the :mod:`os` module + accept ``False`` for their *follow_symlinks* parameter on the local platform. + Different platforms provide different features, and the underlying + functionality Python uses to implement *follow_symlinks* is not available + on all platforms Python supports. For consistency's sake, functions that + may support *follow_symlinks* always allow specifying the parameter, but + will throw an exception if the functionality is used when it's not locally + available. (Specifying ``True`` for *follow_symlinks* is always supported + on all platforms.) + + To check whether a particular function accepts ``False`` for its + *follow_symlinks* parameter, use the ``in`` operator on + ``supports_follow_symlinks``. As an example, this expression evaluates + to ``True`` if you may specify ``follow_symlinks=False`` when calling + :func:`os.stat` on the local platform:: + + os.stat in os.supports_follow_symlinks + + .. versionadded:: 3.3 + + +.. function:: symlink(src, dst, target_is_directory=False, *, dir_fd=None) + + Create a symbolic link pointing to *src* named *dst*. + + On Windows, a symlink represents either a file or a directory, and does not + morph to the target dynamically. If the target is present, the type of the + symlink will be created to match. Otherwise, the symlink will be created + as a directory if *target_is_directory* is ``True`` or a file symlink (the + default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. + + This function can support :ref:`paths relative to directory descriptors + `. + + .. note:: + + On newer versions of Windows 10, unprivileged accounts can create symlinks + if Developer Mode is enabled. When Developer Mode is not available/enabled, + the *SeCreateSymbolicLinkPrivilege* privilege is required, or the process + must be run as an administrator. + + + :exc:`OSError` is raised when the function is called by an unprivileged + user. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.2 + Added support for Windows 6.0 (Vista) symbolic links. + + .. versionadded:: 3.3 + Added the *dir_fd* argument, and now allow *target_is_directory* + on non-Windows platforms. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *src* and *dst*. + + .. versionchanged:: 3.8 + Added support for unelevated symlinks on Windows with Developer Mode. + + +.. function:: sync() + + Force write of everything to disk. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. function:: truncate(path, length) + + Truncate the file corresponding to *path*, so that it is at most + *length* bytes in size. + + This function can support :ref:`specifying a file descriptor `. + + .. audit-event:: os.truncate path,length os.truncate + + .. availability:: Unix, Windows. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.5 + Added support for Windows + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: unlink(path, *, dir_fd=None) + + Remove (delete) the file *path*. This function is semantically + identical to :func:`remove`; the ``unlink`` name is its + traditional Unix name. Please see the documentation for + :func:`remove` for further information. + + .. versionadded:: 3.3 + The *dir_fd* parameter. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: utime(path, times=None, *[, ns], dir_fd=None, follow_symlinks=True) + + Set the access and modified times of the file specified by *path*. + + :func:`utime` takes two optional parameters, *times* and *ns*. + These specify the times set on *path* and are used as follows: + + - If *ns* is specified, + it must be a 2-tuple of the form ``(atime_ns, mtime_ns)`` + where each member is an int expressing nanoseconds. + - If *times* is not ``None``, + it must be a 2-tuple of the form ``(atime, mtime)`` + where each member is an int or float expressing seconds. + - If *times* is ``None`` and *ns* is unspecified, + this is equivalent to specifying ``ns=(atime_ns, mtime_ns)`` + where both times are the current time. + + It is an error to specify tuples for both *times* and *ns*. + + Note that the exact times you set here may not be returned by a subsequent + :func:`~os.stat` call, depending on the resolution with which your operating + system records access and modification times; see :func:`~os.stat`. The best + way to preserve exact times is to use the *st_atime_ns* and *st_mtime_ns* + fields from the :func:`os.stat` result object with the *ns* parameter to + `utime`. + + This function can support :ref:`specifying a file descriptor `, + :ref:`paths relative to directory descriptors ` and :ref:`not + following symlinks `. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor, + and the *dir_fd*, *follow_symlinks*, and *ns* parameters. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: walk(top, topdown=True, onerror=None, followlinks=False) + + .. index:: + single: directory; walking + single: directory; traversal + + Generate the file names in a directory tree by walking the tree + either top-down or bottom-up. For each directory in the tree rooted at directory + *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, + filenames)``. + + *dirpath* is a string, the path to the directory. *dirnames* is a list of the + names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``). + *filenames* is a list of the names of the non-directory files in *dirpath*. + Note that the names in the lists contain no path components. To get a full path + (which begins with *top*) to a file or directory in *dirpath*, do + ``os.path.join(dirpath, name)``. + + If optional argument *topdown* is ``True`` or not specified, the triple for a + directory is generated before the triples for any of its subdirectories + (directories are generated top-down). If *topdown* is ``False``, the triple + for a directory is generated after the triples for all of its subdirectories + (directories are generated bottom-up). No matter the value of *topdown*, the + list of subdirectories is retrieved before the tuples for the directory and + its subdirectories are generated. + + When *topdown* is ``True``, the caller can modify the *dirnames* list in-place + (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only + recurse into the subdirectories whose names remain in *dirnames*; this can be + used to prune the search, impose a specific order of visiting, or even to inform + :func:`walk` about directories the caller creates or renames before it resumes + :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has + no effect on the behavior of the walk, because in bottom-up mode the directories + in *dirnames* are generated before *dirpath* itself is generated. + + By default, errors from the :func:`scandir` call are ignored. If optional + argument *onerror* is specified, it should be a function; it will be called with + one argument, an :exc:`OSError` instance. It can report the error to continue + with the walk, or raise the exception to abort the walk. Note that the filename + is available as the ``filename`` attribute of the exception object. + + By default, :func:`walk` will not walk down into symbolic links that resolve to + directories. Set *followlinks* to ``True`` to visit directories pointed to by + symlinks, on systems that support them. + + .. note:: + + Be aware that setting *followlinks* to ``True`` can lead to infinite + recursion if a link points to a parent directory of itself. :func:`walk` + does not keep track of the directories it visited already. + + .. note:: + + If you pass a relative pathname, don't change the current working directory + between resumptions of :func:`walk`. :func:`walk` never changes the current + directory, and assumes that its caller doesn't either. + + This example displays the number of bytes taken by non-directory files in each + directory under the starting directory, except that it doesn't look under any + CVS subdirectory:: + + import os + from os.path import join, getsize + for root, dirs, files in os.walk('python/Lib/email'): + print(root, "consumes", end=" ") + print(sum(getsize(join(root, name)) for name in files), end=" ") + print("bytes in", len(files), "non-directory files") + if 'CVS' in dirs: + dirs.remove('CVS') # don't visit CVS directories + + In the next example (simple implementation of :func:`shutil.rmtree`), + walking the tree bottom-up is essential, :func:`rmdir` doesn't allow + deleting a directory before the directory is empty:: + + # Delete everything reachable from the directory named in "top", + # assuming there are no symbolic links. + # CAUTION: This is dangerous! For example, if top == '/', it + # could delete all your disk files. + import os + for root, dirs, files in os.walk(top, topdown=False): + for name in files: + os.remove(os.path.join(root, name)) + for name in dirs: + os.rmdir(os.path.join(root, name)) + + .. versionchanged:: 3.5 + This function now calls :func:`os.scandir` instead of :func:`os.listdir`, + making it faster by reducing the number of calls to :func:`os.stat`. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None) + + .. index:: + single: directory; walking + single: directory; traversal + + This behaves exactly like :func:`walk`, except that it yields a 4-tuple + ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``. + + *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output, + and *dirfd* is a file descriptor referring to the directory *dirpath*. + + This function always supports :ref:`paths relative to directory descriptors + ` and :ref:`not following symlinks `. Note however + that, unlike other functions, the :func:`fwalk` default value for + *follow_symlinks* is ``False``. + + .. note:: + + Since :func:`fwalk` yields file descriptors, those are only valid until + the next iteration step, so you should duplicate them (e.g. with + :func:`dup`) if you want to keep them longer. + + This example displays the number of bytes taken by non-directory files in each + directory under the starting directory, except that it doesn't look under any + CVS subdirectory:: + + import os + for root, dirs, files, rootfd in os.fwalk('python/Lib/email'): + print(root, "consumes", end="") + print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]), + end="") + print("bytes in", len(files), "non-directory files") + if 'CVS' in dirs: + dirs.remove('CVS') # don't visit CVS directories + + In the next example, walking the tree bottom-up is essential: + :func:`rmdir` doesn't allow deleting a directory before the directory is + empty:: + + # Delete everything reachable from the directory named in "top", + # assuming there are no symbolic links. + # CAUTION: This is dangerous! For example, if top == '/', it + # could delete all your disk files. + import os + for root, dirs, files, rootfd in os.fwalk(top, topdown=False): + for name in files: + os.unlink(name, dir_fd=rootfd) + for name in dirs: + os.rmdir(name, dir_fd=rootfd) + + .. availability:: Unix. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + .. versionchanged:: 3.7 + Added support for :class:`bytes` paths. + + +.. function:: memfd_create(name[, flags=os.MFD_CLOEXEC]) + + Create an anonymous file and return a file descriptor that refers to it. + *flags* must be one of the ``os.MFD_*`` constants available on the system + (or a bitwise ORed combination of them). By default, the new file + descriptor is :ref:`non-inheritable `. + + The name supplied in *name* is used as a filename and will be displayed as + the target of the corresponding symbolic link in the directory + ``/proc/self/fd/``. The displayed name is always prefixed with ``memfd:`` + and serves only for debugging purposes. Names do not affect the behavior of + the file descriptor, and as such multiple files can have the same name + without any side effects. + + .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. + + .. versionadded:: 3.8 + + +.. data:: MFD_CLOEXEC + MFD_ALLOW_SEALING + MFD_HUGETLB + MFD_HUGE_SHIFT + MFD_HUGE_MASK + MFD_HUGE_64KB + MFD_HUGE_512KB + MFD_HUGE_1MB + MFD_HUGE_2MB + MFD_HUGE_8MB + MFD_HUGE_16MB + MFD_HUGE_32MB + MFD_HUGE_256MB + MFD_HUGE_512MB + MFD_HUGE_1GB + MFD_HUGE_2GB + MFD_HUGE_16GB + + These flags can be passed to :func:`memfd_create`. + + .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. The + ``MFD_HUGE*`` flags are only available since Linux 4.14. + + .. versionadded:: 3.8 + + +Linux extended attributes +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 3.3 + +These functions are all available on Linux only. + +.. function:: getxattr(path, attribute, *, follow_symlinks=True) + + Return the value of the extended filesystem attribute *attribute* for + *path*. *attribute* can be bytes or str (directly or indirectly through the + :class:`PathLike` interface). If it is str, it is encoded with the filesystem + encoding. + + This function can support :ref:`specifying a file descriptor ` and + :ref:`not following symlinks `. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *attribute*. + + +.. function:: listxattr(path=None, *, follow_symlinks=True) + + Return a list of the extended filesystem attributes on *path*. The + attributes in the list are represented as strings decoded with the filesystem + encoding. If *path* is ``None``, :func:`listxattr` will examine the current + directory. + + This function can support :ref:`specifying a file descriptor ` and + :ref:`not following symlinks `. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. function:: removexattr(path, attribute, *, follow_symlinks=True) + + Removes the extended filesystem attribute *attribute* from *path*. + *attribute* should be bytes or str (directly or indirectly through the + :class:`PathLike` interface). If it is a string, it is encoded + with the filesystem encoding. + + This function can support :ref:`specifying a file descriptor ` and + :ref:`not following symlinks `. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *attribute*. + + +.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True) + + Set the extended filesystem attribute *attribute* on *path* to *value*. + *attribute* must be a bytes or str with no embedded NULs (directly or + indirectly through the :class:`PathLike` interface). If it is a str, + it is encoded with the filesystem encoding. *flags* may be + :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is + given and the attribute does not exist, ``EEXISTS`` will be raised. + If :data:`XATTR_CREATE` is given and the attribute already exists, the + attribute will not be created and ``ENODATA`` will be raised. + + This function can support :ref:`specifying a file descriptor ` and + :ref:`not following symlinks `. + + .. note:: + + A bug in Linux kernel versions less than 2.6.39 caused the flags argument + to be ignored on some filesystems. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object` for *path* and *attribute*. + + +.. data:: XATTR_SIZE_MAX + + The maximum size the value of an extended attribute can be. Currently, this + is 64 KiB on Linux. + + +.. data:: XATTR_CREATE + + This is a possible value for the flags argument in :func:`setxattr`. It + indicates the operation must create an attribute. + + +.. data:: XATTR_REPLACE + + This is a possible value for the flags argument in :func:`setxattr`. It + indicates the operation must replace an existing attribute. + + +.. _os-process: + +Process Management +------------------ + +These functions may be used to create and manage processes. + +The various :func:`exec\* ` functions take a list of arguments for the new +program loaded into the process. In each case, the first of these arguments is +passed to the new program as its own name rather than as an argument a user may +have typed on a command line. For the C programmer, this is the ``argv[0]`` +passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', +['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem +to be ignored. + + +.. function:: abort() + + Generate a :const:`SIGABRT` signal to the current process. On Unix, the default + behavior is to produce a core dump; on Windows, the process immediately returns + an exit code of ``3``. Be aware that calling this function will not call the + Python signal handler registered for :const:`SIGABRT` with + :func:`signal.signal`. + + +.. function:: add_dll_directory(path) + + Add a path to the DLL search path. + + This search path is used when resolving dependencies for imported + extension modules (the module itself is resolved through sys.path), + and also by :mod:`ctypes`. + + Remove the directory by calling **close()** on the returned object + or using it in a :keyword:`with` statement. + + See the `Microsoft documentation + `_ + for more information about how DLLs are loaded. + + .. availability:: Windows. + + .. versionadded:: 3.8 + Previous versions of CPython would resolve DLLs using the default + behavior for the current process. This led to inconsistencies, + such as only sometimes searching :envvar:`PATH` or the current + working directory, and OS functions such as ``AddDllDirectory`` + having no effect. + + In 3.8, the two primary ways DLLs are loaded now explicitly + override the process-wide behavior to ensure consistency. See the + :ref:`porting notes ` for information on + updating libraries. + + +.. function:: execl(path, arg0, arg1, ...) + execle(path, arg0, arg1, ..., env) + execlp(file, arg0, arg1, ...) + execlpe(file, arg0, arg1, ..., env) + execv(path, args) + execve(path, args, env) + execvp(file, args) + execvpe(file, args, env) + + These functions all execute a new program, replacing the current process; they + do not return. On Unix, the new executable is loaded into the current process, + and will have the same process id as the caller. Errors will be reported as + :exc:`OSError` exceptions. + + The current process is replaced immediately. Open file objects and + descriptors are not flushed, so if there may be data buffered + on these open files, you should flush them using + :func:`sys.stdout.flush` or :func:`os.fsync` before calling an + :func:`exec\* ` function. + + The "l" and "v" variants of the :func:`exec\* ` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest + to work with if the number of parameters is fixed when the code is written; the + individual parameters simply become additional parameters to the :func:`execl\*` + functions. The "v" variants are good when the number of parameters is + variable, with the arguments being passed in a list or tuple as the *args* + parameter. In either case, the arguments to the child process should start with + the name of the command being run, but this is not enforced. + + The variants which include a "p" near the end (:func:`execlp`, + :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the + :envvar:`PATH` environment variable to locate the program *file*. When the + environment is being replaced (using one of the :func:`exec\*e ` variants, + discussed in the next paragraph), the new environment is used as the source of + the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`, + :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to + locate the executable; *path* must contain an appropriate absolute or relative + path. + + For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note + that these all end in "e"), the *env* parameter must be a mapping which is + used to define the environment variables for the new process (these are used + instead of the current process' environment); the functions :func:`execl`, + :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to + inherit the environment of the current process. + + For :func:`execve` on some platforms, *path* may also be specified as an open + file descriptor. This functionality may not be supported on your platform; + you can check whether or not it is available using :data:`os.supports_fd`. + If it is unavailable, using it will raise a :exc:`NotImplementedError`. + + .. availability:: Unix, Windows. + + .. versionadded:: 3.3 + Added support for specifying *path* as an open file descriptor + for :func:`execve`. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + +.. function:: _exit(n) + + Exit the process with status *n*, without calling cleanup handlers, flushing + stdio buffers, etc. + + .. note:: + + The standard way to exit is ``sys.exit(n)``. :func:`_exit` should + normally only be used in the child process after a :func:`fork`. + +The following exit codes are defined and can be used with :func:`_exit`, +although they are not required. These are typically used for system programs +written in Python, such as a mail server's external command delivery program. + +.. note:: + + Some of these may not be available on all Unix platforms, since there is some + variation. These constants are defined where they are defined by the underlying + platform. + + +.. data:: EX_OK + + Exit code that means no error occurred. + + .. availability:: Unix. + + +.. data:: EX_USAGE + + Exit code that means the command was used incorrectly, such as when the wrong + number of arguments are given. + + .. availability:: Unix. + + +.. data:: EX_DATAERR + + Exit code that means the input data was incorrect. + + .. availability:: Unix. + + +.. data:: EX_NOINPUT + + Exit code that means an input file did not exist or was not readable. + + .. availability:: Unix. + + +.. data:: EX_NOUSER + + Exit code that means a specified user did not exist. + + .. availability:: Unix. + + +.. data:: EX_NOHOST + + Exit code that means a specified host did not exist. + + .. availability:: Unix. + + +.. data:: EX_UNAVAILABLE + + Exit code that means that a required service is unavailable. + + .. availability:: Unix. + + +.. data:: EX_SOFTWARE + + Exit code that means an internal software error was detected. + + .. availability:: Unix. + + +.. data:: EX_OSERR + + Exit code that means an operating system error was detected, such as the + inability to fork or create a pipe. + + .. availability:: Unix. + + +.. data:: EX_OSFILE + + Exit code that means some system file did not exist, could not be opened, or had + some other kind of error. + + .. availability:: Unix. + + +.. data:: EX_CANTCREAT + + Exit code that means a user specified output file could not be created. + + .. availability:: Unix. + + +.. data:: EX_IOERR + + Exit code that means that an error occurred while doing I/O on some file. + + .. availability:: Unix. + + +.. data:: EX_TEMPFAIL + + Exit code that means a temporary failure occurred. This indicates something + that may not really be an error, such as a network connection that couldn't be + made during a retryable operation. + + .. availability:: Unix. + + +.. data:: EX_PROTOCOL + + Exit code that means that a protocol exchange was illegal, invalid, or not + understood. + + .. availability:: Unix. + + +.. data:: EX_NOPERM + + Exit code that means that there were insufficient permissions to perform the + operation (but not intended for file system problems). + + .. availability:: Unix. + + +.. data:: EX_CONFIG + + Exit code that means that some kind of configuration error occurred. + + .. availability:: Unix. + + +.. data:: EX_NOTFOUND + + Exit code that means something like "an entry was not found". + + .. availability:: Unix. + + +.. function:: fork() + + Fork a child process. Return ``0`` in the child and the child's process id in the + parent. If an error occurs :exc:`OSError` is raised. + + Note that some platforms including FreeBSD <= 6.3 and Cygwin have + known issues when using ``fork()`` from a thread. + + .. versionchanged:: 3.8 + Calling ``fork()`` in a subinterpreter is no longer supported + (:exc:`RuntimeError` is raised). + + .. warning:: + + See :mod:`ssl` for applications that use the SSL module with fork(). + + .. availability:: Unix. + + +.. function:: forkpty() + + Fork a child process, using a new pseudo-terminal as the child's controlling + terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the + new child's process id in the parent, and *fd* is the file descriptor of the + master end of the pseudo-terminal. For a more portable approach, use the + :mod:`pty` module. If an error occurs :exc:`OSError` is raised. + + .. versionchanged:: 3.8 + Calling ``forkpty()`` in a subinterpreter is no longer supported + (:exc:`RuntimeError` is raised). + + .. availability:: some flavors of Unix. + + +.. function:: kill(pid, sig) + + .. index:: + single: process; killing + single: process; signalling + + Send signal *sig* to the process *pid*. Constants for the specific signals + available on the host platform are defined in the :mod:`signal` module. + + Windows: The :data:`signal.CTRL_C_EVENT` and + :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can + only be sent to console processes which share a common console window, + e.g., some subprocesses. Any other value for *sig* will cause the process + to be unconditionally killed by the TerminateProcess API, and the exit code + will be set to *sig*. The Windows version of :func:`kill` additionally takes + process handles to be killed. + + See also :func:`signal.pthread_kill`. + + .. versionadded:: 3.2 + Windows support. + + +.. function:: killpg(pgid, sig) + + .. index:: + single: process; killing + single: process; signalling + + Send the signal *sig* to the process group *pgid*. + + .. availability:: Unix. + + +.. function:: nice(increment) + + Add *increment* to the process's "niceness". Return the new niceness. + + .. availability:: Unix. + + +.. function:: pidfd_open(pid, flags=0) + + Return a file descriptor referring to the process *pid*. This descriptor can + be used to perform process management without races and signals. The *flags* + argument is provided for future extensions; no flag values are currently + defined. + + See the :manpage:`pidfd_open(2)` man page for more details. + + .. availability:: Linux 5.3+ + .. versionadded:: 3.9 + + +.. function:: plock(op) + + Lock program segments into memory. The value of *op* (defined in + ````) determines which segments are locked. + + .. availability:: Unix. + + +.. function:: popen(cmd, mode='r', buffering=-1) + + Open a pipe to or from command *cmd*. + The return value is an open file object + connected to the pipe, which can be read or written depending on whether *mode* + is ``'r'`` (default) or ``'w'``. The *buffering* argument has the same meaning as + the corresponding argument to the built-in :func:`open` function. The + returned file object reads or writes text strings rather than bytes. + + The ``close`` method returns :const:`None` if the subprocess exited + successfully, or the subprocess's return code if there was an + error. On POSIX systems, if the return code is positive it + represents the return value of the process left-shifted by one + byte. If the return code is negative, the process was terminated + by the signal given by the negated value of the return code. (For + example, the return value might be ``- signal.SIGKILL`` if the + subprocess was killed.) On Windows systems, the return value + contains the signed integer return code from the child process. + + This is implemented using :class:`subprocess.Popen`; see that class's + documentation for more powerful ways to manage and communicate with + subprocesses. + + +.. function:: posix_spawn(path, argv, env, *, file_actions=None, \ + setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ + setsigdef=(), scheduler=None) + + Wraps the :c:func:`posix_spawn` C library API for use from Python. + + Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`. + + The positional-only arguments *path*, *args*, and *env* are similar to + :func:`execve`. + + The *path* parameter is the path to the executable file.The *path* should + contain a directory.Use :func:`posix_spawnp` to pass an executable file + without directory. + + The *file_actions* argument may be a sequence of tuples describing actions + to take on specific file descriptors in the child process between the C + library implementation's :c:func:`fork` and :c:func:`exec` steps. + The first item in each tuple must be one of the three type indicator + listed below describing the remaining tuple elements: + + .. data:: POSIX_SPAWN_OPEN + + (``os.POSIX_SPAWN_OPEN``, *fd*, *path*, *flags*, *mode*) + + Performs ``os.dup2(os.open(path, flags, mode), fd)``. + + .. data:: POSIX_SPAWN_CLOSE + + (``os.POSIX_SPAWN_CLOSE``, *fd*) + + Performs ``os.close(fd)``. + + .. data:: POSIX_SPAWN_DUP2 + + (``os.POSIX_SPAWN_DUP2``, *fd*, *new_fd*) + + Performs ``os.dup2(fd, new_fd)``. + + These tuples correspond to the C library + :c:func:`posix_spawn_file_actions_addopen`, + :c:func:`posix_spawn_file_actions_addclose`, and + :c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare + for the :c:func:`posix_spawn` call itself. + + The *setpgroup* argument will set the process group of the child to the value + specified. If the value specified is 0, the child's process group ID will be + made the same as its process ID. If the value of *setpgroup* is not set, the + child will inherit the parent's process group ID. This argument corresponds + to the C library :c:data:`POSIX_SPAWN_SETPGROUP` flag. + + If the *resetids* argument is ``True`` it will reset the effective UID and + GID of the child to the real UID and GID of the parent process. If the + argument is ``False``, then the child retains the effective UID and GID of + the parent. In either case, if the set-user-ID and set-group-ID permission + bits are enabled on the executable file, their effect will override the + setting of the effective UID and GID. This argument corresponds to the C + library :c:data:`POSIX_SPAWN_RESETIDS` flag. + + If the *setsid* argument is ``True``, it will create a new session ID + for `posix_spawn`. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` + or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` + is raised. + + The *setsigmask* argument will set the signal mask to the signal set + specified. If the parameter is not used, then the child inherits the + parent's signal mask. This argument corresponds to the C library + :c:data:`POSIX_SPAWN_SETSIGMASK` flag. + + The *sigdef* argument will reset the disposition of all signals in the set + specified. This argument corresponds to the C library + :c:data:`POSIX_SPAWN_SETSIGDEF` flag. + + The *scheduler* argument must be a tuple containing the (optional) scheduler + policy and an instance of :class:`sched_param` with the scheduler parameters. + A value of ``None`` in the place of the scheduler policy indicates that is + not being provided. This argument is a combination of the C library + :c:data:`POSIX_SPAWN_SETSCHEDPARAM` and :c:data:`POSIX_SPAWN_SETSCHEDULER` + flags. + + .. versionadded:: 3.8 + + .. availability:: Unix. + +.. function:: posix_spawnp(path, argv, env, *, file_actions=None, \ + setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ + setsigdef=(), scheduler=None) + + Wraps the :c:func:`posix_spawnp` C library API for use from Python. + + Similar to :func:`posix_spawn` except that the system searches + for the *executable* file in the list of directories specified by the + :envvar:`PATH` environment variable (in the same way as for ``execvp(3)``). + + .. versionadded:: 3.8 + + .. availability:: See :func:`posix_spawn` documentation. + + +.. function:: register_at_fork(*, before=None, after_in_parent=None, \ + after_in_child=None) + + Register callables to be executed when a new child process is forked + using :func:`os.fork` or similar process cloning APIs. + The parameters are optional and keyword-only. + Each specifies a different call point. + + * *before* is a function called before forking a child process. + * *after_in_parent* is a function called from the parent process + after forking a child process. + * *after_in_child* is a function called from the child process. + + These calls are only made if control is expected to return to the + Python interpreter. A typical :mod:`subprocess` launch will not + trigger them as the child is not going to re-enter the interpreter. + + Functions registered for execution before forking are called in + reverse registration order. Functions registered for execution + after forking (either in the parent or in the child) are called + in registration order. + + Note that :c:func:`fork` calls made by third-party C code may not + call those functions, unless it explicitly calls :c:func:`PyOS_BeforeFork`, + :c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`. + + There is no way to unregister a function. + + .. availability:: Unix. + + .. versionadded:: 3.7 + + +.. function:: spawnl(mode, path, ...) + spawnle(mode, path, ..., env) + spawnlp(mode, file, ...) + spawnlpe(mode, file, ..., env) + spawnv(mode, path, args) + spawnve(mode, path, args, env) + spawnvp(mode, file, args) + spawnvpe(mode, file, args, env) + + Execute the program *path* in a new process. + + (Note that the :mod:`subprocess` module provides more powerful facilities for + spawning new processes and retrieving their results; using that module is + preferable to using these functions. Check especially the + :ref:`subprocess-replacements` section.) + + If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new + process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it + exits normally, or ``-signal``, where *signal* is the signal that killed the + process. On Windows, the process id will actually be the process handle, so can + be used with the :func:`waitpid` function. + + Note on VxWorks, this function doesn't return ``-signal`` when the new process is + killed. Instead it raises OSError exception. + + The "l" and "v" variants of the :func:`spawn\* ` functions differ in how + command-line arguments are passed. The "l" variants are perhaps the easiest + to work with if the number of parameters is fixed when the code is written; the + individual parameters simply become additional parameters to the + :func:`spawnl\*` functions. The "v" variants are good when the number of + parameters is variable, with the arguments being passed in a list or tuple as + the *args* parameter. In either case, the arguments to the child process must + start with the name of the command being run. + + The variants which include a second "p" near the end (:func:`spawnlp`, + :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the + :envvar:`PATH` environment variable to locate the program *file*. When the + environment is being replaced (using one of the :func:`spawn\*e ` variants, + discussed in the next paragraph), the new environment is used as the source of + the :envvar:`PATH` variable. The other variants, :func:`spawnl`, + :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the + :envvar:`PATH` variable to locate the executable; *path* must contain an + appropriate absolute or relative path. + + For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` + (note that these all end in "e"), the *env* parameter must be a mapping + which is used to define the environment variables for the new process (they are + used instead of the current process' environment); the functions + :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause + the new process to inherit the environment of the current process. Note that + keys and values in the *env* dictionary must be strings; invalid keys or + values will cause the function to fail, with a return value of ``127``. + + As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are + equivalent:: + + import os + os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') + + L = ['cp', 'index.html', '/dev/null'] + os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) + + .. availability:: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp` + and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and + :func:`spawnve` are not thread-safe on Windows; we advise you to use the + :mod:`subprocess` module instead. + + .. versionchanged:: 3.6 + Accepts a :term:`path-like object`. + + +.. data:: P_NOWAIT + P_NOWAITO + + Possible values for the *mode* parameter to the :func:`spawn\* ` family of + functions. If either of these values is given, the :func:`spawn\*` functions + will return as soon as the new process has been created, with the process id as + the return value. + + .. availability:: Unix, Windows. + + +.. data:: P_WAIT + + Possible value for the *mode* parameter to the :func:`spawn\* ` family of + functions. If this is given as *mode*, the :func:`spawn\*` functions will not + return until the new process has run to completion and will return the exit code + of the process the run is successful, or ``-signal`` if a signal kills the + process. + + .. availability:: Unix, Windows. + + +.. data:: P_DETACH + P_OVERLAY + + Possible values for the *mode* parameter to the :func:`spawn\* ` family of + functions. These are less portable than those listed above. :const:`P_DETACH` + is similar to :const:`P_NOWAIT`, but the new process is detached from the + console of the calling process. If :const:`P_OVERLAY` is used, the current + process will be replaced; the :func:`spawn\* ` function will not return. + + .. availability:: Windows. + + +.. function:: startfile(path[, operation]) + + Start a file with its associated application. + + When *operation* is not specified or ``'open'``, this acts like double-clicking + the file in Windows Explorer, or giving the file name as an argument to the + :program:`start` command from the interactive command shell: the file is opened + with whatever application (if any) its extension is associated. + + When another *operation* is given, it must be a "command verb" that specifies + what should be done with the file. Common verbs documented by Microsoft are + ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and + ``'find'`` (to be used on directories). + + :func:`startfile` returns as soon as the associated application is launched. + There is no option to wait for the application to close, and no way to retrieve + the application's exit status. The *path* parameter is relative to the current + directory. If you want to use an absolute path, make sure the first character + is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function + doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that + the path is properly encoded for Win32. + + To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute` + function is not resolved until this function is first called. If the function + cannot be resolved, :exc:`NotImplementedError` will be raised. + + .. availability:: Windows. + + +.. function:: system(command) + + Execute the command (a string) in a subshell. This is implemented by calling + the Standard C function :c:func:`system`, and has the same limitations. + Changes to :data:`sys.stdin`, etc. are not reflected in the environment of + the executed command. If *command* generates any output, it will be sent to + the interpreter standard output stream. + + On Unix, the return value is the exit status of the process encoded in the + format specified for :func:`wait`. Note that POSIX does not specify the + meaning of the return value of the C :c:func:`system` function, so the return + value of the Python function is system-dependent. + + On Windows, the return value is that returned by the system shell after + running *command*. The shell is given by the Windows environment variable + :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit + status of the command run; on systems using a non-native shell, consult your + shell documentation. + + The :mod:`subprocess` module provides more powerful facilities for spawning + new processes and retrieving their results; using that module is preferable + to using this function. See the :ref:`subprocess-replacements` section in + the :mod:`subprocess` documentation for some helpful recipes. + + .. audit-event:: os.system command os.system + + .. availability:: Unix, Windows. + + +.. function:: times() + + Returns the current global process times. + The return value is an object with five attributes: + + * :attr:`user` - user time + * :attr:`system` - system time + * :attr:`children_user` - user time of all child processes + * :attr:`children_system` - system time of all child processes + * :attr:`elapsed` - elapsed real time since a fixed point in the past + + For backwards compatibility, this object also behaves like a five-tuple + containing :attr:`user`, :attr:`system`, :attr:`children_user`, + :attr:`children_system`, and :attr:`elapsed` in that order. + + See the Unix manual page + :manpage:`times(2)` and :manpage:`times(3)` manual page on Unix or `the GetProcessTimes MSDN + ` + _ on Windows. + On Windows, only :attr:`user` and :attr:`system` are known; the other + attributes are zero. + + .. availability:: Unix, Windows. + + .. versionchanged:: 3.3 + Return type changed from a tuple to a tuple-like object + with named attributes. + + +.. function:: wait() + + Wait for completion of a child process, and return a tuple containing its pid + and exit status indication: a 16-bit number, whose low byte is the signal number + that killed the process, and whose high byte is the exit status (if the signal + number is zero); the high bit of the low byte is set if a core file was + produced. + + .. availability:: Unix. + +.. function:: waitid(idtype, id, options) + + Wait for the completion of one or more child processes. + *idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or + :data:`P_PIDFD` on Linux. + *id* specifies the pid to wait on. + *options* is constructed from the ORing of one or more of :data:`WEXITED`, + :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with + :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object + representing the data contained in the :c:type:`siginfo_t` structure, namely: + :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`, + :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no + children in a waitable state. + + .. availability:: Unix. + + .. versionadded:: 3.3 + +.. data:: P_PID + P_PGID + P_ALL + + These are the possible values for *idtype* in :func:`waitid`. They affect + how *id* is interpreted. + + .. availability:: Unix. + + .. versionadded:: 3.3 + +.. data:: P_PIDFD + + This is a Linux-specific *idtype* that indicates that *id* is a file + descriptor that refers to a process. + + .. availability:: Linux 5.4+ + + .. versionadded:: 3.9 + +.. data:: WEXITED + WSTOPPED + WNOWAIT + + Flags that can be used in *options* in :func:`waitid` that specify what + child signal to wait for. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + +.. data:: CLD_EXITED + CLD_KILLED + CLD_DUMPED + CLD_TRAPPED + CLD_STOPPED + CLD_CONTINUED + + These are the possible values for :attr:`si_code` in the result returned by + :func:`waitid`. + + .. availability:: Unix. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.9 + Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values. + + +.. function:: waitpid(pid, options) + + The details of this function differ on Unix and Windows. + + On Unix: Wait for completion of a child process given by process id *pid*, and + return a tuple containing its process id and exit status indication (encoded as + for :func:`wait`). The semantics of the call are affected by the value of the + integer *options*, which should be ``0`` for normal operation. + + If *pid* is greater than ``0``, :func:`waitpid` requests status information for + that specific process. If *pid* is ``0``, the request is for the status of any + child in the process group of the current process. If *pid* is ``-1``, the + request pertains to any child of the current process. If *pid* is less than + ``-1``, status is requested for any process in the process group ``-pid`` (the + absolute value of *pid*). + + An :exc:`OSError` is raised with the value of errno when the syscall + returns -1. + + On Windows: Wait for completion of a process given by process handle *pid*, and + return a tuple containing *pid*, and its exit status shifted left by 8 bits + (shifting makes cross-platform use of the function easier). A *pid* less than or + equal to ``0`` has no special meaning on Windows, and raises an exception. The + value of integer *options* has no effect. *pid* can refer to any process whose + id is known, not necessarily a child process. The :func:`spawn\* ` + functions called with :const:`P_NOWAIT` return suitable process handles. + + .. versionchanged:: 3.5 + If the system call is interrupted and the signal handler does not raise an + exception, the function now retries the system call instead of raising an + :exc:`InterruptedError` exception (see :pep:`475` for the rationale). + + +.. function:: wait3(options) + + Similar to :func:`waitpid`, except no process id argument is given and a + 3-element tuple containing the child's process id, exit status indication, + and resource usage information is returned. Refer to + :mod:`resource`.\ :func:`~resource.getrusage` for details on resource usage + information. The option argument is the same as that provided to + :func:`waitpid` and :func:`wait4`. + + .. availability:: Unix. + + +.. function:: wait4(pid, options) + + Similar to :func:`waitpid`, except a 3-element tuple, containing the child's + process id, exit status indication, and resource usage information is returned. + Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on + resource usage information. The arguments to :func:`wait4` are the same + as those provided to :func:`waitpid`. + + .. availability:: Unix. + + +.. data:: WNOHANG + + The option for :func:`waitpid` to return immediately if no child process status + is available immediately. The function returns ``(0, 0)`` in this case. + + .. availability:: Unix. + + +.. data:: WCONTINUED + + This option causes child processes to be reported if they have been continued + from a job control stop since their status was last reported. + + .. availability:: some Unix systems. + + +.. data:: WUNTRACED + + This option causes child processes to be reported if they have been stopped but + their current state has not been reported since they were stopped. + + .. availability:: Unix. + + +The following functions take a process status code as returned by +:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be +used to determine the disposition of a process. + +.. function:: WCOREDUMP(status) + + Return ``True`` if a core dump was generated for the process, otherwise + return ``False``. + + .. availability:: Unix. + + +.. function:: WIFCONTINUED(status) + + Return ``True`` if the process has been continued from a job control stop, + otherwise return ``False``. + + .. availability:: Unix. + + +.. function:: WIFSTOPPED(status) + + Return ``True`` if the process has been stopped, otherwise return + ``False``. + + .. availability:: Unix. + + +.. function:: WIFSIGNALED(status) + + Return ``True`` if the process exited due to a signal, otherwise return + ``False``. + + .. availability:: Unix. + + +.. function:: WIFEXITED(status) + + Return ``True`` if the process exited using the :manpage:`exit(2)` system call, + otherwise return ``False``. + + .. availability:: Unix. + + +.. function:: WEXITSTATUS(status) + + If ``WIFEXITED(status)`` is true, return the integer parameter to the + :manpage:`exit(2)` system call. Otherwise, the return value is meaningless. + + .. availability:: Unix. + + +.. function:: WSTOPSIG(status) + + Return the signal which caused the process to stop. + + .. availability:: Unix. + + +.. function:: WTERMSIG(status) + + Return the signal which caused the process to exit. + + .. availability:: Unix. + + +Interface to the scheduler +-------------------------- + +These functions control how a process is allocated CPU time by the operating +system. They are only available on some Unix platforms. For more detailed +information, consult your Unix manpages. + +.. versionadded:: 3.3 + +The following scheduling policies are exposed if they are supported by the +operating system. + +.. data:: SCHED_OTHER + + The default scheduling policy. + +.. data:: SCHED_BATCH + + Scheduling policy for CPU-intensive processes that tries to preserve + interactivity on the rest of the computer. + +.. data:: SCHED_IDLE + + Scheduling policy for extremely low priority background tasks. + +.. data:: SCHED_SPORADIC + + Scheduling policy for sporadic server programs. + +.. data:: SCHED_FIFO + + A First In First Out scheduling policy. + +.. data:: SCHED_RR + + A round-robin scheduling policy. + +.. data:: SCHED_RESET_ON_FORK + + This flag can be OR'ed with any other scheduling policy. When a process with + this flag set forks, its child's scheduling policy and priority are reset to + the default. + + +.. class:: sched_param(sched_priority) + + This class represents tunable scheduling parameters used in + :func:`sched_setparam`, :func:`sched_setscheduler`, and + :func:`sched_getparam`. It is immutable. + + At the moment, there is only one possible parameter: + + .. attribute:: sched_priority + + The scheduling priority for a scheduling policy. + + +.. function:: sched_get_priority_min(policy) + + Get the minimum priority value for *policy*. *policy* is one of the + scheduling policy constants above. + + +.. function:: sched_get_priority_max(policy) + + Get the maximum priority value for *policy*. *policy* is one of the + scheduling policy constants above. + + +.. function:: sched_setscheduler(pid, policy, param) + + Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means + the calling process. *policy* is one of the scheduling policy constants + above. *param* is a :class:`sched_param` instance. + + +.. function:: sched_getscheduler(pid) + + Return the scheduling policy for the process with PID *pid*. A *pid* of 0 + means the calling process. The result is one of the scheduling policy + constants above. + + +.. function:: sched_setparam(pid, param) + + Set a scheduling parameters for the process with PID *pid*. A *pid* of 0 means + the calling process. *param* is a :class:`sched_param` instance. + + +.. function:: sched_getparam(pid) + + Return the scheduling parameters as a :class:`sched_param` instance for the + process with PID *pid*. A *pid* of 0 means the calling process. + + +.. function:: sched_rr_get_interval(pid) + + Return the round-robin quantum in seconds for the process with PID *pid*. A + *pid* of 0 means the calling process. + + +.. function:: sched_yield() + + Voluntarily relinquish the CPU. + + +.. function:: sched_setaffinity(pid, mask) + + Restrict the process with PID *pid* (or the current process if zero) to a + set of CPUs. *mask* is an iterable of integers representing the set of + CPUs to which the process should be restricted. + + +.. function:: sched_getaffinity(pid) + + Return the set of CPUs the process with PID *pid* (or the current process + if zero) is restricted to. + + +.. _os-path: + +Miscellaneous System Information +-------------------------------- + + +.. function:: confstr(name) + + Return string-valued system configuration values. *name* specifies the + configuration value to retrieve; it may be a string which is the name of a + defined system value; these names are specified in a number of standards (POSIX, + Unix 95, Unix 98, and others). Some platforms define additional names as well. + The names known to the host operating system are given as the keys of the + ``confstr_names`` dictionary. For configuration variables not included in that + mapping, passing an integer for *name* is also accepted. + + If the configuration value specified by *name* isn't defined, ``None`` is + returned. + + If *name* is a string and is not known, :exc:`ValueError` is raised. If a + specific value for *name* is not supported by the host system, even if it is + included in ``confstr_names``, an :exc:`OSError` is raised with + :const:`errno.EINVAL` for the error number. + + .. availability:: Unix. + + +.. data:: confstr_names + + Dictionary mapping names accepted by :func:`confstr` to the integer values + defined for those names by the host operating system. This can be used to + determine the set of names known to the system. + + .. availability:: Unix. + + +.. function:: cpu_count() + + Return the number of CPUs in the system. Returns ``None`` if undetermined. + + This number is not equivalent to the number of CPUs the current process can + use. The number of usable CPUs can be obtained with + ``len(os.sched_getaffinity(0))`` + + + .. versionadded:: 3.4 + + +.. function:: getloadavg() + + Return the number of processes in the system run queue averaged over the last + 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was + unobtainable. + + .. availability:: Unix. + + +.. function:: sysconf(name) + + Return integer-valued system configuration values. If the configuration value + specified by *name* isn't defined, ``-1`` is returned. The comments regarding + the *name* parameter for :func:`confstr` apply here as well; the dictionary that + provides information on the known names is given by ``sysconf_names``. + + .. availability:: Unix. + + +.. data:: sysconf_names + + Dictionary mapping names accepted by :func:`sysconf` to the integer values + defined for those names by the host operating system. This can be used to + determine the set of names known to the system. + + .. availability:: Unix. + +The following data values are used to support path manipulation operations. These +are defined for all platforms. + +Higher-level operations on pathnames are defined in the :mod:`os.path` module. + + +.. index:: single: . (dot); in pathnames +.. data:: curdir + + The constant string used by the operating system to refer to the current + directory. This is ``'.'`` for Windows and POSIX. Also available via + :mod:`os.path`. + + +.. index:: single: ..; in pathnames +.. data:: pardir + + The constant string used by the operating system to refer to the parent + directory. This is ``'..'`` for Windows and POSIX. Also available via + :mod:`os.path`. + + +.. index:: single: / (slash); in pathnames +.. index:: single: \ (backslash); in pathnames (Windows) +.. data:: sep + + The character used by the operating system to separate pathname components. + This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this + is not sufficient to be able to parse or concatenate pathnames --- use + :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally + useful. Also available via :mod:`os.path`. + + +.. index:: single: / (slash); in pathnames +.. data:: altsep + + An alternative character used by the operating system to separate pathname + components, or ``None`` if only one separator character exists. This is set to + ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via + :mod:`os.path`. + + +.. index:: single: . (dot); in pathnames +.. data:: extsep + + The character which separates the base filename from the extension; for example, + the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`. + + +.. index:: single: : (colon); path separator (POSIX) + single: ; (semicolon) +.. data:: pathsep + + The character conventionally used by the operating system to separate search + path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for + Windows. Also available via :mod:`os.path`. + + +.. data:: defpath + + The default search path used by :func:`exec\*p\* ` and + :func:`spawn\*p\* ` if the environment doesn't have a ``'PATH'`` + key. Also available via :mod:`os.path`. + + +.. data:: linesep + + The string used to separate (or, rather, terminate) lines on the current + platform. This may be a single character, such as ``'\n'`` for POSIX, or + multiple characters, for example, ``'\r\n'`` for Windows. Do not use + *os.linesep* as a line terminator when writing files opened in text mode (the + default); use a single ``'\n'`` instead, on all platforms. + + +.. data:: devnull + + The file path of the null device. For example: ``'/dev/null'`` for + POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. + +.. data:: RTLD_LAZY + RTLD_NOW + RTLD_GLOBAL + RTLD_LOCAL + RTLD_NODELETE + RTLD_NOLOAD + RTLD_DEEPBIND + + Flags for use with the :func:`~sys.setdlopenflags` and + :func:`~sys.getdlopenflags` functions. See the Unix manual page + :manpage:`dlopen(3)` for what the different flags mean. + + .. versionadded:: 3.3 + + +Random numbers +-------------- + + +.. function:: getrandom(size, flags=0) + + Get up to *size* random bytes. The function can return less bytes than + requested. + + These bytes can be used to seed user-space random number generators or for + cryptographic purposes. + + ``getrandom()`` relies on entropy gathered from device drivers and other + sources of environmental noise. Unnecessarily reading large quantities of + data will have a negative impact on other users of the ``/dev/random`` and + ``/dev/urandom`` devices. + + The flags argument is a bit mask that can contain zero or more of the + following values ORed together: :py:data:`os.GRND_RANDOM` and + :py:data:`GRND_NONBLOCK`. + + See also the `Linux getrandom() manual page + `_. + + .. availability:: Linux 3.17 and newer. + + .. versionadded:: 3.6 + +.. function:: urandom(size) + + Return a string of *size* random bytes suitable for cryptographic use. + + This function returns random bytes from an OS-specific randomness source. The + returned data should be unpredictable enough for cryptographic applications, + though its exact quality depends on the OS implementation. + + On Linux, if the ``getrandom()`` syscall is available, it is used in + blocking mode: block until the system urandom entropy pool is initialized + (128 bits of entropy are collected by the kernel). See the :pep:`524` for + the rationale. On Linux, the :func:`getrandom` function can be used to get + random bytes in non-blocking mode (using the :data:`GRND_NONBLOCK` flag) or + to poll until the system urandom entropy pool is initialized. + + On a Unix-like system, random bytes are read from the ``/dev/urandom`` + device. If the ``/dev/urandom`` device is not available or not readable, the + :exc:`NotImplementedError` exception is raised. + + On Windows, it will use ``CryptGenRandom()``. + + .. seealso:: + The :mod:`secrets` module provides higher level functions. For an + easy-to-use interface to the random number generator provided by your + platform, please see :class:`random.SystemRandom`. + + .. versionchanged:: 3.6.0 + On Linux, ``getrandom()`` is now used in blocking mode to increase the + security. + + .. versionchanged:: 3.5.2 + On Linux, if the ``getrandom()`` syscall blocks (the urandom entropy pool + is not initialized yet), fall back on reading ``/dev/urandom``. + + .. versionchanged:: 3.5 + On Linux 3.17 and newer, the ``getrandom()`` syscall is now used + when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` + function is now used. These functions avoid the usage of an internal file + descriptor. + +.. data:: GRND_NONBLOCK + + By default, when reading from ``/dev/random``, :func:`getrandom` blocks if + no random bytes are available, and when reading from ``/dev/urandom``, it blocks + if the entropy pool has not yet been initialized. + + If the :py:data:`GRND_NONBLOCK` flag is set, then :func:`getrandom` does not + block in these cases, but instead immediately raises :exc:`BlockingIOError`. + + .. versionadded:: 3.6 + +.. data:: GRND_RANDOM + + If this bit is set, then random bytes are drawn from the + ``/dev/random`` pool instead of the ``/dev/urandom`` pool. + + .. versionadded:: 3.6 diff --git a/Doc/library/pty.rst.bak b/Doc/library/pty.rst.bak new file mode 100644 index 00000000000000..12268437d07e98 --- /dev/null +++ b/Doc/library/pty.rst.bak @@ -0,0 +1,114 @@ +:mod:`pty` --- Pseudo-terminal utilities +======================================== + +.. module:: pty + :platform: Linux + :synopsis: Pseudo-Terminal Handling for Linux. + +.. moduleauthor:: Steen Lumholt +.. sectionauthor:: Moshe Zadka + +**Source code:** :source:`Lib/pty.py` + +-------------- + +The :mod:`pty` module defines operations for handling the pseudo-terminal +concept: starting another process and being able to write to and read from its +controlling terminal programmatically. + +Because pseudo-terminal handling is highly platform dependent, there is code to +do it only for Linux. (The Linux code is supposed to work on other platforms, +but hasn't been tested yet.) + +The :mod:`pty` module defines the following functions: + + +.. function:: fork() + + Fork. Connect the child's controlling terminal to a pseudo-terminal. Return + value is ``(pid, fd)``. Note that the child gets *pid* 0, and the *fd* is + *invalid*. The parent's return value is the *pid* of the child, and *fd* is a + file descriptor connected to the child's controlling terminal (and also to the + child's standard input and output). + + +.. function:: openpty() + + Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or + emulation code for generic Unix systems. Return a pair of file descriptors + ``(master, slave)``, for the master and the slave end, respectively. + + +.. function:: spawn(argv[, master_read[, stdin_read]]) + + Spawn a process, and connect its controlling terminal with the current + process's standard io. This is often used to baffle programs which insist on + reading from the controlling terminal. It is expected that the process + spawned behind the pty will eventually terminate, and when it does *spawn* + will return. + + The functions *master_read* and *stdin_read* are passed a file descriptor + which they should read from, and they should always return a byte string. In + order to force spawn to return before the child process exits an + :exc:`OSError` should be thrown. + + The default implementation for both functions will read and return up to 1024 + bytes each time the function is called. The *master_read* callback is passed + the pseudoterminal’s master file descriptor to read output from the child + process, and *stdin_read* is passed file descriptor 0, to read from the + parent process's standard input. + + Returning an empty byte string from either callback is interpreted as an + end-of-file (EOF) condition, and that callback will not be called after + that. If *stdin_read* signals EOF the controlling terminal can no longer + communicate with the parent process OR the child process. Unless the child + process will quit without any input, *spawn* will then loop forever. If + *master_read* signals EOF the same behavior results (on linux at least). + + If both callbacks signal EOF then *spawn* will probably never return, unless + *select* throws an error on your platform when passed three empty lists. This + is a bug, documented in `issue 26228 `_. + + + .. versionchanged:: 3.4 + :func:`spawn` now returns the status value from :func:`os.waitpid` + on the child process. + +Example +------- + +.. sectionauthor:: Steen Lumholt + +The following program acts like the Unix command :manpage:`script(1)`, using a +pseudo-terminal to record all input and output of a terminal session in a +"typescript". :: + + import argparse + import os + import pty + import sys + import time + + parser = argparse.ArgumentParser() + parser.add_argument('-a', dest='append', action='store_true') + parser.add_argument('-p', dest='use_python', action='store_true') + parser.add_argument('filename', nargs='?', default='typescript') + options = parser.parse_args() + + shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh') + filename = options.filename + mode = 'ab' if options.append else 'wb' + + with open(filename, mode) as script: + def read(fd): + data = os.read(fd, 1024) + script.write(data) + return data + + print('Script started, file is', filename) + script.write(('Script started on %s\n' % time.asctime()).encode()) + + pty.spawn(shell, read) + + script.write(('Script done on %s\n' % time.asctime()).encode()) + print('Script done, file is', filename) diff --git a/Doc/library/stdtypes.rst.bak b/Doc/library/stdtypes.rst.bak new file mode 100644 index 00000000000000..fd3401fd18a099 --- /dev/null +++ b/Doc/library/stdtypes.rst.bak @@ -0,0 +1,4885 @@ +.. XXX: reference/datamodel and this have quite a few overlaps! + + +.. _bltin-types: + +************** +Built-in Types +************** + +The following sections describe the standard types that are built into the +interpreter. + +.. index:: pair: built-in; types + +The principal built-in types are numerics, sequences, mappings, classes, +instances and exceptions. + +Some collection classes are mutable. The methods that add, subtract, or +rearrange their members in place, and don't return a specific item, never return +the collection instance itself but ``None``. + +Some operations are supported by several object types; in particular, +practically all objects can be compared for equality, tested for truth +value, and converted to a string (with the :func:`repr` function or the +slightly different :func:`str` function). The latter function is implicitly +used when an object is written by the :func:`print` function. + + +.. _truth: + +Truth Value Testing +=================== + +.. index:: + statement: if + statement: while + pair: truth; value + pair: Boolean; operations + single: false + +Any object can be tested for truth value, for use in an :keyword:`if` or +:keyword:`while` condition or as operand of the Boolean operations below. + +.. index:: single: true + +By default, an object is considered true unless its class defines either a +:meth:`__bool__` method that returns ``False`` or a :meth:`__len__` method that +returns zero, when called with the object. [1]_ Here are most of the built-in +objects considered false: + + .. index:: + single: None (Built-in object) + single: False (Built-in object) + +* constants defined to be false: ``None`` and ``False``. + +* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``, + ``Fraction(0, 1)`` + +* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``, + ``range(0)`` + +.. index:: + operator: or + operator: and + single: False + single: True + +Operations and built-in functions that have a Boolean result always return ``0`` +or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated. +(Important exception: the Boolean operations ``or`` and ``and`` always return +one of their operands.) + + +.. _boolean: + +Boolean Operations --- :keyword:`!and`, :keyword:`!or`, :keyword:`!not` +======================================================================= + +.. index:: pair: Boolean; operations + +These are the Boolean operations, ordered by ascending priority: + ++-------------+---------------------------------+-------+ +| Operation | Result | Notes | ++=============+=================================+=======+ +| ``x or y`` | if *x* is false, then *y*, else | \(1) | +| | *x* | | ++-------------+---------------------------------+-------+ +| ``x and y`` | if *x* is false, then *x*, else | \(2) | +| | *y* | | ++-------------+---------------------------------+-------+ +| ``not x`` | if *x* is false, then ``True``, | \(3) | +| | else ``False`` | | ++-------------+---------------------------------+-------+ + +.. index:: + operator: and + operator: or + operator: not + +Notes: + +(1) + This is a short-circuit operator, so it only evaluates the second + argument if the first one is false. + +(2) + This is a short-circuit operator, so it only evaluates the second + argument if the first one is true. + +(3) + ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is + interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. + + +.. _stdcomparisons: + +Comparisons +=========== + +.. index:: + pair: chaining; comparisons + pair: operator; comparison + operator: == + operator: < (less) + operator: <= + operator: > (greater) + operator: >= + operator: != + operator: is + operator: is not + +There are eight comparison operations in Python. They all have the same +priority (which is higher than that of the Boolean operations). Comparisons can +be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and +y <= z``, except that *y* is evaluated only once (but in both cases *z* is not +evaluated at all when ``x < y`` is found to be false). + +This table summarizes the comparison operations: + ++------------+-------------------------+ +| Operation | Meaning | ++============+=========================+ +| ``<`` | strictly less than | ++------------+-------------------------+ +| ``<=`` | less than or equal | ++------------+-------------------------+ +| ``>`` | strictly greater than | ++------------+-------------------------+ +| ``>=`` | greater than or equal | ++------------+-------------------------+ +| ``==`` | equal | ++------------+-------------------------+ +| ``!=`` | not equal | ++------------+-------------------------+ +| ``is`` | object identity | ++------------+-------------------------+ +| ``is not`` | negated object identity | ++------------+-------------------------+ + +.. index:: + pair: object; numeric + pair: objects; comparing + +Objects of different types, except different numeric types, never compare equal. +The ``==`` operator is always defined but for some object types (for example, +class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` +operators are only defined where they make sense; for example, they raise a +:exc:`TypeError` exception when one of the arguments is a complex number. + +.. index:: + single: __eq__() (instance method) + single: __ne__() (instance method) + single: __lt__() (instance method) + single: __le__() (instance method) + single: __gt__() (instance method) + single: __ge__() (instance method) + +Non-identical instances of a class normally compare as non-equal unless the +class defines the :meth:`__eq__` method. + +Instances of a class cannot be ordered with respect to other instances of the +same class, or other types of object, unless the class defines enough of the +methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in +general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the +conventional meanings of the comparison operators). + +The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be +customized; also they can be applied to any two objects and never raise an +exception. + +.. index:: + operator: in + operator: not in + +Two more operations with the same syntactic priority, :keyword:`in` and +:keyword:`not in`, are supported by types that are :term:`iterable` or +implement the :meth:`__contains__` method. + +.. _typesnumeric: + +Numeric Types --- :class:`int`, :class:`float`, :class:`complex` +================================================================ + +.. index:: + object: numeric + object: Boolean + object: integer + object: floating point + object: complex number + pair: C; language + +There are three distinct numeric types: :dfn:`integers`, :dfn:`floating +point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a +subtype of integers. Integers have unlimited precision. Floating point +numbers are usually implemented using :c:type:`double` in C; information +about the precision and internal representation of floating point +numbers for the machine on which your program is running is available +in :data:`sys.float_info`. Complex numbers have a real and imaginary +part, which are each a floating point number. To extract these parts +from a complex number *z*, use ``z.real`` and ``z.imag``. (The standard +library includes the additional numeric types :mod:`fractions.Fraction`, for +rationals, and :mod:`decimal.Decimal`, for floating-point numbers with +user-definable precision.) + +.. index:: + pair: numeric; literals + pair: integer; literals + pair: floating point; literals + pair: complex number; literals + pair: hexadecimal; literals + pair: octal; literals + pair: binary; literals + +Numbers are created by numeric literals or as the result of built-in functions +and operators. Unadorned integer literals (including hex, octal and binary +numbers) yield integers. Numeric literals containing a decimal point or an +exponent sign yield floating point numbers. Appending ``'j'`` or ``'J'`` to a +numeric literal yields an imaginary number (a complex number with a zero real +part) which you can add to an integer or float to get a complex number with real +and imaginary parts. + +.. index:: + single: arithmetic + builtin: int + builtin: float + builtin: complex + single: operator; + (plus) + single: + (plus); unary operator + single: + (plus); binary operator + single: operator; - (minus) + single: - (minus); unary operator + single: - (minus); binary operator + operator: * (asterisk) + operator: / (slash) + operator: // + operator: % (percent) + operator: ** + +Python fully supports mixed arithmetic: when a binary arithmetic operator has +operands of different numeric types, the operand with the "narrower" type is +widened to that of the other, where integer is narrower than floating point, +which is narrower than complex. Comparisons between numbers of mixed type use +the same rule. [2]_ The constructors :func:`int`, :func:`float`, and +:func:`complex` can be used to produce numbers of a specific type. + +All numeric types (except complex) support the following operations (for priorities of +the operations, see :ref:`operator-summary`): + ++---------------------+---------------------------------+---------+--------------------+ +| Operation | Result | Notes | Full documentation | ++=====================+=================================+=========+====================+ +| ``x + y`` | sum of *x* and *y* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``x - y`` | difference of *x* and *y* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``x * y`` | product of *x* and *y* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``x / y`` | quotient of *x* and *y* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``x // y`` | floored quotient of *x* and | \(1) | | +| | *y* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``x % y`` | remainder of ``x / y`` | \(2) | | ++---------------------+---------------------------------+---------+--------------------+ +| ``-x`` | *x* negated | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``+x`` | *x* unchanged | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``abs(x)`` | absolute value or magnitude of | | :func:`abs` | +| | *x* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``int(x)`` | *x* converted to integer | \(3)\(6)| :func:`int` | ++---------------------+---------------------------------+---------+--------------------+ +| ``float(x)`` | *x* converted to floating point | \(4)\(6)| :func:`float` | ++---------------------+---------------------------------+---------+--------------------+ +| ``complex(re, im)`` | a complex number with real part | \(6) | :func:`complex` | +| | *re*, imaginary part *im*. | | | +| | *im* defaults to zero. | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``c.conjugate()`` | conjugate of the complex number | | | +| | *c* | | | ++---------------------+---------------------------------+---------+--------------------+ +| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | \(2) | :func:`divmod` | ++---------------------+---------------------------------+---------+--------------------+ +| ``pow(x, y)`` | *x* to the power *y* | \(5) | :func:`pow` | ++---------------------+---------------------------------+---------+--------------------+ +| ``x ** y`` | *x* to the power *y* | \(5) | | ++---------------------+---------------------------------+---------+--------------------+ + +.. index:: + triple: operations on; numeric; types + single: conjugate() (complex number method) + +Notes: + +(1) + Also referred to as integer division. The resultant value is a whole + integer, though the result's type is not necessarily int. The result is + always rounded towards minus infinity: ``1//2`` is ``0``, ``(-1)//2`` is + ``-1``, ``1//(-2)`` is ``-1``, and ``(-1)//(-2)`` is ``0``. + +(2) + Not for complex numbers. Instead convert to floats using :func:`abs` if + appropriate. + +(3) + .. index:: + module: math + single: floor() (in module math) + single: ceil() (in module math) + single: trunc() (in module math) + pair: numeric; conversions + pair: C; language + + Conversion from floating point to integer may round or truncate + as in C; see functions :func:`math.floor` and :func:`math.ceil` for + well-defined conversions. + +(4) + float also accepts the strings "nan" and "inf" with an optional prefix "+" + or "-" for Not a Number (NaN) and positive or negative infinity. + +(5) + Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for + programming languages. + +(6) + The numeric literals accepted include the digits ``0`` to ``9`` or any + Unicode equivalent (code points with the ``Nd`` property). + + See http://www.unicode.org/Public/12.1.0/ucd/extracted/DerivedNumericType.txt + for a complete list of code points with the ``Nd`` property. + + +All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include +the following operations: + ++--------------------+---------------------------------------------+ +| Operation | Result | ++====================+=============================================+ +| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` | +| x) ` | | ++--------------------+---------------------------------------------+ +| :func:`round(x[, | *x* rounded to *n* digits, | +| n]) ` | rounding half to even. If *n* is | +| | omitted, it defaults to 0. | ++--------------------+---------------------------------------------+ +| :func:`math.floor(\| the greatest :class:`~numbers.Integral` | +| x) ` | <= *x* | ++--------------------+---------------------------------------------+ +| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* | +| ` | | ++--------------------+---------------------------------------------+ + +For additional numeric operations see the :mod:`math` and :mod:`cmath` +modules. + +.. XXXJH exceptions: overflow (when? what operations?) zerodivision + + +.. _bitstring-ops: + +Bitwise Operations on Integer Types +----------------------------------- + +.. index:: + triple: operations on; integer; types + pair: bitwise; operations + pair: shifting; operations + pair: masking; operations + operator: | (vertical bar) + operator: ^ (caret) + operator: & (ampersand) + operator: << + operator: >> + operator: ~ (tilde) + +Bitwise operations only make sense for integers. The result of bitwise +operations is calculated as though carried out in two's complement with an +infinite number of sign bits. + +The priorities of the binary bitwise operations are all lower than the numeric +operations and higher than the comparisons; the unary operation ``~`` has the +same priority as the other unary numeric operations (``+`` and ``-``). + +This table lists the bitwise operations sorted in ascending priority: + ++------------+--------------------------------+----------+ +| Operation | Result | Notes | ++============+================================+==========+ +| ``x | y`` | bitwise :dfn:`or` of *x* and | \(4) | +| | *y* | | ++------------+--------------------------------+----------+ +| ``x ^ y`` | bitwise :dfn:`exclusive or` of | \(4) | +| | *x* and *y* | | ++------------+--------------------------------+----------+ +| ``x & y`` | bitwise :dfn:`and` of *x* and | \(4) | +| | *y* | | ++------------+--------------------------------+----------+ +| ``x << n`` | *x* shifted left by *n* bits | (1)(2) | ++------------+--------------------------------+----------+ +| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) | ++------------+--------------------------------+----------+ +| ``~x`` | the bits of *x* inverted | | ++------------+--------------------------------+----------+ + +Notes: + +(1) + Negative shift counts are illegal and cause a :exc:`ValueError` to be raised. + +(2) + A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)`` + without overflow check. + +(3) + A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without + overflow check. + +(4) + Performing these calculations with at least one extra sign extension bit in + a finite two's complement representation (a working bit-width of + ``1 + max(x.bit_length(), y.bit_length())`` or more) is sufficient to get the + same result as if there were an infinite number of sign bits. + + +Additional Methods on Integer Types +----------------------------------- + +The int type implements the :class:`numbers.Integral` :term:`abstract base +class`. In addition, it provides a few more methods: + +.. method:: int.bit_length() + + Return the number of bits necessary to represent an integer in binary, + excluding the sign and leading zeros:: + + >>> n = -37 + >>> bin(n) + '-0b100101' + >>> n.bit_length() + 6 + + More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the + unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``. + Equivalently, when ``abs(x)`` is small enough to have a correctly + rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``. + If ``x`` is zero, then ``x.bit_length()`` returns ``0``. + + Equivalent to:: + + def bit_length(self): + s = bin(self) # binary representation: bin(-37) --> '-0b100101' + s = s.lstrip('-0b') # remove leading zeros and minus sign + return len(s) # len('100101') --> 6 + + .. versionadded:: 3.1 + +.. method:: int.to_bytes(length, byteorder, \*, signed=False) + + Return an array of bytes representing an integer. + + >>> (1024).to_bytes(2, byteorder='big') + b'\x04\x00' + >>> (1024).to_bytes(10, byteorder='big') + b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00' + >>> (-1024).to_bytes(10, byteorder='big', signed=True) + b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00' + >>> x = 1000 + >>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little') + b'\xe8\x03' + + The integer is represented using *length* bytes. An :exc:`OverflowError` + is raised if the integer is not representable with the given number of + bytes. + + The *byteorder* argument determines the byte order used to represent the + integer. If *byteorder* is ``"big"``, the most significant byte is at the + beginning of the byte array. If *byteorder* is ``"little"``, the most + significant byte is at the end of the byte array. To request the native + byte order of the host system, use :data:`sys.byteorder` as the byte order + value. + + The *signed* argument determines whether two's complement is used to + represent the integer. If *signed* is ``False`` and a negative integer is + given, an :exc:`OverflowError` is raised. The default value for *signed* + is ``False``. + + .. versionadded:: 3.2 + +.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False) + + Return the integer represented by the given array of bytes. + + >>> int.from_bytes(b'\x00\x10', byteorder='big') + 16 + >>> int.from_bytes(b'\x00\x10', byteorder='little') + 4096 + >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True) + -1024 + >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False) + 64512 + >>> int.from_bytes([255, 0, 0], byteorder='big') + 16711680 + + The argument *bytes* must either be a :term:`bytes-like object` or an + iterable producing bytes. + + The *byteorder* argument determines the byte order used to represent the + integer. If *byteorder* is ``"big"``, the most significant byte is at the + beginning of the byte array. If *byteorder* is ``"little"``, the most + significant byte is at the end of the byte array. To request the native + byte order of the host system, use :data:`sys.byteorder` as the byte order + value. + + The *signed* argument indicates whether two's complement is used to + represent the integer. + + .. versionadded:: 3.2 + +.. method:: int.as_integer_ratio() + + Return a pair of integers whose ratio is exactly equal to the original + integer and with a positive denominator. The integer ratio of integers + (whole numbers) is always the integer as the numerator and ``1`` as the + denominator. + + .. versionadded:: 3.8 + +Additional Methods on Float +--------------------------- + +The float type implements the :class:`numbers.Real` :term:`abstract base +class`. float also has the following additional methods. + +.. method:: float.as_integer_ratio() + + Return a pair of integers whose ratio is exactly equal to the + original float and with a positive denominator. Raises + :exc:`OverflowError` on infinities and a :exc:`ValueError` on + NaNs. + +.. method:: float.is_integer() + + Return ``True`` if the float instance is finite with integral + value, and ``False`` otherwise:: + + >>> (-2.0).is_integer() + True + >>> (3.2).is_integer() + False + +Two methods support conversion to +and from hexadecimal strings. Since Python's floats are stored +internally as binary numbers, converting a float to or from a +*decimal* string usually involves a small rounding error. In +contrast, hexadecimal strings allow exact representation and +specification of floating-point numbers. This can be useful when +debugging, and in numerical work. + + +.. method:: float.hex() + + Return a representation of a floating-point number as a hexadecimal + string. For finite floating-point numbers, this representation + will always include a leading ``0x`` and a trailing ``p`` and + exponent. + + +.. classmethod:: float.fromhex(s) + + Class method to return the float represented by a hexadecimal + string *s*. The string *s* may have leading and trailing + whitespace. + + +Note that :meth:`float.hex` is an instance method, while +:meth:`float.fromhex` is a class method. + +A hexadecimal string takes the form:: + + [sign] ['0x'] integer ['.' fraction] ['p' exponent] + +where the optional ``sign`` may by either ``+`` or ``-``, ``integer`` +and ``fraction`` are strings of hexadecimal digits, and ``exponent`` +is a decimal integer with an optional leading sign. Case is not +significant, and there must be at least one hexadecimal digit in +either the integer or the fraction. This syntax is similar to the +syntax specified in section 6.4.4.2 of the C99 standard, and also to +the syntax used in Java 1.5 onwards. In particular, the output of +:meth:`float.hex` is usable as a hexadecimal floating-point literal in +C or Java code, and hexadecimal strings produced by C's ``%a`` format +character or Java's ``Double.toHexString`` are accepted by +:meth:`float.fromhex`. + + +Note that the exponent is written in decimal rather than hexadecimal, +and that it gives the power of 2 by which to multiply the coefficient. +For example, the hexadecimal string ``0x3.a7p10`` represents the +floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or +``3740.0``:: + + >>> float.fromhex('0x3.a7p10') + 3740.0 + + +Applying the reverse conversion to ``3740.0`` gives a different +hexadecimal string representing the same number:: + + >>> float.hex(3740.0) + '0x1.d380000000000p+11' + + +.. _numeric-hash: + +Hashing of numeric types +------------------------ + +For numbers ``x`` and ``y``, possibly of different types, it's a requirement +that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`__hash__` +method documentation for more details). For ease of implementation and +efficiency across a variety of numeric types (including :class:`int`, +:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`) +Python's hash for numeric types is based on a single mathematical function +that's defined for any rational number, and hence applies to all instances of +:class:`int` and :class:`fractions.Fraction`, and all finite instances of +:class:`float` and :class:`decimal.Decimal`. Essentially, this function is +given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is +made available to Python as the :attr:`modulus` attribute of +:data:`sys.hash_info`. + +.. impl-detail:: + + Currently, the prime used is ``P = 2**31 - 1`` on machines with 32-bit C + longs and ``P = 2**61 - 1`` on machines with 64-bit C longs. + +Here are the rules in detail: + +- If ``x = m / n`` is a nonnegative rational number and ``n`` is not divisible + by ``P``, define ``hash(x)`` as ``m * invmod(n, P) % P``, where ``invmod(n, + P)`` gives the inverse of ``n`` modulo ``P``. + +- If ``x = m / n`` is a nonnegative rational number and ``n`` is + divisible by ``P`` (but ``m`` is not) then ``n`` has no inverse + modulo ``P`` and the rule above doesn't apply; in this case define + ``hash(x)`` to be the constant value ``sys.hash_info.inf``. + +- If ``x = m / n`` is a negative rational number define ``hash(x)`` + as ``-hash(-x)``. If the resulting hash is ``-1``, replace it with + ``-2``. + +- The particular values ``sys.hash_info.inf``, ``-sys.hash_info.inf`` + and ``sys.hash_info.nan`` are used as hash values for positive + infinity, negative infinity, or nans (respectively). (All hashable + nans have the same hash value.) + +- For a :class:`complex` number ``z``, the hash values of the real + and imaginary parts are combined by computing ``hash(z.real) + + sys.hash_info.imag * hash(z.imag)``, reduced modulo + ``2**sys.hash_info.width`` so that it lies in + ``range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - + 1))``. Again, if the result is ``-1``, it's replaced with ``-2``. + + +To clarify the above rules, here's some example Python code, +equivalent to the built-in hash, for computing the hash of a rational +number, :class:`float`, or :class:`complex`:: + + + import sys, math + + def hash_fraction(m, n): + """Compute the hash of a rational number m / n. + + Assumes m and n are integers, with n positive. + Equivalent to hash(fractions.Fraction(m, n)). + + """ + P = sys.hash_info.modulus + # Remove common factors of P. (Unnecessary if m and n already coprime.) + while m % P == n % P == 0: + m, n = m // P, n // P + + if n % P == 0: + hash_value = sys.hash_info.inf + else: + # Fermat's Little Theorem: pow(n, P-1, P) is 1, so + # pow(n, P-2, P) gives the inverse of n modulo P. + hash_value = (abs(m) % P) * pow(n, P - 2, P) % P + if m < 0: + hash_value = -hash_value + if hash_value == -1: + hash_value = -2 + return hash_value + + def hash_float(x): + """Compute the hash of a float x.""" + + if math.isnan(x): + return sys.hash_info.nan + elif math.isinf(x): + return sys.hash_info.inf if x > 0 else -sys.hash_info.inf + else: + return hash_fraction(*x.as_integer_ratio()) + + def hash_complex(z): + """Compute the hash of a complex number z.""" + + hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag) + # do a signed reduction modulo 2**sys.hash_info.width + M = 2**(sys.hash_info.width - 1) + hash_value = (hash_value & (M - 1)) - (hash_value & M) + if hash_value == -1: + hash_value = -2 + return hash_value + +.. _typeiter: + +Iterator Types +============== + +.. index:: + single: iterator protocol + single: protocol; iterator + single: sequence; iteration + single: container; iteration over + +Python supports a concept of iteration over containers. This is implemented +using two distinct methods; these are used to allow user-defined classes to +support iteration. Sequences, described below in more detail, always support +the iteration methods. + +One method needs to be defined for container objects to provide iteration +support: + +.. XXX duplicated in reference/datamodel! + +.. method:: container.__iter__() + + Return an iterator object. The object is required to support the iterator + protocol described below. If a container supports different types of + iteration, additional methods can be provided to specifically request + iterators for those iteration types. (An example of an object supporting + multiple forms of iteration would be a tree structure which supports both + breadth-first and depth-first traversal.) This method corresponds to the + :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C + API. + +The iterator objects themselves are required to support the following two +methods, which together form the :dfn:`iterator protocol`: + + +.. method:: iterator.__iter__() + + Return the iterator object itself. This is required to allow both containers + and iterators to be used with the :keyword:`for` and :keyword:`in` statements. + This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for + Python objects in the Python/C API. + + +.. method:: iterator.__next__() + + Return the next item from the container. If there are no further items, raise + the :exc:`StopIteration` exception. This method corresponds to the + :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the + Python/C API. + +Python defines several iterator objects to support iteration over general and +specific sequence types, dictionaries, and other more specialized forms. The +specific types are not important beyond their implementation of the iterator +protocol. + +Once an iterator's :meth:`~iterator.__next__` method raises +:exc:`StopIteration`, it must continue to do so on subsequent calls. +Implementations that do not obey this property are deemed broken. + + +.. _generator-types: + +Generator Types +--------------- + +Python's :term:`generator`\s provide a convenient way to implement the iterator +protocol. If a container object's :meth:`__iter__` method is implemented as a +generator, it will automatically return an iterator object (technically, a +generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__` +methods. +More information about generators can be found in :ref:`the documentation for +the yield expression `. + + +.. _typesseq: + +Sequence Types --- :class:`list`, :class:`tuple`, :class:`range` +================================================================ + +There are three basic sequence types: lists, tuples, and range objects. +Additional sequence types tailored for processing of +:ref:`binary data ` and :ref:`text strings ` are +described in dedicated sections. + + +.. _typesseq-common: + +Common Sequence Operations +-------------------------- + +.. index:: object: sequence + +The operations in the following table are supported by most sequence types, +both mutable and immutable. The :class:`collections.abc.Sequence` ABC is +provided to make it easier to correctly implement these operations on +custom sequence types. + +This table lists the sequence operations sorted in ascending priority. In the +table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are +integers and *x* is an arbitrary object that meets any type and value +restrictions imposed by *s*. + +The ``in`` and ``not in`` operations have the same priorities as the +comparison operations. The ``+`` (concatenation) and ``*`` (repetition) +operations have the same priority as the corresponding numeric operations. [3]_ + +.. index:: + triple: operations on; sequence; types + builtin: len + builtin: min + builtin: max + pair: concatenation; operation + pair: repetition; operation + pair: subscript; operation + pair: slice; operation + operator: in + operator: not in + single: count() (sequence method) + single: index() (sequence method) + ++--------------------------+--------------------------------+----------+ +| Operation | Result | Notes | ++==========================+================================+==========+ +| ``x in s`` | ``True`` if an item of *s* is | \(1) | +| | equal to *x*, else ``False`` | | ++--------------------------+--------------------------------+----------+ +| ``x not in s`` | ``False`` if an item of *s* is | \(1) | +| | equal to *x*, else ``True`` | | ++--------------------------+--------------------------------+----------+ +| ``s + t`` | the concatenation of *s* and | (6)(7) | +| | *t* | | ++--------------------------+--------------------------------+----------+ +| ``s * n`` or | equivalent to adding *s* to | (2)(7) | +| ``n * s`` | itself *n* times | | ++--------------------------+--------------------------------+----------+ +| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) | ++--------------------------+--------------------------------+----------+ +| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) | ++--------------------------+--------------------------------+----------+ +| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) | +| | with step *k* | | ++--------------------------+--------------------------------+----------+ +| ``len(s)`` | length of *s* | | ++--------------------------+--------------------------------+----------+ +| ``min(s)`` | smallest item of *s* | | ++--------------------------+--------------------------------+----------+ +| ``max(s)`` | largest item of *s* | | ++--------------------------+--------------------------------+----------+ +| ``s.index(x[, i[, j]])`` | index of the first occurrence | \(8) | +| | of *x* in *s* (at or after | | +| | index *i* and before index *j*)| | ++--------------------------+--------------------------------+----------+ +| ``s.count(x)`` | total number of occurrences of | | +| | *x* in *s* | | ++--------------------------+--------------------------------+----------+ + +Sequences of the same type also support comparisons. In particular, tuples +and lists are compared lexicographically by comparing corresponding elements. +This means that to compare equal, every element must compare equal and the +two sequences must be of the same type and have the same length. (For full +details see :ref:`comparisons` in the language reference.) + +Notes: + +(1) + While the ``in`` and ``not in`` operations are used only for simple + containment testing in the general case, some specialised sequences + (such as :class:`str`, :class:`bytes` and :class:`bytearray`) also use + them for subsequence testing:: + + >>> "gg" in "eggs" + True + +(2) + Values of *n* less than ``0`` are treated as ``0`` (which yields an empty + sequence of the same type as *s*). Note that items in the sequence *s* + are not copied; they are referenced multiple times. This often haunts + new Python programmers; consider:: + + >>> lists = [[]] * 3 + >>> lists + [[], [], []] + >>> lists[0].append(3) + >>> lists + [[3], [3], [3]] + + What has happened is that ``[[]]`` is a one-element list containing an empty + list, so all three elements of ``[[]] * 3`` are references to this single empty + list. Modifying any of the elements of ``lists`` modifies this single list. + You can create a list of different lists this way:: + + >>> lists = [[] for i in range(3)] + >>> lists[0].append(3) + >>> lists[1].append(5) + >>> lists[2].append(7) + >>> lists + [[3], [5], [7]] + + Further explanation is available in the FAQ entry + :ref:`faq-multidimensional-list`. + +(3) + If *i* or *j* is negative, the index is relative to the end of sequence *s*: + ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is + still ``0``. + +(4) + The slice of *s* from *i* to *j* is defined as the sequence of items with index + *k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use + ``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or + ``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is + empty. + +(5) + The slice of *s* from *i* to *j* with step *k* is defined as the sequence of + items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words, + the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when + *j* is reached (but never including *j*). When *k* is positive, + *i* and *j* are reduced to ``len(s)`` if they are greater. + When *k* is negative, *i* and *j* are reduced to ``len(s) - 1`` if + they are greater. If *i* or *j* are omitted or ``None``, they become + "end" values (which end depends on the sign of *k*). Note, *k* cannot be zero. + If *k* is ``None``, it is treated like ``1``. + +(6) + Concatenating immutable sequences always results in a new object. This + means that building up a sequence by repeated concatenation will have a + quadratic runtime cost in the total sequence length. To get a linear + runtime cost, you must switch to one of the alternatives below: + + * if concatenating :class:`str` objects, you can build a list and use + :meth:`str.join` at the end or else write to an :class:`io.StringIO` + instance and retrieve its value when complete + + * if concatenating :class:`bytes` objects, you can similarly use + :meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place + concatenation with a :class:`bytearray` object. :class:`bytearray` + objects are mutable and have an efficient overallocation mechanism + + * if concatenating :class:`tuple` objects, extend a :class:`list` instead + + * for other types, investigate the relevant class documentation + + +(7) + Some sequence types (such as :class:`range`) only support item sequences + that follow specific patterns, and hence don't support sequence + concatenation or repetition. + +(8) + ``index`` raises :exc:`ValueError` when *x* is not found in *s*. + Not all implementations support passing the additional arguments *i* and *j*. + These arguments allow efficient searching of subsections of the sequence. Passing + the extra arguments is roughly equivalent to using ``s[i:j].index(x)``, only + without copying any data and with the returned index being relative to + the start of the sequence rather than the start of the slice. + + +.. _typesseq-immutable: + +Immutable Sequence Types +------------------------ + +.. index:: + triple: immutable; sequence; types + object: tuple + builtin: hash + +The only operation that immutable sequence types generally implement that is +not also implemented by mutable sequence types is support for the :func:`hash` +built-in. + +This support allows immutable sequences, such as :class:`tuple` instances, to +be used as :class:`dict` keys and stored in :class:`set` and :class:`frozenset` +instances. + +Attempting to hash an immutable sequence that contains unhashable values will +result in :exc:`TypeError`. + + +.. _typesseq-mutable: + +Mutable Sequence Types +---------------------- + +.. index:: + triple: mutable; sequence; types + object: list + object: bytearray + +The operations in the following table are defined on mutable sequence types. +The :class:`collections.abc.MutableSequence` ABC is provided to make it +easier to correctly implement these operations on custom sequence types. + +In the table *s* is an instance of a mutable sequence type, *t* is any +iterable object and *x* is an arbitrary object that meets any type +and value restrictions imposed by *s* (for example, :class:`bytearray` only +accepts integers that meet the value restriction ``0 <= x <= 255``). + + +.. index:: + triple: operations on; sequence; types + triple: operations on; list; type + pair: subscript; assignment + pair: slice; assignment + statement: del + single: append() (sequence method) + single: clear() (sequence method) + single: copy() (sequence method) + single: extend() (sequence method) + single: insert() (sequence method) + single: pop() (sequence method) + single: remove() (sequence method) + single: reverse() (sequence method) + ++------------------------------+--------------------------------+---------------------+ +| Operation | Result | Notes | ++==============================+================================+=====================+ +| ``s[i] = x`` | item *i* of *s* is replaced by | | +| | *x* | | ++------------------------------+--------------------------------+---------------------+ +| ``s[i:j] = t`` | slice of *s* from *i* to *j* | | +| | is replaced by the contents of | | +| | the iterable *t* | | ++------------------------------+--------------------------------+---------------------+ +| ``del s[i:j]`` | same as ``s[i:j] = []`` | | ++------------------------------+--------------------------------+---------------------+ +| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) | +| | are replaced by those of *t* | | ++------------------------------+--------------------------------+---------------------+ +| ``del s[i:j:k]`` | removes the elements of | | +| | ``s[i:j:k]`` from the list | | ++------------------------------+--------------------------------+---------------------+ +| ``s.append(x)`` | appends *x* to the end of the | | +| | sequence (same as | | +| | ``s[len(s):len(s)] = [x]``) | | ++------------------------------+--------------------------------+---------------------+ +| ``s.clear()`` | removes all items from *s* | \(5) | +| | (same as ``del s[:]``) | | ++------------------------------+--------------------------------+---------------------+ +| ``s.copy()`` | creates a shallow copy of *s* | \(5) | +| | (same as ``s[:]``) | | ++------------------------------+--------------------------------+---------------------+ +| ``s.extend(t)`` or | extends *s* with the | | +| ``s += t`` | contents of *t* (for the | | +| | most part the same as | | +| | ``s[len(s):len(s)] = t``) | | ++------------------------------+--------------------------------+---------------------+ +| ``s *= n`` | updates *s* with its contents | \(6) | +| | repeated *n* times | | ++------------------------------+--------------------------------+---------------------+ +| ``s.insert(i, x)`` | inserts *x* into *s* at the | | +| | index given by *i* | | +| | (same as ``s[i:i] = [x]``) | | ++------------------------------+--------------------------------+---------------------+ +| ``s.pop([i])`` | retrieves the item at *i* and | \(2) | +| | also removes it from *s* | | ++------------------------------+--------------------------------+---------------------+ +| ``s.remove(x)`` | remove the first item from *s* | \(3) | +| | where ``s[i]`` is equal to *x* | | ++------------------------------+--------------------------------+---------------------+ +| ``s.reverse()`` | reverses the items of *s* in | \(4) | +| | place | | ++------------------------------+--------------------------------+---------------------+ + + +Notes: + +(1) + *t* must have the same length as the slice it is replacing. + +(2) + The optional argument *i* defaults to ``-1``, so that by default the last + item is removed and returned. + +(3) + :meth:`remove` raises :exc:`ValueError` when *x* is not found in *s*. + +(4) + The :meth:`reverse` method modifies the sequence in place for economy of + space when reversing a large sequence. To remind users that it operates by + side effect, it does not return the reversed sequence. + +(5) + :meth:`clear` and :meth:`!copy` are included for consistency with the + interfaces of mutable containers that don't support slicing operations + (such as :class:`dict` and :class:`set`). :meth:`!copy` is not part of the + :class:`collections.abc.MutableSequence` ABC, but most concrete + mutable sequence classes provide it. + + .. versionadded:: 3.3 + :meth:`clear` and :meth:`!copy` methods. + +(6) + The value *n* is an integer, or an object implementing + :meth:`~object.__index__`. Zero and negative values of *n* clear + the sequence. Items in the sequence are not copied; they are referenced + multiple times, as explained for ``s * n`` under :ref:`typesseq-common`. + + +.. _typesseq-list: + +Lists +----- + +.. index:: object: list + +Lists are mutable sequences, typically used to store collections of +homogeneous items (where the precise degree of similarity will vary by +application). + +.. class:: list([iterable]) + + Lists may be constructed in several ways: + + * Using a pair of square brackets to denote the empty list: ``[]`` + * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]`` + * Using a list comprehension: ``[x for x in iterable]`` + * Using the type constructor: ``list()`` or ``list(iterable)`` + + The constructor builds a list whose items are the same and in the same + order as *iterable*'s items. *iterable* may be either a sequence, a + container that supports iteration, or an iterator object. If *iterable* + is already a list, a copy is made and returned, similar to ``iterable[:]``. + For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and + ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. + If no argument is given, the constructor creates a new empty list, ``[]``. + + + Many other operations also produce lists, including the :func:`sorted` + built-in. + + Lists implement all of the :ref:`common ` and + :ref:`mutable ` sequence operations. Lists also provide the + following additional method: + + .. method:: list.sort(*, key=None, reverse=False) + + This method sorts the list in place, using only ``<`` comparisons + between items. Exceptions are not suppressed - if any comparison operations + fail, the entire sort operation will fail (and the list will likely be left + in a partially modified state). + + :meth:`sort` accepts two arguments that can only be passed by keyword + (:ref:`keyword-only arguments `): + + *key* specifies a function of one argument that is used to extract a + comparison key from each list element (for example, ``key=str.lower``). + The key corresponding to each item in the list is calculated once and + then used for the entire sorting process. The default value of ``None`` + means that list items are sorted directly without calculating a separate + key value. + + The :func:`functools.cmp_to_key` utility is available to convert a 2.x + style *cmp* function to a *key* function. + + *reverse* is a boolean value. If set to ``True``, then the list elements + are sorted as if each comparison were reversed. + + This method modifies the sequence in place for economy of space when + sorting a large sequence. To remind users that it operates by side + effect, it does not return the sorted sequence (use :func:`sorted` to + explicitly request a new sorted list instance). + + The :meth:`sort` method is guaranteed to be stable. A sort is stable if it + guarantees not to change the relative order of elements that compare equal + --- this is helpful for sorting in multiple passes (for example, sort by + department, then by salary grade). + + For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. + + .. impl-detail:: + + While a list is being sorted, the effect of attempting to mutate, or even + inspect, the list is undefined. The C implementation of Python makes the + list appear empty for the duration, and raises :exc:`ValueError` if it can + detect that the list has been mutated during a sort. + + +.. _typesseq-tuple: + +Tuples +------ + +.. index:: object: tuple + +Tuples are immutable sequences, typically used to store collections of +heterogeneous data (such as the 2-tuples produced by the :func:`enumerate` +built-in). Tuples are also used for cases where an immutable sequence of +homogeneous data is needed (such as allowing storage in a :class:`set` or +:class:`dict` instance). + +.. class:: tuple([iterable]) + + Tuples may be constructed in a number of ways: + + * Using a pair of parentheses to denote the empty tuple: ``()`` + * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)`` + * Separating items with commas: ``a, b, c`` or ``(a, b, c)`` + * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)`` + + The constructor builds a tuple whose items are the same and in the same + order as *iterable*'s items. *iterable* may be either a sequence, a + container that supports iteration, or an iterator object. If *iterable* + is already a tuple, it is returned unchanged. For example, + ``tuple('abc')`` returns ``('a', 'b', 'c')`` and + ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``. + If no argument is given, the constructor creates a new empty tuple, ``()``. + + Note that it is actually the comma which makes a tuple, not the parentheses. + The parentheses are optional, except in the empty tuple case, or + when they are needed to avoid syntactic ambiguity. For example, + ``f(a, b, c)`` is a function call with three arguments, while + ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument. + + Tuples implement all of the :ref:`common ` sequence + operations. + +For heterogeneous collections of data where access by name is clearer than +access by index, :func:`collections.namedtuple` may be a more appropriate +choice than a simple tuple object. + + +.. _typesseq-range: + +Ranges +------ + +.. index:: object: range + +The :class:`range` type represents an immutable sequence of numbers and is +commonly used for looping a specific number of times in :keyword:`for` +loops. + +.. class:: range(stop) + range(start, stop[, step]) + + The arguments to the range constructor must be integers (either built-in + :class:`int` or any object that implements the ``__index__`` special + method). If the *step* argument is omitted, it defaults to ``1``. + If the *start* argument is omitted, it defaults to ``0``. + If *step* is zero, :exc:`ValueError` is raised. + + For a positive *step*, the contents of a range ``r`` are determined by the + formula ``r[i] = start + step*i`` where ``i >= 0`` and + ``r[i] < stop``. + + For a negative *step*, the contents of the range are still determined by + the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0`` + and ``r[i] > stop``. + + A range object will be empty if ``r[0]`` does not meet the value + constraint. Ranges do support negative indices, but these are interpreted + as indexing from the end of the sequence determined by the positive + indices. + + Ranges containing absolute values larger than :data:`sys.maxsize` are + permitted but some features (such as :func:`len`) may raise + :exc:`OverflowError`. + + Range examples:: + + >>> list(range(10)) + [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] + >>> list(range(1, 11)) + [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] + >>> list(range(0, 30, 5)) + [0, 5, 10, 15, 20, 25] + >>> list(range(0, 10, 3)) + [0, 3, 6, 9] + >>> list(range(0, -10, -1)) + [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] + >>> list(range(0)) + [] + >>> list(range(1, 0)) + [] + + Ranges implement all of the :ref:`common ` sequence operations + except concatenation and repetition (due to the fact that range objects can + only represent sequences that follow a strict pattern and repetition and + concatenation will usually violate that pattern). + + .. attribute:: start + + The value of the *start* parameter (or ``0`` if the parameter was + not supplied) + + .. attribute:: stop + + The value of the *stop* parameter + + .. attribute:: step + + The value of the *step* parameter (or ``1`` if the parameter was + not supplied) + +The advantage of the :class:`range` type over a regular :class:`list` or +:class:`tuple` is that a :class:`range` object will always take the same +(small) amount of memory, no matter the size of the range it represents (as it +only stores the ``start``, ``stop`` and ``step`` values, calculating individual +items and subranges as needed). + +Range objects implement the :class:`collections.abc.Sequence` ABC, and provide +features such as containment tests, element index lookup, slicing and +support for negative indices (see :ref:`typesseq`): + + >>> r = range(0, 20, 2) + >>> r + range(0, 20, 2) + >>> 11 in r + False + >>> 10 in r + True + >>> r.index(10) + 5 + >>> r[5] + 10 + >>> r[:5] + range(0, 10, 2) + >>> r[-1] + 18 + +Testing range objects for equality with ``==`` and ``!=`` compares +them as sequences. That is, two range objects are considered equal if +they represent the same sequence of values. (Note that two range +objects that compare equal might have different :attr:`~range.start`, +:attr:`~range.stop` and :attr:`~range.step` attributes, for example +``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) + +.. versionchanged:: 3.2 + Implement the Sequence ABC. + Support slicing and negative indices. + Test :class:`int` objects for membership in constant time instead of + iterating through all items. + +.. versionchanged:: 3.3 + Define '==' and '!=' to compare range objects based on the + sequence of values they define (instead of comparing based on + object identity). + +.. versionadded:: 3.3 + The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step` + attributes. + +.. seealso:: + + * The `linspace recipe `_ + shows how to implement a lazy version of range suitable for floating + point applications. + +.. index:: + single: string; text sequence type + single: str (built-in class); (see also string) + object: string + +.. _textseq: + +Text Sequence Type --- :class:`str` +=================================== + +Textual data in Python is handled with :class:`str` objects, or :dfn:`strings`. +Strings are immutable +:ref:`sequences ` of Unicode code points. String literals are +written in a variety of ways: + +* Single quotes: ``'allows embedded "double" quotes'`` +* Double quotes: ``"allows embedded 'single' quotes"``. +* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""`` + +Triple quoted strings may span multiple lines - all associated whitespace will +be included in the string literal. + +String literals that are part of a single expression and have only whitespace +between them will be implicitly converted to a single string literal. That +is, ``("spam " "eggs") == "spam eggs"``. + +See :ref:`strings` for more about the various forms of string literal, +including supported escape sequences, and the ``r`` ("raw") prefix that +disables most escape sequence processing. + +Strings may also be created from other objects using the :class:`str` +constructor. + +Since there is no separate "character" type, indexing a string produces +strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``. + +.. index:: + object: io.StringIO + +There is also no mutable string type, but :meth:`str.join` or +:class:`io.StringIO` can be used to efficiently construct strings from +multiple fragments. + +.. versionchanged:: 3.3 + For backwards compatibility with the Python 2 series, the ``u`` prefix is + once again permitted on string literals. It has no effect on the meaning + of string literals and cannot be combined with the ``r`` prefix. + + +.. index:: + single: string; str (built-in class) + +.. class:: str(object='') + str(object=b'', encoding='utf-8', errors='strict') + + Return a :ref:`string ` version of *object*. If *object* is not + provided, returns the empty string. Otherwise, the behavior of ``str()`` + depends on whether *encoding* or *errors* is given, as follows. + + If neither *encoding* nor *errors* is given, ``str(object)`` returns + :meth:`object.__str__() `, which is the "informal" or nicely + printable string representation of *object*. For string objects, this is + the string itself. If *object* does not have a :meth:`~object.__str__` + method, then :func:`str` falls back to returning + :meth:`repr(object) `. + + .. index:: + single: buffer protocol; str (built-in class) + single: bytes; str (built-in class) + + If at least one of *encoding* or *errors* is given, *object* should be a + :term:`bytes-like object` (e.g. :class:`bytes` or :class:`bytearray`). In + this case, if *object* is a :class:`bytes` (or :class:`bytearray`) object, + then ``str(bytes, encoding, errors)`` is equivalent to + :meth:`bytes.decode(encoding, errors) `. Otherwise, the bytes + object underlying the buffer object is obtained before calling + :meth:`bytes.decode`. See :ref:`binaryseq` and + :ref:`bufferobjects` for information on buffer objects. + + Passing a :class:`bytes` object to :func:`str` without the *encoding* + or *errors* arguments falls under the first case of returning the informal + string representation (see also the :option:`-b` command-line option to + Python). For example:: + + >>> str(b'Zoot!') + "b'Zoot!'" + + For more information on the ``str`` class and its methods, see + :ref:`textseq` and the :ref:`string-methods` section below. To output + formatted strings, see the :ref:`f-strings` and :ref:`formatstrings` + sections. In addition, see the :ref:`stringservices` section. + + +.. index:: + pair: string; methods + +.. _string-methods: + +String Methods +-------------- + +.. index:: + module: re + +Strings implement all of the :ref:`common ` sequence +operations, along with the additional methods described below. + +Strings also support two styles of string formatting, one providing a large +degree of flexibility and customization (see :meth:`str.format`, +:ref:`formatstrings` and :ref:`string-formatting`) and the other based on C +``printf`` style formatting that handles a narrower range of types and is +slightly harder to use correctly, but is often faster for the cases it can +handle (:ref:`old-string-formatting`). + +The :ref:`textservices` section of the standard library covers a number of +other modules that provide various text related utilities (including regular +expression support in the :mod:`re` module). + +.. method:: str.capitalize() + + Return a copy of the string with its first character capitalized and the + rest lowercased. + + .. versionchanged:: 3.8 + The first character is now put into titlecase rather than uppercase. + This means that characters like digraphs will only have their first + letter capitalized, instead of the full character. + +.. method:: str.casefold() + + Return a casefolded copy of the string. Casefolded strings may be used for + caseless matching. + + Casefolding is similar to lowercasing but more aggressive because it is + intended to remove all case distinctions in a string. For example, the German + lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already + lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` + converts it to ``"ss"``. + + The casefolding algorithm is described in section 3.13 of the Unicode + Standard. + + .. versionadded:: 3.3 + + +.. method:: str.center(width[, fillchar]) + + Return centered in a string of length *width*. Padding is done using the + specified *fillchar* (default is an ASCII space). The original string is + returned if *width* is less than or equal to ``len(s)``. + + + +.. method:: str.count(sub[, start[, end]]) + + Return the number of non-overlapping occurrences of substring *sub* in the + range [*start*, *end*]. Optional arguments *start* and *end* are + interpreted as in slice notation. + + +.. method:: str.encode(encoding="utf-8", errors="strict") + + Return an encoded version of the string as a bytes object. Default encoding + is ``'utf-8'``. *errors* may be given to set a different error handling scheme. + The default for *errors* is ``'strict'``, meaning that encoding errors raise + a :exc:`UnicodeError`. Other possible + values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, + ``'backslashreplace'`` and any other name registered via + :func:`codecs.register_error`, see section :ref:`error-handlers`. For a + list of possible encodings, see section :ref:`standard-encodings`. + + By default, the *errors* argument is not checked for best performances, but + only used at the first encoding error. Enable the :ref:`Python Development + Mode `, or use a debug build to check *errors*. + + .. versionchanged:: 3.1 + Support for keyword arguments added. + + .. versionchanged:: 3.9 + The *errors* is now checked in development mode and in debug mode. + + +.. method:: str.endswith(suffix[, start[, end]]) + + Return ``True`` if the string ends with the specified *suffix*, otherwise return + ``False``. *suffix* can also be a tuple of suffixes to look for. With optional + *start*, test beginning at that position. With optional *end*, stop comparing + at that position. + + +.. method:: str.expandtabs(tabsize=8) + + Return a copy of the string where all tab characters are replaced by one or + more spaces, depending on the current column and the given tab size. Tab + positions occur every *tabsize* characters (default is 8, giving tab + positions at columns 0, 8, 16 and so on). To expand the string, the current + column is set to zero and the string is examined character by character. If + the character is a tab (``\t``), one or more space characters are inserted + in the result until the current column is equal to the next tab position. + (The tab character itself is not copied.) If the character is a newline + (``\n``) or return (``\r``), it is copied and the current column is reset to + zero. Any other character is copied unchanged and the current column is + incremented by one regardless of how the character is represented when + printed. + + >>> '01\t012\t0123\t01234'.expandtabs() + '01 012 0123 01234' + >>> '01\t012\t0123\t01234'.expandtabs(4) + '01 012 0123 01234' + + +.. method:: str.find(sub[, start[, end]]) + + Return the lowest index in the string where substring *sub* is found within + the slice ``s[start:end]``. Optional arguments *start* and *end* are + interpreted as in slice notation. Return ``-1`` if *sub* is not found. + + .. note:: + + The :meth:`~str.find` method should be used only if you need to know the + position of *sub*. To check if *sub* is a substring or not, use the + :keyword:`in` operator:: + + >>> 'Py' in 'Python' + True + + +.. method:: str.format(*args, **kwargs) + + Perform a string formatting operation. The string on which this method is + called can contain literal text or replacement fields delimited by braces + ``{}``. Each replacement field contains either the numeric index of a + positional argument, or the name of a keyword argument. Returns a copy of + the string where each replacement field is replaced with the string value of + the corresponding argument. + + >>> "The sum of 1 + 2 is {0}".format(1+2) + 'The sum of 1 + 2 is 3' + + See :ref:`formatstrings` for a description of the various formatting options + that can be specified in format strings. + + .. note:: + When formatting a number (:class:`int`, :class:`float`, :class:`complex`, + :class:`decimal.Decimal` and subclasses) with the ``n`` type + (ex: ``'{:n}'.format(1234)``), the function temporarily sets the + ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale to decode + ``decimal_point`` and ``thousands_sep`` fields of :c:func:`localeconv` if + they are non-ASCII or longer than 1 byte, and the ``LC_NUMERIC`` locale is + different than the ``LC_CTYPE`` locale. This temporary change affects + other threads. + + .. versionchanged:: 3.7 + When formatting a number with the ``n`` type, the function sets + temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale in some + cases. + + +.. method:: str.format_map(mapping) + + Similar to ``str.format(**mapping)``, except that ``mapping`` is + used directly and not copied to a :class:`dict`. This is useful + if for example ``mapping`` is a dict subclass: + + >>> class Default(dict): + ... def __missing__(self, key): + ... return key + ... + >>> '{name} was born in {country}'.format_map(Default(name='Guido')) + 'Guido was born in country' + + .. versionadded:: 3.2 + + +.. method:: str.index(sub[, start[, end]]) + + Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is + not found. + + +.. method:: str.isalnum() + + Return ``True`` if all characters in the string are alphanumeric and there is at + least one character, ``False`` otherwise. A character ``c`` is alphanumeric if one + of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, + ``c.isdigit()``, or ``c.isnumeric()``. + + +.. method:: str.isalpha() + + Return ``True`` if all characters in the string are alphabetic and there is at least + one character, ``False`` otherwise. Alphabetic characters are those characters defined + in the Unicode character database as "Letter", i.e., those with general category + property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different + from the "Alphabetic" property defined in the Unicode Standard. + + +.. method:: str.isascii() + + Return ``True`` if the string is empty or all characters in the string are ASCII, + ``False`` otherwise. + ASCII characters have code points in the range U+0000-U+007F. + + .. versionadded:: 3.7 + + +.. method:: str.isdecimal() + + Return ``True`` if all characters in the string are decimal + characters and there is at least one character, ``False`` + otherwise. Decimal characters are those that can be used to form + numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT + ZERO. Formally a decimal character is a character in the Unicode + General Category "Nd". + + +.. method:: str.isdigit() + + Return ``True`` if all characters in the string are digits and there is at least one + character, ``False`` otherwise. Digits include decimal characters and digits that need + special handling, such as the compatibility superscript digits. + This covers digits which cannot be used to form numbers in base 10, + like the Kharosthi numbers. Formally, a digit is a character that has the + property value Numeric_Type=Digit or Numeric_Type=Decimal. + + +.. method:: str.isidentifier() + + Return ``True`` if the string is a valid identifier according to the language + definition, section :ref:`identifiers`. + + Call :func:`keyword.iskeyword` to test whether string ``s`` is a reserved + identifier, such as :keyword:`def` and :keyword:`class`. + + Example: + :: + + >>> from keyword import iskeyword + + >>> 'hello'.isidentifier(), iskeyword('hello') + True, False + >>> 'def'.isidentifier(), iskeyword('def') + True, True + + +.. method:: str.islower() + + Return ``True`` if all cased characters [4]_ in the string are lowercase and + there is at least one cased character, ``False`` otherwise. + + +.. method:: str.isnumeric() + + Return ``True`` if all characters in the string are numeric + characters, and there is at least one character, ``False`` + otherwise. Numeric characters include digit characters, and all characters + that have the Unicode numeric value property, e.g. U+2155, + VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property + value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric. + + +.. method:: str.isprintable() + + Return ``True`` if all characters in the string are printable or the string is + empty, ``False`` otherwise. Nonprintable characters are those characters defined + in the Unicode character database as "Other" or "Separator", excepting the + ASCII space (0x20) which is considered printable. (Note that printable + characters in this context are those which should not be escaped when + :func:`repr` is invoked on a string. It has no bearing on the handling of + strings written to :data:`sys.stdout` or :data:`sys.stderr`.) + + +.. method:: str.isspace() + + Return ``True`` if there are only whitespace characters in the string and there is + at least one character, ``False`` otherwise. + + A character is *whitespace* if in the Unicode character database + (see :mod:`unicodedata`), either its general category is ``Zs`` + ("Separator, space"), or its bidirectional class is one of ``WS``, + ``B``, or ``S``. + + +.. method:: str.istitle() + + Return ``True`` if the string is a titlecased string and there is at least one + character, for example uppercase characters may only follow uncased characters + and lowercase characters only cased ones. Return ``False`` otherwise. + + +.. method:: str.isupper() + + Return ``True`` if all cased characters [4]_ in the string are uppercase and + there is at least one cased character, ``False`` otherwise. + + >>> 'BANANA'.isupper() + True + >>> 'banana'.isupper() + False + >>> 'baNana'.isupper() + False + >>> ' '.isupper() + False + + + +.. method:: str.join(iterable) + + Return a string which is the concatenation of the strings in *iterable*. + A :exc:`TypeError` will be raised if there are any non-string values in + *iterable*, including :class:`bytes` objects. The separator between + elements is the string providing this method. + + +.. method:: str.ljust(width[, fillchar]) + + Return the string left justified in a string of length *width*. Padding is + done using the specified *fillchar* (default is an ASCII space). The + original string is returned if *width* is less than or equal to ``len(s)``. + + +.. method:: str.lower() + + Return a copy of the string with all the cased characters [4]_ converted to + lowercase. + + The lowercasing algorithm used is described in section 3.13 of the Unicode + Standard. + + +.. method:: str.lstrip([chars]) + + Return a copy of the string with leading characters removed. The *chars* + argument is a string specifying the set of characters to be removed. If omitted + or ``None``, the *chars* argument defaults to removing whitespace. The *chars* + argument is not a prefix; rather, all combinations of its values are stripped:: + + >>> ' spacious '.lstrip() + 'spacious ' + >>> 'www.example.com'.lstrip('cmowz.') + 'example.com' + + +.. staticmethod:: str.maketrans(x[, y[, z]]) + + This static method returns a translation table usable for :meth:`str.translate`. + + If there is only one argument, it must be a dictionary mapping Unicode + ordinals (integers) or characters (strings of length 1) to Unicode ordinals, + strings (of arbitrary lengths) or ``None``. Character keys will then be + converted to ordinals. + + If there are two arguments, they must be strings of equal length, and in the + resulting dictionary, each character in x will be mapped to the character at + the same position in y. If there is a third argument, it must be a string, + whose characters will be mapped to ``None`` in the result. + + +.. method:: str.partition(sep) + + Split the string at the first occurrence of *sep*, and return a 3-tuple + containing the part before the separator, the separator itself, and the part + after the separator. If the separator is not found, return a 3-tuple containing + the string itself, followed by two empty strings. + + +.. method:: str.replace(old, new[, count]) + + Return a copy of the string with all occurrences of substring *old* replaced by + *new*. If the optional argument *count* is given, only the first *count* + occurrences are replaced. + + +.. method:: str.rfind(sub[, start[, end]]) + + Return the highest index in the string where substring *sub* is found, such + that *sub* is contained within ``s[start:end]``. Optional arguments *start* + and *end* are interpreted as in slice notation. Return ``-1`` on failure. + + +.. method:: str.rindex(sub[, start[, end]]) + + Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not + found. + + +.. method:: str.rjust(width[, fillchar]) + + Return the string right justified in a string of length *width*. Padding is + done using the specified *fillchar* (default is an ASCII space). The + original string is returned if *width* is less than or equal to ``len(s)``. + + +.. method:: str.rpartition(sep) + + Split the string at the last occurrence of *sep*, and return a 3-tuple + containing the part before the separator, the separator itself, and the part + after the separator. If the separator is not found, return a 3-tuple containing + two empty strings, followed by the string itself. + + +.. method:: str.rsplit(sep=None, maxsplit=-1) + + Return a list of the words in the string, using *sep* as the delimiter string. + If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* + ones. If *sep* is not specified or ``None``, any whitespace string is a + separator. Except for splitting from the right, :meth:`rsplit` behaves like + :meth:`split` which is described in detail below. + + +.. method:: str.rstrip([chars]) + + Return a copy of the string with trailing characters removed. The *chars* + argument is a string specifying the set of characters to be removed. If omitted + or ``None``, the *chars* argument defaults to removing whitespace. The *chars* + argument is not a suffix; rather, all combinations of its values are stripped:: + + >>> ' spacious '.rstrip() + ' spacious' + >>> 'mississippi'.rstrip('ipz') + 'mississ' + + +.. method:: str.split(sep=None, maxsplit=-1) + + Return a list of the words in the string, using *sep* as the delimiter + string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, + the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not + specified or ``-1``, then there is no limit on the number of splits + (all possible splits are made). + + If *sep* is given, consecutive delimiters are not grouped together and are + deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns + ``['1', '', '2']``). The *sep* argument may consist of multiple characters + (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``). + Splitting an empty string with a specified separator returns ``['']``. + + For example:: + + >>> '1,2,3'.split(',') + ['1', '2', '3'] + >>> '1,2,3'.split(',', maxsplit=1) + ['1', '2,3'] + >>> '1,2,,3,'.split(',') + ['1', '2', '', '3', ''] + + If *sep* is not specified or is ``None``, a different splitting algorithm is + applied: runs of consecutive whitespace are regarded as a single separator, + and the result will contain no empty strings at the start or end if the + string has leading or trailing whitespace. Consequently, splitting an empty + string or a string consisting of just whitespace with a ``None`` separator + returns ``[]``. + + For example:: + + >>> '1 2 3'.split() + ['1', '2', '3'] + >>> '1 2 3'.split(maxsplit=1) + ['1', '2 3'] + >>> ' 1 2 3 '.split() + ['1', '2', '3'] + + +.. index:: + single: universal newlines; str.splitlines method + +.. method:: str.splitlines([keepends]) + + Return a list of the lines in the string, breaking at line boundaries. Line + breaks are not included in the resulting list unless *keepends* is given and + true. + + This method splits on the following line boundaries. In particular, the + boundaries are a superset of :term:`universal newlines`. + + +-----------------------+-----------------------------+ + | Representation | Description | + +=======================+=============================+ + | ``\n`` | Line Feed | + +-----------------------+-----------------------------+ + | ``\r`` | Carriage Return | + +-----------------------+-----------------------------+ + | ``\r\n`` | Carriage Return + Line Feed | + +-----------------------+-----------------------------+ + | ``\v`` or ``\x0b`` | Line Tabulation | + +-----------------------+-----------------------------+ + | ``\f`` or ``\x0c`` | Form Feed | + +-----------------------+-----------------------------+ + | ``\x1c`` | File Separator | + +-----------------------+-----------------------------+ + | ``\x1d`` | Group Separator | + +-----------------------+-----------------------------+ + | ``\x1e`` | Record Separator | + +-----------------------+-----------------------------+ + | ``\x85`` | Next Line (C1 Control Code) | + +-----------------------+-----------------------------+ + | ``\u2028`` | Line Separator | + +-----------------------+-----------------------------+ + | ``\u2029`` | Paragraph Separator | + +-----------------------+-----------------------------+ + + .. versionchanged:: 3.2 + + ``\v`` and ``\f`` added to list of line boundaries. + + For example:: + + >>> 'ab c\n\nde fg\rkl\r\n'.splitlines() + ['ab c', '', 'de fg', 'kl'] + >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) + ['ab c\n', '\n', 'de fg\r', 'kl\r\n'] + + Unlike :meth:`~str.split` when a delimiter string *sep* is given, this + method returns an empty list for the empty string, and a terminal line + break does not result in an extra line:: + + >>> "".splitlines() + [] + >>> "One line\n".splitlines() + ['One line'] + + For comparison, ``split('\n')`` gives:: + + >>> ''.split('\n') + [''] + >>> 'Two lines\n'.split('\n') + ['Two lines', ''] + + +.. method:: str.startswith(prefix[, start[, end]]) + + Return ``True`` if string starts with the *prefix*, otherwise return ``False``. + *prefix* can also be a tuple of prefixes to look for. With optional *start*, + test string beginning at that position. With optional *end*, stop comparing + string at that position. + + +.. method:: str.strip([chars]) + + Return a copy of the string with the leading and trailing characters removed. + The *chars* argument is a string specifying the set of characters to be removed. + If omitted or ``None``, the *chars* argument defaults to removing whitespace. + The *chars* argument is not a prefix or suffix; rather, all combinations of its + values are stripped:: + + >>> ' spacious '.strip() + 'spacious' + >>> 'www.example.com'.strip('cmowz.') + 'example' + + The outermost leading and trailing *chars* argument values are stripped + from the string. Characters are removed from the leading end until + reaching a string character that is not contained in the set of + characters in *chars*. A similar action takes place on the trailing end. + For example:: + + >>> comment_string = '#....... Section 3.2.1 Issue #32 .......' + >>> comment_string.strip('.#! ') + 'Section 3.2.1 Issue #32' + + +.. method:: str.swapcase() + + Return a copy of the string with uppercase characters converted to lowercase and + vice versa. Note that it is not necessarily true that + ``s.swapcase().swapcase() == s``. + + +.. method:: str.title() + + Return a titlecased version of the string where words start with an uppercase + character and the remaining characters are lowercase. + + For example:: + + >>> 'Hello world'.title() + 'Hello World' + + The algorithm uses a simple language-independent definition of a word as + groups of consecutive letters. The definition works in many contexts but + it means that apostrophes in contractions and possessives form word + boundaries, which may not be the desired result:: + + >>> "they're bill's friends from the UK".title() + "They'Re Bill'S Friends From The Uk" + + A workaround for apostrophes can be constructed using regular expressions:: + + >>> import re + >>> def titlecase(s): + ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", + ... lambda mo: mo.group(0).capitalize(), + ... s) + ... + >>> titlecase("they're bill's friends.") + "They're Bill's Friends." + + +.. method:: str.translate(table) + + Return a copy of the string in which each character has been mapped through + the given translation table. The table must be an object that implements + indexing via :meth:`__getitem__`, typically a :term:`mapping` or + :term:`sequence`. When indexed by a Unicode ordinal (an integer), the + table object can do any of the following: return a Unicode ordinal or a + string, to map the character to one or more other characters; return + ``None``, to delete the character from the return string; or raise a + :exc:`LookupError` exception, to map the character to itself. + + You can use :meth:`str.maketrans` to create a translation map from + character-to-character mappings in different formats. + + See also the :mod:`codecs` module for a more flexible approach to custom + character mappings. + + +.. method:: str.upper() + + Return a copy of the string with all the cased characters [4]_ converted to + uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s`` + contains uncased characters or if the Unicode category of the resulting + character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, + titlecase). + + The uppercasing algorithm used is described in section 3.13 of the Unicode + Standard. + + +.. method:: str.zfill(width) + + Return a copy of the string left filled with ASCII ``'0'`` digits to + make a string of length *width*. A leading sign prefix (``'+'``/``'-'``) + is handled by inserting the padding *after* the sign character rather + than before. The original string is returned if *width* is less than + or equal to ``len(s)``. + + For example:: + + >>> "42".zfill(5) + '00042' + >>> "-42".zfill(5) + '-0042' + + + +.. _old-string-formatting: + +``printf``-style String Formatting +---------------------------------- + +.. index:: + single: formatting, string (%) + single: interpolation, string (%) + single: string; formatting, printf + single: string; interpolation, printf + single: printf-style formatting + single: sprintf-style formatting + single: % (percent); printf-style formatting + +.. note:: + + The formatting operations described here exhibit a variety of quirks that + lead to a number of common errors (such as failing to display tuples and + dictionaries correctly). Using the newer :ref:`formatted string literals + `, the :meth:`str.format` interface, or :ref:`template strings + ` may help avoid these errors. Each of these + alternatives provides their own trade-offs and benefits of simplicity, + flexibility, and/or extensibility. + +String objects have one unique built-in operation: the ``%`` operator (modulo). +This is also known as the string *formatting* or *interpolation* operator. +Given ``format % values`` (where *format* is a string), ``%`` conversion +specifications in *format* are replaced with zero or more elements of *values*. +The effect is similar to using the :c:func:`sprintf` in the C language. + +If *format* requires a single argument, *values* may be a single non-tuple +object. [5]_ Otherwise, *values* must be a tuple with exactly the number of +items specified by the format string, or a single mapping object (for example, a +dictionary). + +.. index:: + single: () (parentheses); in printf-style formatting + single: * (asterisk); in printf-style formatting + single: . (dot); in printf-style formatting + +A conversion specifier contains two or more characters and has the following +components, which must occur in this order: + +#. The ``'%'`` character, which marks the start of the specifier. + +#. Mapping key (optional), consisting of a parenthesised sequence of characters + (for example, ``(somename)``). + +#. Conversion flags (optional), which affect the result of some conversion + types. + +#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the + actual width is read from the next element of the tuple in *values*, and the + object to convert comes after the minimum field width and optional precision. + +#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If + specified as ``'*'`` (an asterisk), the actual precision is read from the next + element of the tuple in *values*, and the value to convert comes after the + precision. + +#. Length modifier (optional). + +#. Conversion type. + +When the right argument is a dictionary (or other mapping type), then the +formats in the string *must* include a parenthesised mapping key into that +dictionary inserted immediately after the ``'%'`` character. The mapping key +selects the value to be formatted from the mapping. For example: + + >>> print('%(language)s has %(number)03d quote types.' % + ... {'language': "Python", "number": 2}) + Python has 002 quote types. + +In this case no ``*`` specifiers may occur in a format (since they require a +sequential parameter list). + +The conversion flag characters are: + +.. index:: + single: # (hash); in printf-style formatting + single: - (minus); in printf-style formatting + single: + (plus); in printf-style formatting + single: space; in printf-style formatting + ++---------+---------------------------------------------------------------------+ +| Flag | Meaning | ++=========+=====================================================================+ +| ``'#'`` | The value conversion will use the "alternate form" (where defined | +| | below). | ++---------+---------------------------------------------------------------------+ +| ``'0'`` | The conversion will be zero padded for numeric values. | ++---------+---------------------------------------------------------------------+ +| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | +| | conversion if both are given). | ++---------+---------------------------------------------------------------------+ +| ``' '`` | (a space) A blank should be left before a positive number (or empty | +| | string) produced by a signed conversion. | ++---------+---------------------------------------------------------------------+ +| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | +| | (overrides a "space" flag). | ++---------+---------------------------------------------------------------------+ + +A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it +is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. + +The conversion types are: + ++------------+-----------------------------------------------------+-------+ +| Conversion | Meaning | Notes | ++============+=====================================================+=======+ +| ``'d'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'i'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'o'`` | Signed octal value. | \(1) | ++------------+-----------------------------------------------------+-------+ +| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(6) | ++------------+-----------------------------------------------------+-------+ +| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'e'`` | Floating point exponential format (lowercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'E'`` | Floating point exponential format (uppercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'f'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'F'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | +| | format if exponent is less than -4 or not less than | | +| | precision, decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | +| | format if exponent is less than -4 or not less than | | +| | precision, decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'c'`` | Single character (accepts integer or single | | +| | character string). | | ++------------+-----------------------------------------------------+-------+ +| ``'r'`` | String (converts any Python object using | \(5) | +| | :func:`repr`). | | ++------------+-----------------------------------------------------+-------+ +| ``'s'`` | String (converts any Python object using | \(5) | +| | :func:`str`). | | ++------------+-----------------------------------------------------+-------+ +| ``'a'`` | String (converts any Python object using | \(5) | +| | :func:`ascii`). | | ++------------+-----------------------------------------------------+-------+ +| ``'%'`` | No argument is converted, results in a ``'%'`` | | +| | character in the result. | | ++------------+-----------------------------------------------------+-------+ + +Notes: + +(1) + The alternate form causes a leading octal specifier (``'0o'``) to be + inserted before the first digit. + +(2) + The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether + the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. + +(3) + The alternate form causes the result to always contain a decimal point, even if + no digits follow it. + + The precision determines the number of digits after the decimal point and + defaults to 6. + +(4) + The alternate form causes the result to always contain a decimal point, and + trailing zeroes are not removed as they would otherwise be. + + The precision determines the number of significant digits before and after the + decimal point and defaults to 6. + +(5) + If precision is ``N``, the output is truncated to ``N`` characters. + +(6) + See :pep:`237`. + +Since Python strings have an explicit length, ``%s`` conversions do not assume +that ``'\0'`` is the end of the string. + +.. XXX Examples? + +.. versionchanged:: 3.1 + ``%f`` conversions for numbers whose absolute value is over 1e50 are no + longer replaced by ``%g`` conversions. + + +.. index:: + single: buffer protocol; binary sequence types + +.. _binaryseq: + +Binary Sequence Types --- :class:`bytes`, :class:`bytearray`, :class:`memoryview` +================================================================================= + +.. index:: + object: bytes + object: bytearray + object: memoryview + module: array + +The core built-in types for manipulating binary data are :class:`bytes` and +:class:`bytearray`. They are supported by :class:`memoryview` which uses +the :ref:`buffer protocol ` to access the memory of other +binary objects without needing to make a copy. + +The :mod:`array` module supports efficient storage of basic data types like +32-bit integers and IEEE754 double-precision floating values. + +.. _typebytes: + +Bytes Objects +------------- + +.. index:: object: bytes + +Bytes objects are immutable sequences of single bytes. Since many major +binary protocols are based on the ASCII text encoding, bytes objects offer +several methods that are only valid when working with ASCII compatible +data and are closely related to string objects in a variety of other ways. + +.. class:: bytes([source[, encoding[, errors]]]) + + Firstly, the syntax for bytes literals is largely the same as that for string + literals, except that a ``b`` prefix is added: + + * Single quotes: ``b'still allows embedded "double" quotes'`` + * Double quotes: ``b"still allows embedded 'single' quotes"``. + * Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""`` + + Only ASCII characters are permitted in bytes literals (regardless of the + declared source code encoding). Any binary values over 127 must be entered + into bytes literals using the appropriate escape sequence. + + As with string literals, bytes literals may also use a ``r`` prefix to disable + processing of escape sequences. See :ref:`strings` for more about the various + forms of bytes literal, including supported escape sequences. + + While bytes literals and representations are based on ASCII text, bytes + objects actually behave like immutable sequences of integers, with each + value in the sequence restricted such that ``0 <= x < 256`` (attempts to + violate this restriction will trigger :exc:`ValueError`). This is done + deliberately to emphasise that while many binary formats include ASCII based + elements and can be usefully manipulated with some text-oriented algorithms, + this is not generally the case for arbitrary binary data (blindly applying + text processing algorithms to binary data formats that are not ASCII + compatible will usually lead to data corruption). + + In addition to the literal forms, bytes objects can be created in a number of + other ways: + + * A zero-filled bytes object of a specified length: ``bytes(10)`` + * From an iterable of integers: ``bytes(range(20))`` + * Copying existing binary data via the buffer protocol: ``bytes(obj)`` + + Also see the :ref:`bytes ` built-in. + + Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal + numbers are a commonly used format for describing binary data. Accordingly, + the bytes type has an additional class method to read data in that format: + + .. classmethod:: fromhex(string) + + This :class:`bytes` class method returns a bytes object, decoding the + given string object. The string must contain two hexadecimal digits per + byte, with ASCII whitespace being ignored. + + >>> bytes.fromhex('2Ef0 F1f2 ') + b'.\xf0\xf1\xf2' + + .. versionchanged:: 3.7 + :meth:`bytes.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + + A reverse conversion function exists to transform a bytes object into its + hexadecimal representation. + + .. method:: hex() + + Return a string object containing two hexadecimal digits for each + byte in the instance. + + >>> b'\xf0\xf1\xf2'.hex() + 'f0f1f2' + + If you want to make the hex string easier to read, you can specify a + single character separator *sep* parameter to include in the output. + By default between each byte. A second optional *bytes_per_sep* + parameter controls the spacing. Positive values calculate the + separator position from the right, negative values from the left. + + >>> value = b'\xf0\xf1\xf2' + >>> value.hex('-') + 'f0-f1-f2' + >>> value.hex('_', 2) + 'f0_f1f2' + >>> b'UUDDLRLRAB'.hex(' ', -4) + '55554444 4c524c52 4142' + + .. versionadded:: 3.5 + + .. versionchanged:: 3.8 + :meth:`bytes.hex` now supports optional *sep* and *bytes_per_sep* + parameters to insert separators between bytes in the hex output. + +Since bytes objects are sequences of integers (akin to a tuple), for a bytes +object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes +object of length 1. (This contrasts with text strings, where both indexing +and slicing will produce a string of length 1) + +The representation of bytes objects uses the literal format (``b'...'``) +since it is often more useful than e.g. ``bytes([46, 46, 46])``. You can +always convert a bytes object into a list of integers using ``list(b)``. + +.. note:: + For Python 2.x users: In the Python 2.x series, a variety of implicit + conversions between 8-bit strings (the closest thing 2.x offers to a + built-in binary data type) and Unicode strings were permitted. This was a + backwards compatibility workaround to account for the fact that Python + originally only supported 8-bit text, and Unicode text was a later + addition. In Python 3.x, those implicit conversions are gone - conversions + between 8-bit binary data and Unicode text must be explicit, and bytes and + string objects will always compare unequal. + + +.. _typebytearray: + +Bytearray Objects +----------------- + +.. index:: object: bytearray + +:class:`bytearray` objects are a mutable counterpart to :class:`bytes` +objects. + +.. class:: bytearray([source[, encoding[, errors]]]) + + There is no dedicated literal syntax for bytearray objects, instead + they are always created by calling the constructor: + + * Creating an empty instance: ``bytearray()`` + * Creating a zero-filled instance with a given length: ``bytearray(10)`` + * From an iterable of integers: ``bytearray(range(20))`` + * Copying existing binary data via the buffer protocol: ``bytearray(b'Hi!')`` + + As bytearray objects are mutable, they support the + :ref:`mutable ` sequence operations in addition to the + common bytes and bytearray operations described in :ref:`bytes-methods`. + + Also see the :ref:`bytearray ` built-in. + + Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal + numbers are a commonly used format for describing binary data. Accordingly, + the bytearray type has an additional class method to read data in that format: + + .. classmethod:: fromhex(string) + + This :class:`bytearray` class method returns bytearray object, decoding + the given string object. The string must contain two hexadecimal digits + per byte, with ASCII whitespace being ignored. + + >>> bytearray.fromhex('2Ef0 F1f2 ') + bytearray(b'.\xf0\xf1\xf2') + + .. versionchanged:: 3.7 + :meth:`bytearray.fromhex` now skips all ASCII whitespace in the string, + not just spaces. + + A reverse conversion function exists to transform a bytearray object into its + hexadecimal representation. + + .. method:: hex() + + Return a string object containing two hexadecimal digits for each + byte in the instance. + + >>> bytearray(b'\xf0\xf1\xf2').hex() + 'f0f1f2' + + .. versionadded:: 3.5 + +Since bytearray objects are sequences of integers (akin to a list), for a +bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be +a bytearray object of length 1. (This contrasts with text strings, where +both indexing and slicing will produce a string of length 1) + +The representation of bytearray objects uses the bytes literal format +(``bytearray(b'...')``) since it is often more useful than e.g. +``bytearray([46, 46, 46])``. You can always convert a bytearray object into +a list of integers using ``list(b)``. + + +.. _bytes-methods: + +Bytes and Bytearray Operations +------------------------------ + +.. index:: pair: bytes; methods + pair: bytearray; methods + +Both bytes and bytearray objects support the :ref:`common ` +sequence operations. They interoperate not just with operands of the same +type, but with any :term:`bytes-like object`. Due to this flexibility, they can be +freely mixed in operations without causing errors. However, the return type +of the result may depend on the order of operands. + +.. note:: + + The methods on bytes and bytearray objects don't accept strings as their + arguments, just as the methods on strings don't accept bytes as their + arguments. For example, you have to write:: + + a = "abc" + b = a.replace("a", "f") + + and:: + + a = b"abc" + b = a.replace(b"a", b"f") + +Some bytes and bytearray operations assume the use of ASCII compatible +binary formats, and hence should be avoided when working with arbitrary +binary data. These restrictions are covered below. + +.. note:: + Using these ASCII based operations to manipulate binary data that is not + stored in an ASCII based format may lead to data corruption. + +The following methods on bytes and bytearray objects can be used with +arbitrary binary data. + +.. method:: bytes.count(sub[, start[, end]]) + bytearray.count(sub[, start[, end]]) + + Return the number of non-overlapping occurrences of subsequence *sub* in + the range [*start*, *end*]. Optional arguments *start* and *end* are + interpreted as in slice notation. + + The subsequence to search for may be any :term:`bytes-like object` or an + integer in the range 0 to 255. + + .. versionchanged:: 3.3 + Also accept an integer in the range 0 to 255 as the subsequence. + + +.. method:: bytes.decode(encoding="utf-8", errors="strict") + bytearray.decode(encoding="utf-8", errors="strict") + + Return a string decoded from the given bytes. Default encoding is + ``'utf-8'``. *errors* may be given to set a different + error handling scheme. The default for *errors* is ``'strict'``, meaning + that encoding errors raise a :exc:`UnicodeError`. Other possible values are + ``'ignore'``, ``'replace'`` and any other name registered via + :func:`codecs.register_error`, see section :ref:`error-handlers`. For a + list of possible encodings, see section :ref:`standard-encodings`. + + By default, the *errors* argument is not checked for best performances, but + only used at the first decoding error. Enable the :ref:`Python Development + Mode `, or use a debug build to check *errors*. + + .. note:: + + Passing the *encoding* argument to :class:`str` allows decoding any + :term:`bytes-like object` directly, without needing to make a temporary + bytes or bytearray object. + + .. versionchanged:: 3.1 + Added support for keyword arguments. + + .. versionchanged:: 3.9 + The *errors* is now checked in development mode and in debug mode. + + +.. method:: bytes.endswith(suffix[, start[, end]]) + bytearray.endswith(suffix[, start[, end]]) + + Return ``True`` if the binary data ends with the specified *suffix*, + otherwise return ``False``. *suffix* can also be a tuple of suffixes to + look for. With optional *start*, test beginning at that position. With + optional *end*, stop comparing at that position. + + The suffix(es) to search for may be any :term:`bytes-like object`. + + +.. method:: bytes.find(sub[, start[, end]]) + bytearray.find(sub[, start[, end]]) + + Return the lowest index in the data where the subsequence *sub* is found, + such that *sub* is contained in the slice ``s[start:end]``. Optional + arguments *start* and *end* are interpreted as in slice notation. Return + ``-1`` if *sub* is not found. + + The subsequence to search for may be any :term:`bytes-like object` or an + integer in the range 0 to 255. + + .. note:: + + The :meth:`~bytes.find` method should be used only if you need to know the + position of *sub*. To check if *sub* is a substring or not, use the + :keyword:`in` operator:: + + >>> b'Py' in b'Python' + True + + .. versionchanged:: 3.3 + Also accept an integer in the range 0 to 255 as the subsequence. + + +.. method:: bytes.index(sub[, start[, end]]) + bytearray.index(sub[, start[, end]]) + + Like :meth:`~bytes.find`, but raise :exc:`ValueError` when the + subsequence is not found. + + The subsequence to search for may be any :term:`bytes-like object` or an + integer in the range 0 to 255. + + .. versionchanged:: 3.3 + Also accept an integer in the range 0 to 255 as the subsequence. + + +.. method:: bytes.join(iterable) + bytearray.join(iterable) + + Return a bytes or bytearray object which is the concatenation of the + binary data sequences in *iterable*. A :exc:`TypeError` will be raised + if there are any values in *iterable* that are not :term:`bytes-like + objects `, including :class:`str` objects. The + separator between elements is the contents of the bytes or + bytearray object providing this method. + + +.. staticmethod:: bytes.maketrans(from, to) + bytearray.maketrans(from, to) + + This static method returns a translation table usable for + :meth:`bytes.translate` that will map each character in *from* into the + character at the same position in *to*; *from* and *to* must both be + :term:`bytes-like objects ` and have the same length. + + .. versionadded:: 3.1 + + +.. method:: bytes.partition(sep) + bytearray.partition(sep) + + Split the sequence at the first occurrence of *sep*, and return a 3-tuple + containing the part before the separator, the separator itself or its + bytearray copy, and the part after the separator. + If the separator is not found, return a 3-tuple + containing a copy of the original sequence, followed by two empty bytes or + bytearray objects. + + The separator to search for may be any :term:`bytes-like object`. + + +.. method:: bytes.replace(old, new[, count]) + bytearray.replace(old, new[, count]) + + Return a copy of the sequence with all occurrences of subsequence *old* + replaced by *new*. If the optional argument *count* is given, only the + first *count* occurrences are replaced. + + The subsequence to search for and its replacement may be any + :term:`bytes-like object`. + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.rfind(sub[, start[, end]]) + bytearray.rfind(sub[, start[, end]]) + + Return the highest index in the sequence where the subsequence *sub* is + found, such that *sub* is contained within ``s[start:end]``. Optional + arguments *start* and *end* are interpreted as in slice notation. Return + ``-1`` on failure. + + The subsequence to search for may be any :term:`bytes-like object` or an + integer in the range 0 to 255. + + .. versionchanged:: 3.3 + Also accept an integer in the range 0 to 255 as the subsequence. + + +.. method:: bytes.rindex(sub[, start[, end]]) + bytearray.rindex(sub[, start[, end]]) + + Like :meth:`~bytes.rfind` but raises :exc:`ValueError` when the + subsequence *sub* is not found. + + The subsequence to search for may be any :term:`bytes-like object` or an + integer in the range 0 to 255. + + .. versionchanged:: 3.3 + Also accept an integer in the range 0 to 255 as the subsequence. + + +.. method:: bytes.rpartition(sep) + bytearray.rpartition(sep) + + Split the sequence at the last occurrence of *sep*, and return a 3-tuple + containing the part before the separator, the separator itself or its + bytearray copy, and the part after the separator. + If the separator is not found, return a 3-tuple + containing two empty bytes or bytearray objects, followed by a copy of the + original sequence. + + The separator to search for may be any :term:`bytes-like object`. + + +.. method:: bytes.startswith(prefix[, start[, end]]) + bytearray.startswith(prefix[, start[, end]]) + + Return ``True`` if the binary data starts with the specified *prefix*, + otherwise return ``False``. *prefix* can also be a tuple of prefixes to + look for. With optional *start*, test beginning at that position. With + optional *end*, stop comparing at that position. + + The prefix(es) to search for may be any :term:`bytes-like object`. + + +.. method:: bytes.translate(table, /, delete=b'') + bytearray.translate(table, /, delete=b'') + + Return a copy of the bytes or bytearray object where all bytes occurring in + the optional argument *delete* are removed, and the remaining bytes have + been mapped through the given translation table, which must be a bytes + object of length 256. + + You can use the :func:`bytes.maketrans` method to create a translation + table. + + Set the *table* argument to ``None`` for translations that only delete + characters:: + + >>> b'read this short text'.translate(None, b'aeiou') + b'rd ths shrt txt' + + .. versionchanged:: 3.6 + *delete* is now supported as a keyword argument. + + +The following methods on bytes and bytearray objects have default behaviours +that assume the use of ASCII compatible binary formats, but can still be used +with arbitrary binary data by passing appropriate arguments. Note that all of +the bytearray methods in this section do *not* operate in place, and instead +produce new objects. + +.. method:: bytes.center(width[, fillbyte]) + bytearray.center(width[, fillbyte]) + + Return a copy of the object centered in a sequence of length *width*. + Padding is done using the specified *fillbyte* (default is an ASCII + space). For :class:`bytes` objects, the original sequence is returned if + *width* is less than or equal to ``len(s)``. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +.. method:: bytes.ljust(width[, fillbyte]) + bytearray.ljust(width[, fillbyte]) + + Return a copy of the object left justified in a sequence of length *width*. + Padding is done using the specified *fillbyte* (default is an ASCII + space). For :class:`bytes` objects, the original sequence is returned if + *width* is less than or equal to ``len(s)``. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +.. method:: bytes.lstrip([chars]) + bytearray.lstrip([chars]) + + Return a copy of the sequence with specified leading bytes removed. The + *chars* argument is a binary sequence specifying the set of byte values to + be removed - the name refers to the fact this method is usually used with + ASCII characters. If omitted or ``None``, the *chars* argument defaults + to removing ASCII whitespace. The *chars* argument is not a prefix; + rather, all combinations of its values are stripped:: + + >>> b' spacious '.lstrip() + b'spacious ' + >>> b'www.example.com'.lstrip(b'cmowz.') + b'example.com' + + The binary sequence of byte values to remove may be any + :term:`bytes-like object`. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +.. method:: bytes.rjust(width[, fillbyte]) + bytearray.rjust(width[, fillbyte]) + + Return a copy of the object right justified in a sequence of length *width*. + Padding is done using the specified *fillbyte* (default is an ASCII + space). For :class:`bytes` objects, the original sequence is returned if + *width* is less than or equal to ``len(s)``. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +.. method:: bytes.rsplit(sep=None, maxsplit=-1) + bytearray.rsplit(sep=None, maxsplit=-1) + + Split the binary sequence into subsequences of the same type, using *sep* + as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits + are done, the *rightmost* ones. If *sep* is not specified or ``None``, + any subsequence consisting solely of ASCII whitespace is a separator. + Except for splitting from the right, :meth:`rsplit` behaves like + :meth:`split` which is described in detail below. + + +.. method:: bytes.rstrip([chars]) + bytearray.rstrip([chars]) + + Return a copy of the sequence with specified trailing bytes removed. The + *chars* argument is a binary sequence specifying the set of byte values to + be removed - the name refers to the fact this method is usually used with + ASCII characters. If omitted or ``None``, the *chars* argument defaults to + removing ASCII whitespace. The *chars* argument is not a suffix; rather, + all combinations of its values are stripped:: + + >>> b' spacious '.rstrip() + b' spacious' + >>> b'mississippi'.rstrip(b'ipz') + b'mississ' + + The binary sequence of byte values to remove may be any + :term:`bytes-like object`. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +.. method:: bytes.split(sep=None, maxsplit=-1) + bytearray.split(sep=None, maxsplit=-1) + + Split the binary sequence into subsequences of the same type, using *sep* + as the delimiter string. If *maxsplit* is given and non-negative, at most + *maxsplit* splits are done (thus, the list will have at most ``maxsplit+1`` + elements). If *maxsplit* is not specified or is ``-1``, then there is no + limit on the number of splits (all possible splits are made). + + If *sep* is given, consecutive delimiters are not grouped together and are + deemed to delimit empty subsequences (for example, ``b'1,,2'.split(b',')`` + returns ``[b'1', b'', b'2']``). The *sep* argument may consist of a + multibyte sequence (for example, ``b'1<>2<>3'.split(b'<>')`` returns + ``[b'1', b'2', b'3']``). Splitting an empty sequence with a specified + separator returns ``[b'']`` or ``[bytearray(b'')]`` depending on the type + of object being split. The *sep* argument may be any + :term:`bytes-like object`. + + For example:: + + >>> b'1,2,3'.split(b',') + [b'1', b'2', b'3'] + >>> b'1,2,3'.split(b',', maxsplit=1) + [b'1', b'2,3'] + >>> b'1,2,,3,'.split(b',') + [b'1', b'2', b'', b'3', b''] + + If *sep* is not specified or is ``None``, a different splitting algorithm + is applied: runs of consecutive ASCII whitespace are regarded as a single + separator, and the result will contain no empty strings at the start or + end if the sequence has leading or trailing whitespace. Consequently, + splitting an empty sequence or a sequence consisting solely of ASCII + whitespace without a specified separator returns ``[]``. + + For example:: + + + >>> b'1 2 3'.split() + [b'1', b'2', b'3'] + >>> b'1 2 3'.split(maxsplit=1) + [b'1', b'2 3'] + >>> b' 1 2 3 '.split() + [b'1', b'2', b'3'] + + +.. method:: bytes.strip([chars]) + bytearray.strip([chars]) + + Return a copy of the sequence with specified leading and trailing bytes + removed. The *chars* argument is a binary sequence specifying the set of + byte values to be removed - the name refers to the fact this method is + usually used with ASCII characters. If omitted or ``None``, the *chars* + argument defaults to removing ASCII whitespace. The *chars* argument is + not a prefix or suffix; rather, all combinations of its values are + stripped:: + + >>> b' spacious '.strip() + b'spacious' + >>> b'www.example.com'.strip(b'cmowz.') + b'example' + + The binary sequence of byte values to remove may be any + :term:`bytes-like object`. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. + + +The following methods on bytes and bytearray objects assume the use of ASCII +compatible binary formats and should not be applied to arbitrary binary data. +Note that all of the bytearray methods in this section do *not* operate in +place, and instead produce new objects. + +.. method:: bytes.capitalize() + bytearray.capitalize() + + Return a copy of the sequence with each byte interpreted as an ASCII + character, and the first byte capitalized and the rest lowercased. + Non-ASCII byte values are passed through unchanged. + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.expandtabs(tabsize=8) + bytearray.expandtabs(tabsize=8) + + Return a copy of the sequence where all ASCII tab characters are replaced + by one or more ASCII spaces, depending on the current column and the given + tab size. Tab positions occur every *tabsize* bytes (default is 8, + giving tab positions at columns 0, 8, 16 and so on). To expand the + sequence, the current column is set to zero and the sequence is examined + byte by byte. If the byte is an ASCII tab character (``b'\t'``), one or + more space characters are inserted in the result until the current column + is equal to the next tab position. (The tab character itself is not + copied.) If the current byte is an ASCII newline (``b'\n'``) or + carriage return (``b'\r'``), it is copied and the current column is reset + to zero. Any other byte value is copied unchanged and the current column + is incremented by one regardless of how the byte value is represented when + printed:: + + >>> b'01\t012\t0123\t01234'.expandtabs() + b'01 012 0123 01234' + >>> b'01\t012\t0123\t01234'.expandtabs(4) + b'01 012 0123 01234' + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.isalnum() + bytearray.isalnum() + + Return ``True`` if all bytes in the sequence are alphabetical ASCII characters + or ASCII decimal digits and the sequence is not empty, ``False`` otherwise. + Alphabetic ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. ASCII decimal + digits are those byte values in the sequence ``b'0123456789'``. + + For example:: + + >>> b'ABCabc1'.isalnum() + True + >>> b'ABC abc1'.isalnum() + False + + +.. method:: bytes.isalpha() + bytearray.isalpha() + + Return ``True`` if all bytes in the sequence are alphabetic ASCII characters + and the sequence is not empty, ``False`` otherwise. Alphabetic ASCII + characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + For example:: + + >>> b'ABCabc'.isalpha() + True + >>> b'ABCabc1'.isalpha() + False + + +.. method:: bytes.isascii() + bytearray.isascii() + + Return ``True`` if the sequence is empty or all bytes in the sequence are ASCII, + ``False`` otherwise. + ASCII bytes are in the range 0-0x7F. + + .. versionadded:: 3.7 + + +.. method:: bytes.isdigit() + bytearray.isdigit() + + Return ``True`` if all bytes in the sequence are ASCII decimal digits + and the sequence is not empty, ``False`` otherwise. ASCII decimal digits are + those byte values in the sequence ``b'0123456789'``. + + For example:: + + >>> b'1234'.isdigit() + True + >>> b'1.23'.isdigit() + False + + +.. method:: bytes.islower() + bytearray.islower() + + Return ``True`` if there is at least one lowercase ASCII character + in the sequence and no uppercase ASCII characters, ``False`` otherwise. + + For example:: + + >>> b'hello world'.islower() + True + >>> b'Hello world'.islower() + False + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + +.. method:: bytes.isspace() + bytearray.isspace() + + Return ``True`` if all bytes in the sequence are ASCII whitespace and the + sequence is not empty, ``False`` otherwise. ASCII whitespace characters are + those byte values in the sequence ``b' \t\n\r\x0b\f'`` (space, tab, newline, + carriage return, vertical tab, form feed). + + +.. method:: bytes.istitle() + bytearray.istitle() + + Return ``True`` if the sequence is ASCII titlecase and the sequence is not + empty, ``False`` otherwise. See :meth:`bytes.title` for more details on the + definition of "titlecase". + + For example:: + + >>> b'Hello World'.istitle() + True + >>> b'Hello world'.istitle() + False + + +.. method:: bytes.isupper() + bytearray.isupper() + + Return ``True`` if there is at least one uppercase alphabetic ASCII character + in the sequence and no lowercase ASCII characters, ``False`` otherwise. + + For example:: + + >>> b'HELLO WORLD'.isupper() + True + >>> b'Hello world'.isupper() + False + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + +.. method:: bytes.lower() + bytearray.lower() + + Return a copy of the sequence with all the uppercase ASCII characters + converted to their corresponding lowercase counterpart. + + For example:: + + >>> b'Hello World'.lower() + b'hello world' + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. index:: + single: universal newlines; bytes.splitlines method + single: universal newlines; bytearray.splitlines method + +.. method:: bytes.splitlines(keepends=False) + bytearray.splitlines(keepends=False) + + Return a list of the lines in the binary sequence, breaking at ASCII + line boundaries. This method uses the :term:`universal newlines` approach + to splitting lines. Line breaks are not included in the resulting list + unless *keepends* is given and true. + + For example:: + + >>> b'ab c\n\nde fg\rkl\r\n'.splitlines() + [b'ab c', b'', b'de fg', b'kl'] + >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) + [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n'] + + Unlike :meth:`~bytes.split` when a delimiter string *sep* is given, this + method returns an empty list for the empty string, and a terminal line + break does not result in an extra line:: + + >>> b"".split(b'\n'), b"Two lines\n".split(b'\n') + ([b''], [b'Two lines', b'']) + >>> b"".splitlines(), b"One line\n".splitlines() + ([], [b'One line']) + + +.. method:: bytes.swapcase() + bytearray.swapcase() + + Return a copy of the sequence with all the lowercase ASCII characters + converted to their corresponding uppercase counterpart and vice-versa. + + For example:: + + >>> b'Hello World'.swapcase() + b'hELLO wORLD' + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + Unlike :func:`str.swapcase()`, it is always the case that + ``bin.swapcase().swapcase() == bin`` for the binary versions. Case + conversions are symmetrical in ASCII, even though that is not generally + true for arbitrary Unicode code points. + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.title() + bytearray.title() + + Return a titlecased version of the binary sequence where words start with + an uppercase ASCII character and the remaining characters are lowercase. + Uncased byte values are left unmodified. + + For example:: + + >>> b'Hello world'.title() + b'Hello World' + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + All other byte values are uncased. + + The algorithm uses a simple language-independent definition of a word as + groups of consecutive letters. The definition works in many contexts but + it means that apostrophes in contractions and possessives form word + boundaries, which may not be the desired result:: + + >>> b"they're bill's friends from the UK".title() + b"They'Re Bill'S Friends From The Uk" + + A workaround for apostrophes can be constructed using regular expressions:: + + >>> import re + >>> def titlecase(s): + ... return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?", + ... lambda mo: mo.group(0)[0:1].upper() + + ... mo.group(0)[1:].lower(), + ... s) + ... + >>> titlecase(b"they're bill's friends.") + b"They're Bill's Friends." + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.upper() + bytearray.upper() + + Return a copy of the sequence with all the lowercase ASCII characters + converted to their corresponding uppercase counterpart. + + For example:: + + >>> b'Hello World'.upper() + b'HELLO WORLD' + + Lowercase ASCII characters are those byte values in the sequence + ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters + are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. method:: bytes.zfill(width) + bytearray.zfill(width) + + Return a copy of the sequence left filled with ASCII ``b'0'`` digits to + make a sequence of length *width*. A leading sign prefix (``b'+'``/ + ``b'-'``) is handled by inserting the padding *after* the sign character + rather than before. For :class:`bytes` objects, the original sequence is + returned if *width* is less than or equal to ``len(seq)``. + + For example:: + + >>> b"42".zfill(5) + b'00042' + >>> b"-42".zfill(5) + b'-0042' + + .. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + + +.. _bytes-formatting: + +``printf``-style Bytes Formatting +---------------------------------- + +.. index:: + single: formatting; bytes (%) + single: formatting; bytearray (%) + single: interpolation; bytes (%) + single: interpolation; bytearray (%) + single: bytes; formatting + single: bytearray; formatting + single: bytes; interpolation + single: bytearray; interpolation + single: printf-style formatting + single: sprintf-style formatting + single: % (percent); printf-style formatting + +.. note:: + + The formatting operations described here exhibit a variety of quirks that + lead to a number of common errors (such as failing to display tuples and + dictionaries correctly). If the value being printed may be a tuple or + dictionary, wrap it in a tuple. + +Bytes objects (``bytes``/``bytearray``) have one unique built-in operation: +the ``%`` operator (modulo). +This is also known as the bytes *formatting* or *interpolation* operator. +Given ``format % values`` (where *format* is a bytes object), ``%`` conversion +specifications in *format* are replaced with zero or more elements of *values*. +The effect is similar to using the :c:func:`sprintf` in the C language. + +If *format* requires a single argument, *values* may be a single non-tuple +object. [5]_ Otherwise, *values* must be a tuple with exactly the number of +items specified by the format bytes object, or a single mapping object (for +example, a dictionary). + +.. index:: + single: () (parentheses); in printf-style formatting + single: * (asterisk); in printf-style formatting + single: . (dot); in printf-style formatting + +A conversion specifier contains two or more characters and has the following +components, which must occur in this order: + +#. The ``'%'`` character, which marks the start of the specifier. + +#. Mapping key (optional), consisting of a parenthesised sequence of characters + (for example, ``(somename)``). + +#. Conversion flags (optional), which affect the result of some conversion + types. + +#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the + actual width is read from the next element of the tuple in *values*, and the + object to convert comes after the minimum field width and optional precision. + +#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If + specified as ``'*'`` (an asterisk), the actual precision is read from the next + element of the tuple in *values*, and the value to convert comes after the + precision. + +#. Length modifier (optional). + +#. Conversion type. + +When the right argument is a dictionary (or other mapping type), then the +formats in the bytes object *must* include a parenthesised mapping key into that +dictionary inserted immediately after the ``'%'`` character. The mapping key +selects the value to be formatted from the mapping. For example: + + >>> print(b'%(language)s has %(number)03d quote types.' % + ... {b'language': b"Python", b"number": 2}) + b'Python has 002 quote types.' + +In this case no ``*`` specifiers may occur in a format (since they require a +sequential parameter list). + +The conversion flag characters are: + +.. index:: + single: # (hash); in printf-style formatting + single: - (minus); in printf-style formatting + single: + (plus); in printf-style formatting + single: space; in printf-style formatting + ++---------+---------------------------------------------------------------------+ +| Flag | Meaning | ++=========+=====================================================================+ +| ``'#'`` | The value conversion will use the "alternate form" (where defined | +| | below). | ++---------+---------------------------------------------------------------------+ +| ``'0'`` | The conversion will be zero padded for numeric values. | ++---------+---------------------------------------------------------------------+ +| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | +| | conversion if both are given). | ++---------+---------------------------------------------------------------------+ +| ``' '`` | (a space) A blank should be left before a positive number (or empty | +| | string) produced by a signed conversion. | ++---------+---------------------------------------------------------------------+ +| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | +| | (overrides a "space" flag). | ++---------+---------------------------------------------------------------------+ + +A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it +is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. + +The conversion types are: + ++------------+-----------------------------------------------------+-------+ +| Conversion | Meaning | Notes | ++============+=====================================================+=======+ +| ``'d'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'i'`` | Signed integer decimal. | | ++------------+-----------------------------------------------------+-------+ +| ``'o'`` | Signed octal value. | \(1) | ++------------+-----------------------------------------------------+-------+ +| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(8) | ++------------+-----------------------------------------------------+-------+ +| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | ++------------+-----------------------------------------------------+-------+ +| ``'e'`` | Floating point exponential format (lowercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'E'`` | Floating point exponential format (uppercase). | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'f'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'F'`` | Floating point decimal format. | \(3) | ++------------+-----------------------------------------------------+-------+ +| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | +| | format if exponent is less than -4 or not less than | | +| | precision, decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | +| | format if exponent is less than -4 or not less than | | +| | precision, decimal format otherwise. | | ++------------+-----------------------------------------------------+-------+ +| ``'c'`` | Single byte (accepts integer or single | | +| | byte objects). | | ++------------+-----------------------------------------------------+-------+ +| ``'b'`` | Bytes (any object that follows the | \(5) | +| | :ref:`buffer protocol ` or has | | +| | :meth:`__bytes__`). | | ++------------+-----------------------------------------------------+-------+ +| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) | +| | be used for Python2/3 code bases. | | ++------------+-----------------------------------------------------+-------+ +| ``'a'`` | Bytes (converts any Python object using | \(5) | +| | ``repr(obj).encode('ascii','backslashreplace)``). | | ++------------+-----------------------------------------------------+-------+ +| ``'r'`` | ``'r'`` is an alias for ``'a'`` and should only | \(7) | +| | be used for Python2/3 code bases. | | ++------------+-----------------------------------------------------+-------+ +| ``'%'`` | No argument is converted, results in a ``'%'`` | | +| | character in the result. | | ++------------+-----------------------------------------------------+-------+ + +Notes: + +(1) + The alternate form causes a leading octal specifier (``'0o'``) to be + inserted before the first digit. + +(2) + The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether + the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. + +(3) + The alternate form causes the result to always contain a decimal point, even if + no digits follow it. + + The precision determines the number of digits after the decimal point and + defaults to 6. + +(4) + The alternate form causes the result to always contain a decimal point, and + trailing zeroes are not removed as they would otherwise be. + + The precision determines the number of significant digits before and after the + decimal point and defaults to 6. + +(5) + If precision is ``N``, the output is truncated to ``N`` characters. + +(6) + ``b'%s'`` is deprecated, but will not be removed during the 3.x series. + +(7) + ``b'%r'`` is deprecated, but will not be removed during the 3.x series. + +(8) + See :pep:`237`. + +.. note:: + + The bytearray version of this method does *not* operate in place - it + always produces a new object, even if no changes were made. + +.. seealso:: + + :pep:`461` - Adding % formatting to bytes and bytearray + +.. versionadded:: 3.5 + +.. _typememoryview: + +Memory Views +------------ + +:class:`memoryview` objects allow Python code to access the internal data +of an object that supports the :ref:`buffer protocol ` without +copying. + +.. class:: memoryview(obj) + + Create a :class:`memoryview` that references *obj*. *obj* must support the + buffer protocol. Built-in objects that support the buffer protocol include + :class:`bytes` and :class:`bytearray`. + + A :class:`memoryview` has the notion of an *element*, which is the + atomic memory unit handled by the originating object *obj*. For many + simple types such as :class:`bytes` and :class:`bytearray`, an element + is a single byte, but other types such as :class:`array.array` may have + bigger elements. + + ``len(view)`` is equal to the length of :class:`~memoryview.tolist`. + If ``view.ndim = 0``, the length is 1. If ``view.ndim = 1``, the length + is equal to the number of elements in the view. For higher dimensions, + the length is equal to the length of the nested list representation of + the view. The :class:`~memoryview.itemsize` attribute will give you the + number of bytes in a single element. + + A :class:`memoryview` supports slicing and indexing to expose its data. + One-dimensional slicing will result in a subview:: + + >>> v = memoryview(b'abcefg') + >>> v[1] + 98 + >>> v[-1] + 103 + >>> v[1:4] + + >>> bytes(v[1:4]) + b'bce' + + If :class:`~memoryview.format` is one of the native format specifiers + from the :mod:`struct` module, indexing with an integer or a tuple of + integers is also supported and returns a single *element* with + the correct type. One-dimensional memoryviews can be indexed + with an integer or a one-integer tuple. Multi-dimensional memoryviews + can be indexed with tuples of exactly *ndim* integers where *ndim* is + the number of dimensions. Zero-dimensional memoryviews can be indexed + with the empty tuple. + + Here is an example with a non-byte format:: + + >>> import array + >>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444]) + >>> m = memoryview(a) + >>> m[0] + -11111111 + >>> m[-1] + 44444444 + >>> m[::2].tolist() + [-11111111, -33333333] + + If the underlying object is writable, the memoryview supports + one-dimensional slice assignment. Resizing is not allowed:: + + >>> data = bytearray(b'abcefg') + >>> v = memoryview(data) + >>> v.readonly + False + >>> v[0] = ord(b'z') + >>> data + bytearray(b'zbcefg') + >>> v[1:4] = b'123' + >>> data + bytearray(b'z123fg') + >>> v[2:3] = b'spam' + Traceback (most recent call last): + File "", line 1, in + ValueError: memoryview assignment: lvalue and rvalue have different structures + >>> v[2:6] = b'spam' + >>> data + bytearray(b'z1spam') + + One-dimensional memoryviews of hashable (read-only) types with formats + 'B', 'b' or 'c' are also hashable. The hash is defined as + ``hash(m) == hash(m.tobytes())``:: + + >>> v = memoryview(b'abcefg') + >>> hash(v) == hash(b'abcefg') + True + >>> hash(v[2:4]) == hash(b'ce') + True + >>> hash(v[::-2]) == hash(b'abcefg'[::-2]) + True + + .. versionchanged:: 3.3 + One-dimensional memoryviews can now be sliced. + One-dimensional memoryviews with formats 'B', 'b' or 'c' are now hashable. + + .. versionchanged:: 3.4 + memoryview is now registered automatically with + :class:`collections.abc.Sequence` + + .. versionchanged:: 3.5 + memoryviews can now be indexed with tuple of integers. + + :class:`memoryview` has several methods: + + .. method:: __eq__(exporter) + + A memoryview and a :pep:`3118` exporter are equal if their shapes are + equivalent and if all corresponding values are equal when the operands' + respective format codes are interpreted using :mod:`struct` syntax. + + For the subset of :mod:`struct` format strings currently supported by + :meth:`tolist`, ``v`` and ``w`` are equal if ``v.tolist() == w.tolist()``:: + + >>> import array + >>> a = array.array('I', [1, 2, 3, 4, 5]) + >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0]) + >>> c = array.array('b', [5, 3, 1]) + >>> x = memoryview(a) + >>> y = memoryview(b) + >>> x == a == y == b + True + >>> x.tolist() == a.tolist() == y.tolist() == b.tolist() + True + >>> z = y[::-2] + >>> z == c + True + >>> z.tolist() == c.tolist() + True + + If either format string is not supported by the :mod:`struct` module, + then the objects will always compare as unequal (even if the format + strings and buffer contents are identical):: + + >>> from ctypes import BigEndianStructure, c_long + >>> class BEPoint(BigEndianStructure): + ... _fields_ = [("x", c_long), ("y", c_long)] + ... + >>> point = BEPoint(100, 200) + >>> a = memoryview(point) + >>> b = memoryview(point) + >>> a == point + False + >>> a == b + False + + Note that, as with floating point numbers, ``v is w`` does *not* imply + ``v == w`` for memoryview objects. + + .. versionchanged:: 3.3 + Previous versions compared the raw memory disregarding the item format + and the logical array structure. + + .. method:: tobytes(order=None) + + Return the data in the buffer as a bytestring. This is equivalent to + calling the :class:`bytes` constructor on the memoryview. :: + + >>> m = memoryview(b"abc") + >>> m.tobytes() + b'abc' + >>> bytes(m) + b'abc' + + For non-contiguous arrays the result is equal to the flattened list + representation with all elements converted to bytes. :meth:`tobytes` + supports all format strings, including those that are not in + :mod:`struct` module syntax. + + .. versionadded:: 3.8 + *order* can be {'C', 'F', 'A'}. When *order* is 'C' or 'F', the data + of the original array is converted to C or Fortran order. For contiguous + views, 'A' returns an exact copy of the physical memory. In particular, + in-memory Fortran order is preserved. For non-contiguous views, the + data is converted to C first. *order=None* is the same as *order='C'*. + + .. method:: hex() + + Return a string object containing two hexadecimal digits for each + byte in the buffer. :: + + >>> m = memoryview(b"abc") + >>> m.hex() + '616263' + + .. versionadded:: 3.5 + + .. method:: tolist() + + Return the data in the buffer as a list of elements. :: + + >>> memoryview(b'abc').tolist() + [97, 98, 99] + >>> import array + >>> a = array.array('d', [1.1, 2.2, 3.3]) + >>> m = memoryview(a) + >>> m.tolist() + [1.1, 2.2, 3.3] + + .. versionchanged:: 3.3 + :meth:`tolist` now supports all single character native formats in + :mod:`struct` module syntax as well as multi-dimensional + representations. + + .. method:: toreadonly() + + Return a readonly version of the memoryview object. The original + memoryview object is unchanged. :: + + >>> m = memoryview(bytearray(b'abc')) + >>> mm = m.toreadonly() + >>> mm.tolist() + [89, 98, 99] + >>> mm[0] = 42 + Traceback (most recent call last): + File "", line 1, in + TypeError: cannot modify read-only memory + >>> m[0] = 43 + >>> mm.tolist() + [43, 98, 99] + + .. versionadded:: 3.8 + + .. method:: release() + + Release the underlying buffer exposed by the memoryview object. Many + objects take special actions when a view is held on them (for example, + a :class:`bytearray` would temporarily forbid resizing); therefore, + calling release() is handy to remove these restrictions (and free any + dangling resources) as soon as possible. + + After this method has been called, any further operation on the view + raises a :class:`ValueError` (except :meth:`release()` itself which can + be called multiple times):: + + >>> m = memoryview(b'abc') + >>> m.release() + >>> m[0] + Traceback (most recent call last): + File "", line 1, in + ValueError: operation forbidden on released memoryview object + + The context management protocol can be used for a similar effect, + using the ``with`` statement:: + + >>> with memoryview(b'abc') as m: + ... m[0] + ... + 97 + >>> m[0] + Traceback (most recent call last): + File "", line 1, in + ValueError: operation forbidden on released memoryview object + + .. versionadded:: 3.2 + + .. method:: cast(format[, shape]) + + Cast a memoryview to a new format or shape. *shape* defaults to + ``[byte_length//new_itemsize]``, which means that the result view + will be one-dimensional. The return value is a new memoryview, but + the buffer itself is not copied. Supported casts are 1D -> C-:term:`contiguous` + and C-contiguous -> 1D. + + The destination format is restricted to a single element native format in + :mod:`struct` syntax. One of the formats must be a byte format + ('B', 'b' or 'c'). The byte length of the result must be the same + as the original length. + + Cast 1D/long to 1D/unsigned bytes:: + + >>> import array + >>> a = array.array('l', [1,2,3]) + >>> x = memoryview(a) + >>> x.format + 'l' + >>> x.itemsize + 8 + >>> len(x) + 3 + >>> x.nbytes + 24 + >>> y = x.cast('B') + >>> y.format + 'B' + >>> y.itemsize + 1 + >>> len(y) + 24 + >>> y.nbytes + 24 + + Cast 1D/unsigned bytes to 1D/char:: + + >>> b = bytearray(b'zyz') + >>> x = memoryview(b) + >>> x[0] = b'a' + Traceback (most recent call last): + File "", line 1, in + ValueError: memoryview: invalid value for format "B" + >>> y = x.cast('c') + >>> y[0] = b'a' + >>> b + bytearray(b'ayz') + + Cast 1D/bytes to 3D/ints to 1D/signed char:: + + >>> import struct + >>> buf = struct.pack("i"*12, *list(range(12))) + >>> x = memoryview(buf) + >>> y = x.cast('i', shape=[2,2,3]) + >>> y.tolist() + [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] + >>> y.format + 'i' + >>> y.itemsize + 4 + >>> len(y) + 2 + >>> y.nbytes + 48 + >>> z = y.cast('b') + >>> z.format + 'b' + >>> z.itemsize + 1 + >>> len(z) + 48 + >>> z.nbytes + 48 + + Cast 1D/unsigned long to 2D/unsigned long:: + + >>> buf = struct.pack("L"*6, *list(range(6))) + >>> x = memoryview(buf) + >>> y = x.cast('L', shape=[2,3]) + >>> len(y) + 2 + >>> y.nbytes + 48 + >>> y.tolist() + [[0, 1, 2], [3, 4, 5]] + + .. versionadded:: 3.3 + + .. versionchanged:: 3.5 + The source format is no longer restricted when casting to a byte view. + + There are also several readonly attributes available: + + .. attribute:: obj + + The underlying object of the memoryview:: + + >>> b = bytearray(b'xyz') + >>> m = memoryview(b) + >>> m.obj is b + True + + .. versionadded:: 3.3 + + .. attribute:: nbytes + + ``nbytes == product(shape) * itemsize == len(m.tobytes())``. This is + the amount of space in bytes that the array would use in a contiguous + representation. It is not necessarily equal to ``len(m)``:: + + >>> import array + >>> a = array.array('i', [1,2,3,4,5]) + >>> m = memoryview(a) + >>> len(m) + 5 + >>> m.nbytes + 20 + >>> y = m[::2] + >>> len(y) + 3 + >>> y.nbytes + 12 + >>> len(y.tobytes()) + 12 + + Multi-dimensional arrays:: + + >>> import struct + >>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)]) + >>> x = memoryview(buf) + >>> y = x.cast('d', shape=[3,4]) + >>> y.tolist() + [[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]] + >>> len(y) + 3 + >>> y.nbytes + 96 + + .. versionadded:: 3.3 + + .. attribute:: readonly + + A bool indicating whether the memory is read only. + + .. attribute:: format + + A string containing the format (in :mod:`struct` module style) for each + element in the view. A memoryview can be created from exporters with + arbitrary format strings, but some methods (e.g. :meth:`tolist`) are + restricted to native single element formats. + + .. versionchanged:: 3.3 + format ``'B'`` is now handled according to the struct module syntax. + This means that ``memoryview(b'abc')[0] == b'abc'[0] == 97``. + + .. attribute:: itemsize + + The size in bytes of each element of the memoryview:: + + >>> import array, struct + >>> m = memoryview(array.array('H', [32000, 32001, 32002])) + >>> m.itemsize + 2 + >>> m[0] + 32000 + >>> struct.calcsize('H') == m.itemsize + True + + .. attribute:: ndim + + An integer indicating how many dimensions of a multi-dimensional array the + memory represents. + + .. attribute:: shape + + A tuple of integers the length of :attr:`ndim` giving the shape of the + memory as an N-dimensional array. + + .. versionchanged:: 3.3 + An empty tuple instead of ``None`` when ndim = 0. + + .. attribute:: strides + + A tuple of integers the length of :attr:`ndim` giving the size in bytes to + access each element for each dimension of the array. + + .. versionchanged:: 3.3 + An empty tuple instead of ``None`` when ndim = 0. + + .. attribute:: suboffsets + + Used internally for PIL-style arrays. The value is informational only. + + .. attribute:: c_contiguous + + A bool indicating whether the memory is C-:term:`contiguous`. + + .. versionadded:: 3.3 + + .. attribute:: f_contiguous + + A bool indicating whether the memory is Fortran :term:`contiguous`. + + .. versionadded:: 3.3 + + .. attribute:: contiguous + + A bool indicating whether the memory is :term:`contiguous`. + + .. versionadded:: 3.3 + + +.. _types-set: + +Set Types --- :class:`set`, :class:`frozenset` +============================================== + +.. index:: object: set + +A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects. +Common uses include membership testing, removing duplicates from a sequence, and +computing mathematical operations such as intersection, union, difference, and +symmetric difference. +(For other containers see the built-in :class:`dict`, :class:`list`, +and :class:`tuple` classes, and the :mod:`collections` module.) + +Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in +set``. Being an unordered collection, sets do not record element position or +order of insertion. Accordingly, sets do not support indexing, slicing, or +other sequence-like behavior. + +There are currently two built-in set types, :class:`set` and :class:`frozenset`. +The :class:`set` type is mutable --- the contents can be changed using methods +like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no +hash value and cannot be used as either a dictionary key or as an element of +another set. The :class:`frozenset` type is immutable and :term:`hashable` --- +its contents cannot be altered after it is created; it can therefore be used as +a dictionary key or as an element of another set. + +Non-empty sets (not frozensets) can be created by placing a comma-separated list +of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the +:class:`set` constructor. + +The constructors for both classes work the same: + +.. class:: set([iterable]) + frozenset([iterable]) + + Return a new set or frozenset object whose elements are taken from + *iterable*. The elements of a set must be :term:`hashable`. To + represent sets of sets, the inner sets must be :class:`frozenset` + objects. If *iterable* is not specified, a new empty set is + returned. + + Instances of :class:`set` and :class:`frozenset` provide the following + operations: + + .. describe:: len(s) + + Return the number of elements in set *s* (cardinality of *s*). + + .. describe:: x in s + + Test *x* for membership in *s*. + + .. describe:: x not in s + + Test *x* for non-membership in *s*. + + .. method:: isdisjoint(other) + + Return ``True`` if the set has no elements in common with *other*. Sets are + disjoint if and only if their intersection is the empty set. + + .. method:: issubset(other) + set <= other + + Test whether every element in the set is in *other*. + + .. method:: set < other + + Test whether the set is a proper subset of *other*, that is, + ``set <= other and set != other``. + + .. method:: issuperset(other) + set >= other + + Test whether every element in *other* is in the set. + + .. method:: set > other + + Test whether the set is a proper superset of *other*, that is, ``set >= + other and set != other``. + + .. method:: union(*others) + set | other | ... + + Return a new set with elements from the set and all others. + + .. method:: intersection(*others) + set & other & ... + + Return a new set with elements common to the set and all others. + + .. method:: difference(*others) + set - other - ... + + Return a new set with elements in the set that are not in the others. + + .. method:: symmetric_difference(other) + set ^ other + + Return a new set with elements in either the set or *other* but not both. + + .. method:: copy() + + Return a shallow copy of the set. + + + Note, the non-operator versions of :meth:`union`, :meth:`intersection`, + :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and + :meth:`issuperset` methods will accept any iterable as an argument. In + contrast, their operator based counterparts require their arguments to be + sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` + in favor of the more readable ``set('abc').intersection('cbs')``. + + Both :class:`set` and :class:`frozenset` support set to set comparisons. Two + sets are equal if and only if every element of each set is contained in the + other (each is a subset of the other). A set is less than another set if and + only if the first set is a proper subset of the second set (is a subset, but + is not equal). A set is greater than another set if and only if the first set + is a proper superset of the second set (is a superset, but is not equal). + + Instances of :class:`set` are compared to instances of :class:`frozenset` + based on their members. For example, ``set('abc') == frozenset('abc')`` + returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``. + + The subset and equality comparisons do not generalize to a total ordering + function. For example, any two nonempty disjoint sets are not equal and are not + subsets of each other, so *all* of the following return ``False``: ``ab``. + + Since sets only define partial ordering (subset relationships), the output of + the :meth:`list.sort` method is undefined for lists of sets. + + Set elements, like dictionary keys, must be :term:`hashable`. + + Binary operations that mix :class:`set` instances with :class:`frozenset` + return the type of the first operand. For example: ``frozenset('ab') | + set('bc')`` returns an instance of :class:`frozenset`. + + The following table lists operations available for :class:`set` that do not + apply to immutable instances of :class:`frozenset`: + + .. method:: update(*others) + set |= other | ... + + Update the set, adding elements from all others. + + .. method:: intersection_update(*others) + set &= other & ... + + Update the set, keeping only elements found in it and all others. + + .. method:: difference_update(*others) + set -= other | ... + + Update the set, removing elements found in others. + + .. method:: symmetric_difference_update(other) + set ^= other + + Update the set, keeping only elements found in either set, but not in both. + + .. method:: add(elem) + + Add element *elem* to the set. + + .. method:: remove(elem) + + Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is + not contained in the set. + + .. method:: discard(elem) + + Remove element *elem* from the set if it is present. + + .. method:: pop() + + Remove and return an arbitrary element from the set. Raises + :exc:`KeyError` if the set is empty. + + .. method:: clear() + + Remove all elements from the set. + + + Note, the non-operator versions of the :meth:`update`, + :meth:`intersection_update`, :meth:`difference_update`, and + :meth:`symmetric_difference_update` methods will accept any iterable as an + argument. + + Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and + :meth:`discard` methods may be a set. To support searching for an equivalent + frozenset, a temporary one is created from *elem*. + + +.. _typesmapping: + +Mapping Types --- :class:`dict` +=============================== + +.. index:: + object: mapping + object: dictionary + triple: operations on; mapping; types + triple: operations on; dictionary; type + statement: del + builtin: len + +A :term:`mapping` object maps :term:`hashable` values to arbitrary objects. +Mappings are mutable objects. There is currently only one standard mapping +type, the :dfn:`dictionary`. (For other containers see the built-in +:class:`list`, :class:`set`, and :class:`tuple` classes, and the +:mod:`collections` module.) + +A dictionary's keys are *almost* arbitrary values. Values that are not +:term:`hashable`, that is, values containing lists, dictionaries or other +mutable types (that are compared by value rather than by object identity) may +not be used as keys. Numeric types used for keys obey the normal rules for +numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) +then they can be used interchangeably to index the same dictionary entry. (Note +however, that since computers store floating-point numbers as approximations it +is usually unwise to use them as dictionary keys.) + +Dictionaries can be created by placing a comma-separated list of ``key: value`` +pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: +'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. + +.. class:: dict(**kwarg) + dict(mapping, **kwarg) + dict(iterable, **kwarg) + + Return a new dictionary initialized from an optional positional argument + and a possibly empty set of keyword arguments. + + If no positional argument is given, an empty dictionary is created. + If a positional argument is given and it is a mapping object, a dictionary + is created with the same key-value pairs as the mapping object. Otherwise, + the positional argument must be an :term:`iterable` object. Each item in + the iterable must itself be an iterable with exactly two objects. The + first object of each item becomes a key in the new dictionary, and the + second object the corresponding value. If a key occurs more than once, the + last value for that key becomes the corresponding value in the new + dictionary. + + If keyword arguments are given, the keyword arguments and their values are + added to the dictionary created from the positional argument. If a key + being added is already present, the value from the keyword argument + replaces the value from the positional argument. + + To illustrate, the following examples all return a dictionary equal to + ``{"one": 1, "two": 2, "three": 3}``:: + + >>> a = dict(one=1, two=2, three=3) + >>> b = {'one': 1, 'two': 2, 'three': 3} + >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3])) + >>> d = dict([('two', 2), ('one', 1), ('three', 3)]) + >>> e = dict({'three': 3, 'one': 1, 'two': 2}) + >>> f = dict({'one': 1, 'three': 3}, two=2) + >>> a == b == c == d == e == f + True + + Providing keyword arguments as in the first example only works for keys that + are valid Python identifiers. Otherwise, any valid keys can be used. + + + These are the operations that dictionaries support (and therefore, custom + mapping types should support too): + + .. describe:: list(d) + + Return a list of all the keys used in the dictionary *d*. + + .. describe:: len(d) + + Return the number of items in the dictionary *d*. + + .. describe:: d[key] + + Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is + not in the map. + + .. index:: __missing__() + + If a subclass of dict defines a method :meth:`__missing__` and *key* + is not present, the ``d[key]`` operation calls that method with the key *key* + as argument. The ``d[key]`` operation then returns or raises whatever is + returned or raised by the ``__missing__(key)`` call. + No other operations or methods invoke :meth:`__missing__`. If + :meth:`__missing__` is not defined, :exc:`KeyError` is raised. + :meth:`__missing__` must be a method; it cannot be an instance variable:: + + >>> class Counter(dict): + ... def __missing__(self, key): + ... return 0 + >>> c = Counter() + >>> c['red'] + 0 + >>> c['red'] += 1 + >>> c['red'] + 1 + + The example above shows part of the implementation of + :class:`collections.Counter`. A different ``__missing__`` method is used + by :class:`collections.defaultdict`. + + .. describe:: d[key] = value + + Set ``d[key]`` to *value*. + + .. describe:: del d[key] + + Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the + map. + + .. describe:: key in d + + Return ``True`` if *d* has a key *key*, else ``False``. + + .. describe:: key not in d + + Equivalent to ``not key in d``. + + .. describe:: iter(d) + + Return an iterator over the keys of the dictionary. This is a shortcut + for ``iter(d.keys())``. + + .. method:: clear() + + Remove all items from the dictionary. + + .. method:: copy() + + Return a shallow copy of the dictionary. + + .. classmethod:: fromkeys(iterable[, value]) + + Create a new dictionary with keys from *iterable* and values set to *value*. + + :meth:`fromkeys` is a class method that returns a new dictionary. *value* + defaults to ``None``. All of the values refer to just a single instance, + so it generally doesn't make sense for *value* to be a mutable object + such as an empty list. To get distinct values, use a :ref:`dict + comprehension ` instead. + + .. method:: get(key[, default]) + + Return the value for *key* if *key* is in the dictionary, else *default*. + If *default* is not given, it defaults to ``None``, so that this method + never raises a :exc:`KeyError`. + + .. method:: items() + + Return a new view of the dictionary's items (``(key, value)`` pairs). + See the :ref:`documentation of view objects `. + + .. method:: keys() + + Return a new view of the dictionary's keys. See the :ref:`documentation + of view objects `. + + .. method:: pop(key[, default]) + + If *key* is in the dictionary, remove it and return its value, else return + *default*. If *default* is not given and *key* is not in the dictionary, + a :exc:`KeyError` is raised. + + .. method:: popitem() + + Remove and return a ``(key, value)`` pair from the dictionary. + Pairs are returned in :abbr:`LIFO (last-in, first-out)` order. + + :meth:`popitem` is useful to destructively iterate over a dictionary, as + often used in set algorithms. If the dictionary is empty, calling + :meth:`popitem` raises a :exc:`KeyError`. + + .. versionchanged:: 3.7 + LIFO order is now guaranteed. In prior versions, :meth:`popitem` would + return an arbitrary key/value pair. + + .. describe:: reversed(d) + + Return a reverse iterator over the keys of the dictionary. This is a + shortcut for ``reversed(d.keys())``. + + .. versionadded:: 3.8 + + .. method:: setdefault(key[, default]) + + If *key* is in the dictionary, return its value. If not, insert *key* + with a value of *default* and return *default*. *default* defaults to + ``None``. + + .. method:: update([other]) + + Update the dictionary with the key/value pairs from *other*, overwriting + existing keys. Return ``None``. + + :meth:`update` accepts either another dictionary object or an iterable of + key/value pairs (as tuples or other iterables of length two). If keyword + arguments are specified, the dictionary is then updated with those + key/value pairs: ``d.update(red=1, blue=2)``. + + .. method:: values() + + Return a new view of the dictionary's values. See the + :ref:`documentation of view objects `. + + An equality comparison between one ``dict.values()`` view and another + will always return ``False``. This also applies when comparing + ``dict.values()`` to itself:: + + >>> d = {'a': 1} + >>> d.values() == d.values() + False + + Dictionaries compare equal if and only if they have the same ``(key, + value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise + :exc:`TypeError`. + + Dictionaries preserve insertion order. Note that updating a key does not + affect the order. Keys added after deletion are inserted at the end. :: + + >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} + >>> d + {'one': 1, 'two': 2, 'three': 3, 'four': 4} + >>> list(d) + ['one', 'two', 'three', 'four'] + >>> list(d.values()) + [1, 2, 3, 4] + >>> d["one"] = 42 + >>> d + {'one': 42, 'two': 2, 'three': 3, 'four': 4} + >>> del d["two"] + >>> d["two"] = None + >>> d + {'one': 42, 'three': 3, 'four': 4, 'two': None} + + .. versionchanged:: 3.7 + Dictionary order is guaranteed to be insertion order. This behavior was + an implementation detail of CPython from 3.6. + + Dictionaries and dictionary views are reversible. :: + + >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} + >>> d + {'one': 1, 'two': 2, 'three': 3, 'four': 4} + >>> list(reversed(d)) + ['four', 'three', 'two', 'one'] + >>> list(reversed(d.values())) + [4, 3, 2, 1] + >>> list(reversed(d.items())) + [('four', 4), ('three', 3), ('two', 2), ('one', 1)] + + .. versionchanged:: 3.8 + Dictionaries are now reversible. + + +.. seealso:: + :class:`types.MappingProxyType` can be used to create a read-only view + of a :class:`dict`. + + +.. _dict-views: + +Dictionary view objects +----------------------- + +The objects returned by :meth:`dict.keys`, :meth:`dict.values` and +:meth:`dict.items` are *view objects*. They provide a dynamic view on the +dictionary's entries, which means that when the dictionary changes, the view +reflects these changes. + +Dictionary views can be iterated over to yield their respective data, and +support membership tests: + +.. describe:: len(dictview) + + Return the number of entries in the dictionary. + +.. describe:: iter(dictview) + + Return an iterator over the keys, values or items (represented as tuples of + ``(key, value)``) in the dictionary. + + Keys and values are iterated over in insertion order. + This allows the creation of ``(value, key)`` pairs + using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to + create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``. + + Iterating views while adding or deleting entries in the dictionary may raise + a :exc:`RuntimeError` or fail to iterate over all entries. + + .. versionchanged:: 3.7 + Dictionary order is guaranteed to be insertion order. + +.. describe:: x in dictview + + Return ``True`` if *x* is in the underlying dictionary's keys, values or + items (in the latter case, *x* should be a ``(key, value)`` tuple). + +.. describe:: reversed(dictview) + + Return a reverse iterator over the keys, values or items of the dictionary. + The view will be iterated in reverse order of the insertion. + + .. versionchanged:: 3.8 + Dictionary views are now reversible. + + +Keys views are set-like since their entries are unique and hashable. If all +values are hashable, so that ``(key, value)`` pairs are unique and hashable, +then the items view is also set-like. (Values views are not treated as set-like +since the entries are generally not unique.) For set-like views, all of the +operations defined for the abstract base class :class:`collections.abc.Set` are +available (for example, ``==``, ``<``, or ``^``). + +An example of dictionary view usage:: + + >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500} + >>> keys = dishes.keys() + >>> values = dishes.values() + + >>> # iteration + >>> n = 0 + >>> for val in values: + ... n += val + >>> print(n) + 504 + + >>> # keys and values are iterated over in the same order (insertion order) + >>> list(keys) + ['eggs', 'sausage', 'bacon', 'spam'] + >>> list(values) + [2, 1, 1, 500] + + >>> # view objects are dynamic and reflect dict changes + >>> del dishes['eggs'] + >>> del dishes['sausage'] + >>> list(keys) + ['bacon', 'spam'] + + >>> # set operations + >>> keys & {'eggs', 'bacon', 'salad'} + {'bacon'} + >>> keys ^ {'sausage', 'juice'} + {'juice', 'sausage', 'bacon', 'spam'} + + +.. _typecontextmanager: + +Context Manager Types +===================== + +.. index:: + single: context manager + single: context management protocol + single: protocol; context management + +Python's :keyword:`with` statement supports the concept of a runtime context +defined by a context manager. This is implemented using a pair of methods +that allow user-defined classes to define a runtime context that is entered +before the statement body is executed and exited when the statement ends: + + +.. method:: contextmanager.__enter__() + + Enter the runtime context and return either this object or another object + related to the runtime context. The value returned by this method is bound to + the identifier in the :keyword:`!as` clause of :keyword:`with` statements using + this context manager. + + An example of a context manager that returns itself is a :term:`file object`. + File objects return themselves from __enter__() to allow :func:`open` to be + used as the context expression in a :keyword:`with` statement. + + An example of a context manager that returns a related object is the one + returned by :func:`decimal.localcontext`. These managers set the active + decimal context to a copy of the original decimal context and then return the + copy. This allows changes to be made to the current decimal context in the body + of the :keyword:`with` statement without affecting code outside the + :keyword:`!with` statement. + + +.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) + + Exit the runtime context and return a Boolean flag indicating if any exception + that occurred should be suppressed. If an exception occurred while executing the + body of the :keyword:`with` statement, the arguments contain the exception type, + value and traceback information. Otherwise, all three arguments are ``None``. + + Returning a true value from this method will cause the :keyword:`with` statement + to suppress the exception and continue execution with the statement immediately + following the :keyword:`!with` statement. Otherwise the exception continues + propagating after this method has finished executing. Exceptions that occur + during execution of this method will replace any exception that occurred in the + body of the :keyword:`!with` statement. + + The exception passed in should never be reraised explicitly - instead, this + method should return a false value to indicate that the method completed + successfully and does not want to suppress the raised exception. This allows + context management code to easily detect whether or not an :meth:`__exit__` + method has actually failed. + +Python defines several context managers to support easy thread synchronisation, +prompt closure of files or other objects, and simpler manipulation of the active +decimal arithmetic context. The specific types are not treated specially beyond +their implementation of the context management protocol. See the +:mod:`contextlib` module for some examples. + +Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator +provide a convenient way to implement these protocols. If a generator function is +decorated with the :class:`contextlib.contextmanager` decorator, it will return a +context manager implementing the necessary :meth:`__enter__` and +:meth:`__exit__` methods, rather than the iterator produced by an undecorated +generator function. + +Note that there is no specific slot for any of these methods in the type +structure for Python objects in the Python/C API. Extension types wanting to +define these methods must provide them as a normal Python accessible method. +Compared to the overhead of setting up the runtime context, the overhead of a +single class dictionary lookup is negligible. + + +.. _typesother: + +Other Built-in Types +==================== + +The interpreter supports several other kinds of objects. Most of these support +only one or two operations. + + +.. _typesmodules: + +Modules +------- + +The only special operation on a module is attribute access: ``m.name``, where +*m* is a module and *name* accesses a name defined in *m*'s symbol table. +Module attributes can be assigned to. (Note that the :keyword:`import` +statement is not, strictly speaking, an operation on a module object; ``import +foo`` does not require a module object named *foo* to exist, rather it requires +an (external) *definition* for a module named *foo* somewhere.) + +A special attribute of every module is :attr:`~object.__dict__`. This is the +dictionary containing the module's symbol table. Modifying this dictionary will +actually change the module's symbol table, but direct assignment to the +:attr:`~object.__dict__` attribute is not possible (you can write +``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write +``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is +not recommended. + +Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ````. + + +.. _typesobjects: + +Classes and Class Instances +--------------------------- + +See :ref:`objects` and :ref:`class` for these. + + +.. _typesfunctions: + +Functions +--------- + +Function objects are created by function definitions. The only operation on a +function object is to call it: ``func(argument-list)``. + +There are really two flavors of function objects: built-in functions and +user-defined functions. Both support the same operation (to call the function), +but the implementation is different, hence the different object types. + +See :ref:`function` for more information. + + +.. _typesmethods: + +Methods +------- + +.. index:: object: method + +Methods are functions that are called using the attribute notation. There are +two flavors: built-in methods (such as :meth:`append` on lists) and class +instance methods. Built-in methods are described with the types that support +them. + +If you access a method (a function defined in a class namespace) through an +instance, you get a special object: a :dfn:`bound method` (also called +:dfn:`instance method`) object. When called, it will add the ``self`` argument +to the argument list. Bound methods have two special read-only attributes: +``m.__self__`` is the object on which the method operates, and ``m.__func__`` is +the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)`` +is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ..., +arg-n)``. + +Like function objects, bound method objects support getting arbitrary +attributes. However, since method attributes are actually stored on the +underlying function object (``meth.__func__``), setting method attributes on +bound methods is disallowed. Attempting to set an attribute on a method +results in an :exc:`AttributeError` being raised. In order to set a method +attribute, you need to explicitly set it on the underlying function object:: + + >>> class C: + ... def method(self): + ... pass + ... + >>> c = C() + >>> c.method.whoami = 'my name is method' # can't set on the method + Traceback (most recent call last): + File "", line 1, in + AttributeError: 'method' object has no attribute 'whoami' + >>> c.method.__func__.whoami = 'my name is method' + >>> c.method.whoami + 'my name is method' + +See :ref:`types` for more information. + + +.. index:: object; code, code object + +.. _bltin-code-objects: + +Code Objects +------------ + +.. index:: + builtin: compile + single: __code__ (function object attribute) + +Code objects are used by the implementation to represent "pseudo-compiled" +executable Python code such as a function body. They differ from function +objects because they don't contain a reference to their global execution +environment. Code objects are returned by the built-in :func:`compile` function +and can be extracted from function objects through their :attr:`__code__` +attribute. See also the :mod:`code` module. + +.. index:: + builtin: exec + builtin: eval + +A code object can be executed or evaluated by passing it (instead of a source +string) to the :func:`exec` or :func:`eval` built-in functions. + +See :ref:`types` for more information. + + +.. _bltin-type-objects: + +Type Objects +------------ + +.. index:: + builtin: type + module: types + +Type objects represent the various object types. An object's type is accessed +by the built-in function :func:`type`. There are no special operations on +types. The standard module :mod:`types` defines names for all standard built-in +types. + +Types are written like this: ````. + + +.. _bltin-null-object: + +The Null Object +--------------- + +This object is returned by functions that don't explicitly return a value. It +supports no special operations. There is exactly one null object, named +``None`` (a built-in name). ``type(None)()`` produces the same singleton. + +It is written as ``None``. + + +.. index:: single: ...; ellipsis literal +.. _bltin-ellipsis-object: + +The Ellipsis Object +------------------- + +This object is commonly used by slicing (see :ref:`slicings`). It supports no +special operations. There is exactly one ellipsis object, named +:const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the +:const:`Ellipsis` singleton. + +It is written as ``Ellipsis`` or ``...``. + + +.. _bltin-notimplemented-object: + +The NotImplemented Object +------------------------- + +This object is returned from comparisons and binary operations when they are +asked to operate on types they don't support. See :ref:`comparisons` for more +information. There is exactly one ``NotImplemented`` object. +``type(NotImplemented)()`` produces the singleton instance. + +It is written as ``NotImplemented``. + + +.. _bltin-boolean-values: + +Boolean Values +-------------- + +Boolean values are the two constant objects ``False`` and ``True``. They are +used to represent truth values (although other values can also be considered +false or true). In numeric contexts (for example when used as the argument to +an arithmetic operator), they behave like the integers 0 and 1, respectively. +The built-in function :func:`bool` can be used to convert any value to a +Boolean, if the value can be interpreted as a truth value (see section +:ref:`truth` above). + +.. index:: + single: False + single: True + pair: Boolean; values + +They are written as ``False`` and ``True``, respectively. + + +.. _typesinternal: + +Internal Objects +---------------- + +See :ref:`types` for this information. It describes stack frame objects, +traceback objects, and slice objects. + + +.. _specialattrs: + +Special Attributes +================== + +The implementation adds a few special read-only attributes to several object +types, where they are relevant. Some of these are not reported by the +:func:`dir` built-in function. + + +.. attribute:: object.__dict__ + + A dictionary or other mapping object used to store an object's (writable) + attributes. + + +.. attribute:: instance.__class__ + + The class to which a class instance belongs. + + +.. attribute:: class.__bases__ + + The tuple of base classes of a class object. + + +.. attribute:: definition.__name__ + + The name of the class, function, method, descriptor, or + generator instance. + + +.. attribute:: definition.__qualname__ + + The :term:`qualified name` of the class, function, method, descriptor, + or generator instance. + + .. versionadded:: 3.3 + + +.. attribute:: class.__mro__ + + This attribute is a tuple of classes that are considered when looking for + base classes during method resolution. + + +.. method:: class.mro() + + This method can be overridden by a metaclass to customize the method + resolution order for its instances. It is called at class instantiation, and + its result is stored in :attr:`~class.__mro__`. + + +.. method:: class.__subclasses__ + + Each class keeps a list of weak references to its immediate subclasses. This + method returns a list of all those references still alive. + Example:: + + >>> int.__subclasses__() + [] + + +.. rubric:: Footnotes + +.. [1] Additional information on these special methods may be found in the Python + Reference Manual (:ref:`customization`). + +.. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and + similarly for tuples. + +.. [3] They must have since the parser can't tell the type of the operands. + +.. [4] Cased characters are those with general category property being one of + "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase). + +.. [5] To format only a tuple you should therefore provide a singleton tuple whose only + element is the tuple to be formatted. diff --git a/Doc/library/sys.rst.bak b/Doc/library/sys.rst.bak new file mode 100644 index 00000000000000..d28b3565c1c633 --- /dev/null +++ b/Doc/library/sys.rst.bak @@ -0,0 +1,1652 @@ +:mod:`sys` --- System-specific parameters and functions +======================================================= + +.. module:: sys + :synopsis: Access system-specific parameters and functions. + +-------------- + +This module provides access to some variables used or maintained by the +interpreter and to functions that interact strongly with the interpreter. It is +always available. + + +.. data:: abiflags + + On POSIX systems where Python was built with the standard ``configure`` + script, this contains the ABI flags as specified by :pep:`3149`. + + .. versionchanged:: 3.8 + Default flags became an empty string (``m`` flag for pymalloc has been + removed). + + .. versionadded:: 3.2 + + +.. function:: addaudithook(hook) + + Append the callable *hook* to the list of active auditing hooks for the + current interpreter. + + When an auditing event is raised through the :func:`sys.audit` function, each + hook will be called in the order it was added with the event name and the + tuple of arguments. Native hooks added by :c:func:`PySys_AddAuditHook` are + called first, followed by hooks added in the current interpreter. + + .. audit-event:: sys.addaudithook "" sys.addaudithook + + Raise an auditing event ``sys.addaudithook`` with no arguments. If any + existing hooks raise an exception derived from :class:`RuntimeError`, the + new hook will not be added and the exception suppressed. As a result, + callers cannot assume that their hook has been added unless they control + all existing hooks. + + .. versionadded:: 3.8 + + .. versionchanged:: 3.8.1 + + Exceptions derived from :class:`Exception` but not :class:`RuntimeError` + are no longer suppressed. + + .. impl-detail:: + + When tracing is enabled (see :func:`settrace`), Python hooks are only + traced if the callable has a ``__cantrace__`` member that is set to a + true value. Otherwise, trace functions will skip the hook. + + +.. data:: argv + + The list of command line arguments passed to a Python script. ``argv[0]`` is the + script name (it is operating system dependent whether this is a full pathname or + not). If the command was executed using the :option:`-c` command line option to + the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name + was passed to the Python interpreter, ``argv[0]`` is the empty string. + + To loop over the standard input, or the list of files given on the + command line, see the :mod:`fileinput` module. + + .. note:: + On Unix, command line arguments are passed by bytes from OS. Python decodes + them with filesystem encoding and "surrogateescape" error handler. + When you need original bytes, you can get it by + ``[os.fsencode(arg) for arg in sys.argv]``. + + +.. _auditing: + +.. function:: audit(event, *args) + + .. index:: single: auditing + + Raise an auditing event with any active hooks. The event name is a string + identifying the event and its associated schema, which is the number and + types of arguments. The schema for a given event is considered public and + stable API and should not be modified between releases. + + This function will raise the first exception raised by any hook. In general, + these errors should not be handled and should terminate the process as + quickly as possible. + + Hooks are added using the :func:`sys.addaudithook` or + :c:func:`PySys_AddAuditHook` functions. + + The native equivalent of this function is :c:func:`PySys_Audit`. Using the + native function is preferred when possible. + + See the :ref:`audit events table ` for all events raised by + CPython. + + .. versionadded:: 3.8 + + +.. data:: base_exec_prefix + + Set during Python startup, before ``site.py`` is run, to the same value as + :data:`exec_prefix`. If not running in a + :ref:`virtual environment `, the values will stay the same; if + ``site.py`` finds that a virtual environment is in use, the values of + :data:`prefix` and :data:`exec_prefix` will be changed to point to the + virtual environment, whereas :data:`base_prefix` and + :data:`base_exec_prefix` will remain pointing to the base Python + installation (the one which the virtual environment was created from). + + .. versionadded:: 3.3 + + +.. data:: base_prefix + + Set during Python startup, before ``site.py`` is run, to the same value as + :data:`prefix`. If not running in a :ref:`virtual environment `, the values + will stay the same; if ``site.py`` finds that a virtual environment is in + use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to + point to the virtual environment, whereas :data:`base_prefix` and + :data:`base_exec_prefix` will remain pointing to the base Python + installation (the one which the virtual environment was created from). + + .. versionadded:: 3.3 + + +.. data:: byteorder + + An indicator of the native byte order. This will have the value ``'big'`` on + big-endian (most-significant byte first) platforms, and ``'little'`` on + little-endian (least-significant byte first) platforms. + + +.. data:: builtin_module_names + + A tuple of strings giving the names of all modules that are compiled into this + Python interpreter. (This information is not available in any other way --- + ``modules.keys()`` only lists the imported modules.) + + +.. function:: call_tracing(func, args) + + Call ``func(*args)``, while tracing is enabled. The tracing state is saved, + and restored afterwards. This is intended to be called from a debugger from + a checkpoint, to recursively debug some other code. + + +.. data:: copyright + + A string containing the copyright pertaining to the Python interpreter. + + +.. function:: _clear_type_cache() + + Clear the internal type cache. The type cache is used to speed up attribute + and method lookups. Use the function *only* to drop unnecessary references + during reference leak debugging. + + This function should be used for internal and specialized purposes only. + + +.. function:: _current_frames() + + Return a dictionary mapping each thread's identifier to the topmost stack frame + currently active in that thread at the time the function is called. Note that + functions in the :mod:`traceback` module can build the call stack given such a + frame. + + This is most useful for debugging deadlock: this function does not require the + deadlocked threads' cooperation, and such threads' call stacks are frozen for as + long as they remain deadlocked. The frame returned for a non-deadlocked thread + may bear no relationship to that thread's current activity by the time calling + code examines the frame. + + This function should be used for internal and specialized purposes only. + + .. audit-event:: sys._current_frames "" sys._current_frames + + +.. function:: breakpointhook() + + This hook function is called by built-in :func:`breakpoint`. By default, + it drops you into the :mod:`pdb` debugger, but it can be set to any other + function so that you can choose which debugger gets used. + + The signature of this function is dependent on what it calls. For example, + the default binding (e.g. ``pdb.set_trace()``) expects no arguments, but + you might bind it to a function that expects additional arguments + (positional and/or keyword). The built-in ``breakpoint()`` function passes + its ``*args`` and ``**kws`` straight through. Whatever + ``breakpointhooks()`` returns is returned from ``breakpoint()``. + + The default implementation first consults the environment variable + :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function + returns immediately; i.e. it is a no-op. If the environment variable is + not set, or is set to the empty string, ``pdb.set_trace()`` is called. + Otherwise this variable should name a function to run, using Python's + dotted-import nomenclature, e.g. ``package.subpackage.module.function``. + In this case, ``package.subpackage.module`` would be imported and the + resulting module must have a callable named ``function()``. This is run, + passing in ``*args`` and ``**kws``, and whatever ``function()`` returns, + ``sys.breakpointhook()`` returns to the built-in :func:`breakpoint` + function. + + Note that if anything goes wrong while importing the callable named by + :envvar:`PYTHONBREAKPOINT`, a :exc:`RuntimeWarning` is reported and the + breakpoint is ignored. + + Also note that if ``sys.breakpointhook()`` is overridden programmatically, + :envvar:`PYTHONBREAKPOINT` is *not* consulted. + + .. versionadded:: 3.7 + +.. function:: _debugmallocstats() + + Print low-level information to stderr about the state of CPython's memory + allocator. + + If Python is configured --with-pydebug, it also performs some expensive + internal consistency checks. + + .. versionadded:: 3.3 + + .. impl-detail:: + + This function is specific to CPython. The exact output format is not + defined here, and may change. + + +.. data:: dllhandle + + Integer specifying the handle of the Python DLL. + + .. availability:: Windows. + + +.. function:: displayhook(value) + + If *value* is not ``None``, this function prints ``repr(value)`` to + ``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is + not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error + handler (which is probably ``'strict'``), encode it to + ``sys.stdout.encoding`` with ``'backslashreplace'`` error handler. + + ``sys.displayhook`` is called on the result of evaluating an :term:`expression` + entered in an interactive Python session. The display of these values can be + customized by assigning another one-argument function to ``sys.displayhook``. + + Pseudo-code:: + + def displayhook(value): + if value is None: + return + # Set '_' to None to avoid recursion + builtins._ = None + text = repr(value) + try: + sys.stdout.write(text) + except UnicodeEncodeError: + bytes = text.encode(sys.stdout.encoding, 'backslashreplace') + if hasattr(sys.stdout, 'buffer'): + sys.stdout.buffer.write(bytes) + else: + text = bytes.decode(sys.stdout.encoding, 'strict') + sys.stdout.write(text) + sys.stdout.write("\n") + builtins._ = value + + .. versionchanged:: 3.2 + Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`. + + +.. data:: dont_write_bytecode + + If this is true, Python won't try to write ``.pyc`` files on the + import of source modules. This value is initially set to ``True`` or + ``False`` depending on the :option:`-B` command line option and the + :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it + yourself to control bytecode file generation. + + +.. data:: pycache_prefix + + If this is set (not ``None``), Python will write bytecode-cache ``.pyc`` + files to (and read them from) a parallel directory tree rooted at this + directory, rather than from ``__pycache__`` directories in the source code + tree. Any ``__pycache__`` directories in the source code tree will be ignored + and new `.pyc` files written within the pycache prefix. Thus if you use + :mod:`compileall` as a pre-build step, you must ensure you run it with the + same pycache prefix (if any) that you will use at runtime. + + A relative path is interpreted relative to the current working directory. + + This value is initially set based on the value of the :option:`-X` + ``pycache_prefix=PATH`` command-line option or the + :envvar:`PYTHONPYCACHEPREFIX` environment variable (command-line takes + precedence). If neither are set, it is ``None``. + + .. versionadded:: 3.8 + + +.. function:: excepthook(type, value, traceback) + + This function prints out a given traceback and exception to ``sys.stderr``. + + When an exception is raised and uncaught, the interpreter calls + ``sys.excepthook`` with three arguments, the exception class, exception + instance, and a traceback object. In an interactive session this happens just + before control is returned to the prompt; in a Python program this happens just + before the program exits. The handling of such top-level exceptions can be + customized by assigning another three-argument function to ``sys.excepthook``. + + .. audit-event:: sys.excepthook hook,type,value,traceback sys.excepthook + + Raise an auditing event ``sys.excepthook`` with arguments ``hook``, + ``type``, ``value``, ``traceback`` when an uncaught exception occurs. + If no hook has been set, ``hook`` may be ``None``. If any hook raises + an exception derived from :class:`RuntimeError` the call to the hook will + be suppressed. Otherwise, the audit hook exception will be reported as + unraisable and ``sys.excepthook`` will be called. + + .. seealso:: + + The :func:`sys.unraisablehook` function handles unraisable exceptions + and the :func:`threading.excepthook` function handles exception raised + by :func:`threading.Thread.run`. + + +.. data:: __breakpointhook__ + __displayhook__ + __excepthook__ + __unraisablehook__ + + These objects contain the original values of ``breakpointhook``, + ``displayhook``, ``excepthook``, and ``unraisablehook`` at the start of the + program. They are saved so that ``breakpointhook``, ``displayhook`` and + ``excepthook``, ``unraisablehook`` can be restored in case they happen to + get replaced with broken or alternative objects. + + .. versionadded:: 3.7 + __breakpointhook__ + + +.. function:: exc_info() + + This function returns a tuple of three values that give information about the + exception that is currently being handled. The information returned is specific + both to the current thread and to the current stack frame. If the current stack + frame is not handling an exception, the information is taken from the calling + stack frame, or its caller, and so on until a stack frame is found that is + handling an exception. Here, "handling an exception" is defined as "executing + an except clause." For any stack frame, only information about the exception + being currently handled is accessible. + + .. index:: object: traceback + + If no exception is being handled anywhere on the stack, a tuple containing + three ``None`` values is returned. Otherwise, the values returned are + ``(type, value, traceback)``. Their meaning is: *type* gets the type of the + exception being handled (a subclass of :exc:`BaseException`); *value* gets + the exception instance (an instance of the exception type); *traceback* gets + a :ref:`traceback object ` which encapsulates the call + stack at the point where the exception originally occurred. + + +.. data:: exec_prefix + + A string giving the site-specific directory prefix where the platform-dependent + Python files are installed; by default, this is also ``'/usr/local'``. This can + be set at build time with the ``--exec-prefix`` argument to the + :program:`configure` script. Specifically, all configuration files (e.g. the + :file:`pyconfig.h` header file) are installed in the directory + :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are + installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y* + is the version number of Python, for example ``3.2``. + + .. note:: + + If a :ref:`virtual environment ` is in effect, this + value will be changed in ``site.py`` to point to the virtual environment. + The value for the Python installation will still be available, via + :data:`base_exec_prefix`. + + +.. data:: executable + + A string giving the absolute path of the executable binary for the Python + interpreter, on systems where this makes sense. If Python is unable to retrieve + the real path to its executable, :data:`sys.executable` will be an empty string + or ``None``. + + +.. function:: exit([arg]) + + Exit from Python. This is implemented by raising the :exc:`SystemExit` + exception, so cleanup actions specified by finally clauses of :keyword:`try` + statements are honored, and it is possible to intercept the exit attempt at + an outer level. + + The optional argument *arg* can be an integer giving the exit status + (defaulting to zero), or another type of object. If it is an integer, zero + is considered "successful termination" and any nonzero value is considered + "abnormal termination" by shells and the like. Most systems require it to be + in the range 0--127, and produce undefined results otherwise. Some systems + have a convention for assigning specific meanings to specific exit codes, but + these are generally underdeveloped; Unix programs generally use 2 for command + line syntax errors and 1 for all other kind of errors. If another type of + object is passed, ``None`` is equivalent to passing zero, and any other + object is printed to :data:`stderr` and results in an exit code of 1. In + particular, ``sys.exit("some error message")`` is a quick way to exit a + program when an error occurs. + + Since :func:`exit` ultimately "only" raises an exception, it will only exit + the process when called from the main thread, and the exception is not + intercepted. + + .. versionchanged:: 3.6 + If an error occurs in the cleanup after the Python interpreter + has caught :exc:`SystemExit` (such as an error flushing buffered data + in the standard streams), the exit status is changed to 120. + + +.. data:: flags + + The :term:`named tuple` *flags* exposes the status of command line + flags. The attributes are read only. + + ============================= ================================================================ + attribute flag + ============================= ================================================================ + :const:`debug` :option:`-d` + :const:`inspect` :option:`-i` + :const:`interactive` :option:`-i` + :const:`isolated` :option:`-I` + :const:`optimize` :option:`-O` or :option:`-OO` + :const:`dont_write_bytecode` :option:`-B` + :const:`no_user_site` :option:`-s` + :const:`no_site` :option:`-S` + :const:`ignore_environment` :option:`-E` + :const:`verbose` :option:`-v` + :const:`bytes_warning` :option:`-b` + :const:`quiet` :option:`-q` + :const:`hash_randomization` :option:`-R` + :const:`dev_mode` :option:`-X dev <-X>` (:ref:`Python Development Mode `) + :const:`utf8_mode` :option:`-X utf8 <-X>` + ============================= ================================================================ + + .. versionchanged:: 3.2 + Added ``quiet`` attribute for the new :option:`-q` flag. + + .. versionadded:: 3.2.3 + The ``hash_randomization`` attribute. + + .. versionchanged:: 3.3 + Removed obsolete ``division_warning`` attribute. + + .. versionchanged:: 3.4 + Added ``isolated`` attribute for :option:`-I` ``isolated`` flag. + + .. versionchanged:: 3.7 + Added the ``dev_mode`` attribute for the new :ref:`Python Development + Mode ` and the ``utf8_mode`` attribute for the new :option:`-X` + ``utf8`` flag. + + +.. data:: float_info + + A :term:`named tuple` holding information about the float type. It + contains low level information about the precision and internal + representation. The values correspond to the various floating-point + constants defined in the standard header file :file:`float.h` for the 'C' + programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard + [C99]_, 'Characteristics of floating types', for details. + + .. tabularcolumns:: |l|l|L| + + +---------------------+----------------+--------------------------------------------------+ + | attribute | float.h macro | explanation | + +=====================+================+==================================================+ + | :const:`epsilon` | DBL_EPSILON | difference between 1.0 and the least value | + | | | greater than 1.0 that is representable as a float| + | | | | + | | | See also :func:`math.ulp`. | + +---------------------+----------------+--------------------------------------------------+ + | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be | + | | | faithfully represented in a float; see below | + +---------------------+----------------+--------------------------------------------------+ + | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` | + | | | digits in the significand of a float | + +---------------------+----------------+--------------------------------------------------+ + | :const:`max` | DBL_MAX | maximum representable positive finite float | + +---------------------+----------------+--------------------------------------------------+ + | :const:`max_exp` | DBL_MAX_EXP | maximum integer *e* such that ``radix**(e-1)`` is| + | | | a representable finite float | + +---------------------+----------------+--------------------------------------------------+ + | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer *e* such that ``10**e`` is in the| + | | | range of representable finite floats | + +---------------------+----------------+--------------------------------------------------+ + | :const:`min` | DBL_MIN | minimum representable positive *normalized* float| + | | | | + | | | Use :func:`math.ulp(0.0) ` to get the | + | | | smallest positive *denormalized* representable | + | | | float. | + +---------------------+----------------+--------------------------------------------------+ + | :const:`min_exp` | DBL_MIN_EXP | minimum integer *e* such that ``radix**(e-1)`` is| + | | | a normalized float | + +---------------------+----------------+--------------------------------------------------+ + | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer *e* such that ``10**e`` is a | + | | | normalized float | + +---------------------+----------------+--------------------------------------------------+ + | :const:`radix` | FLT_RADIX | radix of exponent representation | + +---------------------+----------------+--------------------------------------------------+ + | :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode | + | | | used for arithmetic operations. This reflects | + | | | the value of the system FLT_ROUNDS macro at | + | | | interpreter startup time. See section 5.2.4.2.2 | + | | | of the C99 standard for an explanation of the | + | | | possible values and their meanings. | + +---------------------+----------------+--------------------------------------------------+ + + The attribute :attr:`sys.float_info.dig` needs further explanation. If + ``s`` is any string representing a decimal number with at most + :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a + float and back again will recover a string representing the same decimal + value:: + + >>> import sys + >>> sys.float_info.dig + 15 + >>> s = '3.14159265358979' # decimal string with 15 significant digits + >>> format(float(s), '.15g') # convert to float and back -> same value + '3.14159265358979' + + But for strings with more than :attr:`sys.float_info.dig` significant digits, + this isn't always true:: + + >>> s = '9876543211234567' # 16 significant digits is too many! + >>> format(float(s), '.16g') # conversion changes value + '9876543211234568' + +.. data:: float_repr_style + + A string indicating how the :func:`repr` function behaves for + floats. If the string has value ``'short'`` then for a finite + float ``x``, ``repr(x)`` aims to produce a short string with the + property that ``float(repr(x)) == x``. This is the usual behaviour + in Python 3.1 and later. Otherwise, ``float_repr_style`` has value + ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in + versions of Python prior to 3.1. + + .. versionadded:: 3.1 + + +.. function:: getallocatedblocks() + + Return the number of memory blocks currently allocated by the interpreter, + regardless of their size. This function is mainly useful for tracking + and debugging memory leaks. Because of the interpreter's internal + caches, the result can vary from call to call; you may have to call + :func:`_clear_type_cache()` and :func:`gc.collect()` to get more + predictable results. + + If a Python build or implementation cannot reasonably compute this + information, :func:`getallocatedblocks()` is allowed to return 0 instead. + + .. versionadded:: 3.4 + + +.. function:: getandroidapilevel() + + Return the build time API version of Android as an integer. + + .. availability:: Android. + + .. versionadded:: 3.7 + + +.. function:: getdefaultencoding() + + Return the name of the current default string encoding used by the Unicode + implementation. + + +.. function:: getdlopenflags() + + Return the current value of the flags that are used for + :c:func:`dlopen` calls. Symbolic names for the flag values can be + found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. + :data:`os.RTLD_LAZY`). + + .. availability:: Unix. + + +.. function:: getfilesystemencoding() + + Return the name of the encoding used to convert between Unicode + filenames and bytes filenames. For best compatibility, str should be + used for filenames in all cases, although representing filenames as bytes + is also supported. Functions accepting or returning filenames should support + either str or bytes and internally convert to the system's preferred + representation. + + This encoding is always ASCII-compatible. + + :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that + the correct encoding and errors mode are used. + + * In the UTF-8 mode, the encoding is ``utf-8`` on any platform. + + * On macOS, the encoding is ``'utf-8'``. + + * On Unix, the encoding is the locale encoding. + + * On Windows, the encoding may be ``'utf-8'`` or ``'mbcs'``, depending + on user configuration. + + * On Android, the encoding is ``'utf-8'``. + + * On VxWorks, the encoding is ``'utf-8'``. + + .. versionchanged:: 3.2 + :func:`getfilesystemencoding` result cannot be ``None`` anymore. + + .. versionchanged:: 3.6 + Windows is no longer guaranteed to return ``'mbcs'``. See :pep:`529` + and :func:`_enablelegacywindowsfsencoding` for more information. + + .. versionchanged:: 3.7 + Return 'utf-8' in the UTF-8 mode. + + +.. function:: getfilesystemencodeerrors() + + Return the name of the error mode used to convert between Unicode filenames + and bytes filenames. The encoding name is returned from + :func:`getfilesystemencoding`. + + :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that + the correct encoding and errors mode are used. + + .. versionadded:: 3.6 + +.. function:: getrefcount(object) + + Return the reference count of the *object*. The count returned is generally one + higher than you might expect, because it includes the (temporary) reference as + an argument to :func:`getrefcount`. + + +.. function:: getrecursionlimit() + + Return the current value of the recursion limit, the maximum depth of the Python + interpreter stack. This limit prevents infinite recursion from causing an + overflow of the C stack and crashing Python. It can be set by + :func:`setrecursionlimit`. + + +.. function:: getsizeof(object[, default]) + + Return the size of an object in bytes. The object can be any type of + object. All built-in objects will return correct results, but this + does not have to hold true for third-party extensions as it is implementation + specific. + + Only the memory consumption directly attributed to the object is + accounted for, not the memory consumption of objects it refers to. + + If given, *default* will be returned if the object does not provide means to + retrieve the size. Otherwise a :exc:`TypeError` will be raised. + + :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an + additional garbage collector overhead if the object is managed by the garbage + collector. + + See `recursive sizeof recipe `_ + for an example of using :func:`getsizeof` recursively to find the size of + containers and all their contents. + +.. function:: getswitchinterval() + + Return the interpreter's "thread switch interval"; see + :func:`setswitchinterval`. + + .. versionadded:: 3.2 + + +.. function:: _getframe([depth]) + + Return a frame object from the call stack. If optional integer *depth* is + given, return the frame object that many calls below the top of the stack. If + that is deeper than the call stack, :exc:`ValueError` is raised. The default + for *depth* is zero, returning the frame at the top of the call stack. + + .. audit-event:: sys._getframe "" sys._getframe + + .. impl-detail:: + + This function should be used for internal and specialized purposes only. + It is not guaranteed to exist in all implementations of Python. + + +.. function:: getprofile() + + .. index:: + single: profile function + single: profiler + + Get the profiler function as set by :func:`setprofile`. + + +.. function:: gettrace() + + .. index:: + single: trace function + single: debugger + + Get the trace function as set by :func:`settrace`. + + .. impl-detail:: + + The :func:`gettrace` function is intended only for implementing debuggers, + profilers, coverage tools and the like. Its behavior is part of the + implementation platform, rather than part of the language definition, and + thus may not be available in all Python implementations. + + +.. function:: getwindowsversion() + + Return a named tuple describing the Windows version + currently running. The named elements are *major*, *minor*, + *build*, *platform*, *service_pack*, *service_pack_minor*, + *service_pack_major*, *suite_mask*, *product_type* and + *platform_version*. *service_pack* contains a string, + *platform_version* a 3-tuple and all other values are + integers. The components can also be accessed by name, so + ``sys.getwindowsversion()[0]`` is equivalent to + ``sys.getwindowsversion().major``. For compatibility with prior + versions, only the first 5 elements are retrievable by indexing. + + *platform* will be :const:`2 (VER_PLATFORM_WIN32_NT)`. + + *product_type* may be one of the following values: + + +---------------------------------------+---------------------------------+ + | Constant | Meaning | + +=======================================+=================================+ + | :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. | + +---------------------------------------+---------------------------------+ + | :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain | + | | controller. | + +---------------------------------------+---------------------------------+ + | :const:`3 (VER_NT_SERVER)` | The system is a server, but not | + | | a domain controller. | + +---------------------------------------+---------------------------------+ + + This function wraps the Win32 :c:func:`GetVersionEx` function; see the + Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information + about these fields. + + *platform_version* returns the accurate major version, minor version and + build number of the current operating system, rather than the version that + is being emulated for the process. It is intended for use in logging rather + than for feature detection. + + .. availability:: Windows. + + .. versionchanged:: 3.2 + Changed to a named tuple and added *service_pack_minor*, + *service_pack_major*, *suite_mask*, and *product_type*. + + .. versionchanged:: 3.6 + Added *platform_version* + + +.. function:: get_asyncgen_hooks() + + Returns an *asyncgen_hooks* object, which is similar to a + :class:`~collections.namedtuple` of the form `(firstiter, finalizer)`, + where *firstiter* and *finalizer* are expected to be either ``None`` or + functions which take an :term:`asynchronous generator iterator` as an + argument, and are used to schedule finalization of an asynchronous + generator by an event loop. + + .. versionadded:: 3.6 + See :pep:`525` for more details. + + .. note:: + This function has been added on a provisional basis (see :pep:`411` + for details.) + + +.. function:: get_coroutine_origin_tracking_depth() + + Get the current coroutine origin tracking depth, as set by + :func:`set_coroutine_origin_tracking_depth`. + + .. versionadded:: 3.7 + + .. note:: + This function has been added on a provisional basis (see :pep:`411` + for details.) Use it only for debugging purposes. + + +.. data:: hash_info + + A :term:`named tuple` giving parameters of the numeric hash + implementation. For more details about hashing of numeric types, see + :ref:`numeric-hash`. + + +---------------------+--------------------------------------------------+ + | attribute | explanation | + +=====================+==================================================+ + | :const:`width` | width in bits used for hash values | + +---------------------+--------------------------------------------------+ + | :const:`modulus` | prime modulus P used for numeric hash scheme | + +---------------------+--------------------------------------------------+ + | :const:`inf` | hash value returned for a positive infinity | + +---------------------+--------------------------------------------------+ + | :const:`nan` | hash value returned for a nan | + +---------------------+--------------------------------------------------+ + | :const:`imag` | multiplier used for the imaginary part of a | + | | complex number | + +---------------------+--------------------------------------------------+ + | :const:`algorithm` | name of the algorithm for hashing of str, bytes, | + | | and memoryview | + +---------------------+--------------------------------------------------+ + | :const:`hash_bits` | internal output size of the hash algorithm | + +---------------------+--------------------------------------------------+ + | :const:`seed_bits` | size of the seed key of the hash algorithm | + +---------------------+--------------------------------------------------+ + + + .. versionadded:: 3.2 + + .. versionchanged:: 3.4 + Added *algorithm*, *hash_bits* and *seed_bits* + + +.. data:: hexversion + + The version number encoded as a single integer. This is guaranteed to increase + with each version, including proper support for non-production releases. For + example, to test that the Python interpreter is at least version 1.5.2, use:: + + if sys.hexversion >= 0x010502F0: + # use some advanced feature + ... + else: + # use an alternative implementation or warn the user + ... + + This is called ``hexversion`` since it only really looks meaningful when viewed + as the result of passing it to the built-in :func:`hex` function. The + :term:`named tuple` :data:`sys.version_info` may be used for a more + human-friendly encoding of the same information. + + More details of ``hexversion`` can be found at :ref:`apiabiversion`. + + +.. data:: implementation + + An object containing information about the implementation of the + currently running Python interpreter. The following attributes are + required to exist in all Python implementations. + + *name* is the implementation's identifier, e.g. ``'cpython'``. The actual + string is defined by the Python implementation, but it is guaranteed to be + lower case. + + *version* is a named tuple, in the same format as + :data:`sys.version_info`. It represents the version of the Python + *implementation*. This has a distinct meaning from the specific + version of the Python *language* to which the currently running + interpreter conforms, which ``sys.version_info`` represents. For + example, for PyPy 1.8 ``sys.implementation.version`` might be + ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info`` + would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they + are the same value, since it is the reference implementation. + + *hexversion* is the implementation version in hexadecimal format, like + :data:`sys.hexversion`. + + *cache_tag* is the tag used by the import machinery in the filenames of + cached modules. By convention, it would be a composite of the + implementation's name and version, like ``'cpython-33'``. However, a + Python implementation may use some other value if appropriate. If + ``cache_tag`` is set to ``None``, it indicates that module caching should + be disabled. + + :data:`sys.implementation` may contain additional attributes specific to + the Python implementation. These non-standard attributes must start with + an underscore, and are not described here. Regardless of its contents, + :data:`sys.implementation` will not change during a run of the interpreter, + nor between implementation versions. (It may change between Python + language versions, however.) See :pep:`421` for more information. + + .. versionadded:: 3.3 + + .. note:: + + The addition of new required attributes must go through the normal PEP + process. See :pep:`421` for more information. + +.. data:: int_info + + A :term:`named tuple` that holds information about Python's internal + representation of integers. The attributes are read only. + + .. tabularcolumns:: |l|L| + + +-------------------------+----------------------------------------------+ + | Attribute | Explanation | + +=========================+==============================================+ + | :const:`bits_per_digit` | number of bits held in each digit. Python | + | | integers are stored internally in base | + | | ``2**int_info.bits_per_digit`` | + +-------------------------+----------------------------------------------+ + | :const:`sizeof_digit` | size in bytes of the C type used to | + | | represent a digit | + +-------------------------+----------------------------------------------+ + + .. versionadded:: 3.1 + + +.. data:: __interactivehook__ + + When this attribute exists, its value is automatically called (with no + arguments) when the interpreter is launched in :ref:`interactive mode + `. This is done after the :envvar:`PYTHONSTARTUP` file is + read, so that you can set this hook there. The :mod:`site` module + :ref:`sets this `. + + .. audit-event:: cpython.run_interactivehook hook sys.__interactivehook__ + + Raises an :ref:`auditing event ` + ``cpython.run_interactivehook`` with the hook object as the argument when + the hook is called on startup. + + .. versionadded:: 3.4 + + +.. function:: intern(string) + + Enter *string* in the table of "interned" strings and return the interned string + -- which is *string* itself or a copy. Interning strings is useful to gain a + little performance on dictionary lookup -- if the keys in a dictionary are + interned, and the lookup key is interned, the key comparisons (after hashing) + can be done by a pointer compare instead of a string compare. Normally, the + names used in Python programs are automatically interned, and the dictionaries + used to hold module, class or instance attributes have interned keys. + + Interned strings are not immortal; you must keep a reference to the return + value of :func:`intern` around to benefit from it. + + +.. function:: is_finalizing() + + Return :const:`True` if the Python interpreter is + :term:`shutting down `, :const:`False` otherwise. + + .. versionadded:: 3.5 + + +.. data:: last_type + last_value + last_traceback + + These three variables are not always defined; they are set when an exception is + not handled and the interpreter prints an error message and a stack traceback. + Their intended use is to allow an interactive user to import a debugger module + and engage in post-mortem debugging without having to re-execute the command + that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the + post-mortem debugger; see :mod:`pdb` module for + more information.) + + The meaning of the variables is the same as that of the return values from + :func:`exc_info` above. + + +.. data:: maxsize + + An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can + take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a + 64-bit platform. + + +.. data:: maxunicode + + An integer giving the value of the largest Unicode code point, + i.e. ``1114111`` (``0x10FFFF`` in hexadecimal). + + .. versionchanged:: 3.3 + Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF`` + or ``0x10FFFF``, depending on the configuration option that specified + whether Unicode characters were stored as UCS-2 or UCS-4. + + +.. data:: meta_path + + A list of :term:`meta path finder` objects that have their + :meth:`~importlib.abc.MetaPathFinder.find_spec` methods called to see if one + of the objects can find the module to be imported. The + :meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at + least the absolute name of the module being imported. If the module to be + imported is contained in a package, then the parent package's :attr:`__path__` + attribute is passed in as a second argument. The method returns a + :term:`module spec`, or ``None`` if the module cannot be found. + + .. seealso:: + + :class:`importlib.abc.MetaPathFinder` + The abstract base class defining the interface of finder objects on + :data:`meta_path`. + :class:`importlib.machinery.ModuleSpec` + The concrete class which + :meth:`~importlib.abc.MetaPathFinder.find_spec` should return + instances of. + + .. versionchanged:: 3.4 + + :term:`Module specs ` were introduced in Python 3.4, by + :pep:`451`. Earlier versions of Python looked for a method called + :meth:`~importlib.abc.MetaPathFinder.find_module`. + This is still called as a fallback if a :data:`meta_path` entry doesn't + have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method. + +.. data:: modules + + This is a dictionary that maps module names to modules which have already been + loaded. This can be manipulated to force reloading of modules and other tricks. + However, replacing the dictionary will not necessarily work as expected and + deleting essential items from the dictionary may cause Python to fail. + + +.. data:: path + + .. index:: triple: module; search; path + + A list of strings that specifies the search path for modules. Initialized from + the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent + default. + + As initialized upon program startup, the first item of this list, ``path[0]``, + is the directory containing the script that was used to invoke the Python + interpreter. If the script directory is not available (e.g. if the interpreter + is invoked interactively or if the script is read from standard input), + ``path[0]`` is the empty string, which directs Python to search modules in the + current directory first. Notice that the script directory is inserted *before* + the entries inserted as a result of :envvar:`PYTHONPATH`. + + A program is free to modify this list for its own purposes. Only strings + and bytes should be added to :data:`sys.path`; all other data types are + ignored during import. + + + .. seealso:: + Module :mod:`site` This describes how to use .pth files to extend + :data:`sys.path`. + + +.. data:: path_hooks + + A list of callables that take a path argument to try to create a + :term:`finder` for the path. If a finder can be created, it is to be + returned by the callable, else raise :exc:`ImportError`. + + Originally specified in :pep:`302`. + + +.. data:: path_importer_cache + + A dictionary acting as a cache for :term:`finder` objects. The keys are + paths that have been passed to :data:`sys.path_hooks` and the values are + the finders that are found. If a path is a valid file system path but no + finder is found on :data:`sys.path_hooks` then ``None`` is + stored. + + Originally specified in :pep:`302`. + + .. versionchanged:: 3.3 + ``None`` is stored instead of :class:`imp.NullImporter` when no finder + is found. + + +.. data:: platform + + This string contains a platform identifier that can be used to append + platform-specific components to :data:`sys.path`, for instance. + + For Unix systems, except on Linux and AIX, this is the lowercased OS name as + returned by ``uname -s`` with the first part of the version as returned by + ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time + when Python was built*. Unless you want to test for a specific system + version, it is therefore recommended to use the following idiom:: + + if sys.platform.startswith('freebsd'): + # FreeBSD-specific code here... + elif sys.platform.startswith('linux'): + # Linux-specific code here... + elif sys.platform.startswith('aix'): + # AIX-specific code here... + + For other systems, the values are: + + ================ =========================== + System ``platform`` value + ================ =========================== + AIX ``'aix'`` + Linux ``'linux'`` + Windows ``'win32'`` + Windows/Cygwin ``'cygwin'`` + macOS ``'darwin'`` + ================ =========================== + + .. versionchanged:: 3.3 + On Linux, :attr:`sys.platform` doesn't contain the major version anymore. + It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since + older Python versions include the version number, it is recommended to + always use the ``startswith`` idiom presented above. + + .. versionchanged:: 3.8 + On AIX, :attr:`sys.platform` doesn't contain the major version anymore. + It is always ``'aix'``, instead of ``'aix5'`` or ``'aix7'``. Since + older Python versions include the version number, it is recommended to + always use the ``startswith`` idiom presented above. + + .. seealso:: + + :attr:`os.name` has a coarser granularity. :func:`os.uname` gives + system-dependent version information. + + The :mod:`platform` module provides detailed checks for the + system's identity. + + +.. data:: prefix + + A string giving the site-specific directory prefix where the platform + independent Python files are installed; by default, this is the string + ``'/usr/local'``. This can be set at build time with the ``--prefix`` + argument to the :program:`configure` script. The main collection of Python + library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}` + while the platform independent header files (all except :file:`pyconfig.h`) are + stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version + number of Python, for example ``3.2``. + + .. note:: If a :ref:`virtual environment ` is in effect, this + value will be changed in ``site.py`` to point to the virtual + environment. The value for the Python installation will still be + available, via :data:`base_prefix`. + + +.. data:: ps1 + ps2 + + .. index:: + single: interpreter prompts + single: prompts, interpreter + single: >>>; interpreter prompt + single: ...; interpreter prompt + + Strings specifying the primary and secondary prompt of the interpreter. These + are only defined if the interpreter is in interactive mode. Their initial + values in this case are ``'>>> '`` and ``'... '``. If a non-string object is + assigned to either variable, its :func:`str` is re-evaluated each time the + interpreter prepares to read a new interactive command; this can be used to + implement a dynamic prompt. + + +.. function:: setdlopenflags(n) + + Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when + the interpreter loads extension modules. Among other things, this will enable a + lazy resolving of symbols when importing a module, if called as + ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as + ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values + can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. + :data:`os.RTLD_LAZY`). + + .. availability:: Unix. + +.. function:: setprofile(profilefunc) + + .. index:: + single: profile function + single: profiler + + Set the system's profile function, which allows you to implement a Python source + code profiler in Python. See chapter :ref:`profile` for more information on the + Python profiler. The system's profile function is called similarly to the + system's trace function (see :func:`settrace`), but it is called with different events, + for example it isn't called for each executed line of code (only on call and return, + but the return event is reported even when an exception has been set). The function is + thread-specific, but there is no way for the profiler to know about context switches between + threads, so it does not make sense to use this in the presence of multiple threads. Also, + its return value is not used, so it can simply return ``None``. Error in the profile + function will cause itself unset. + + Profile functions should have three arguments: *frame*, *event*, and + *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, + ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends + on the event type. + + .. audit-event:: sys.setprofile "" sys.setprofile + + The events have the following meaning: + + ``'call'`` + A function is called (or some other code block entered). The + profile function is called; *arg* is ``None``. + + ``'return'`` + A function (or other code block) is about to return. The profile + function is called; *arg* is the value that will be returned, or ``None`` + if the event is caused by an exception being raised. + + ``'c_call'`` + A C function is about to be called. This may be an extension function or + a built-in. *arg* is the C function object. + + ``'c_return'`` + A C function has returned. *arg* is the C function object. + + ``'c_exception'`` + A C function has raised an exception. *arg* is the C function object. + +.. function:: setrecursionlimit(limit) + + Set the maximum depth of the Python interpreter stack to *limit*. This limit + prevents infinite recursion from causing an overflow of the C stack and crashing + Python. + + The highest possible limit is platform-dependent. A user may need to set the + limit higher when they have a program that requires deep recursion and a platform + that supports a higher limit. This should be done with care, because a too-high + limit can lead to a crash. + + If the new limit is too low at the current recursion depth, a + :exc:`RecursionError` exception is raised. + + .. versionchanged:: 3.5.1 + A :exc:`RecursionError` exception is now raised if the new limit is too + low at the current recursion depth. + + +.. function:: setswitchinterval(interval) + + Set the interpreter's thread switch interval (in seconds). This floating-point + value determines the ideal duration of the "timeslices" allocated to + concurrently running Python threads. Please note that the actual value + can be higher, especially if long-running internal functions or methods + are used. Also, which thread becomes scheduled at the end of the interval + is the operating system's decision. The interpreter doesn't have its + own scheduler. + + .. versionadded:: 3.2 + + +.. function:: settrace(tracefunc) + + .. index:: + single: trace function + single: debugger + + Set the system's trace function, which allows you to implement a Python + source code debugger in Python. The function is thread-specific; for a + debugger to support multiple threads, it must register a trace function using + :func:`settrace` for each thread being debugged or use :func:`threading.settrace`. + + Trace functions should have three arguments: *frame*, *event*, and + *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, + ``'line'``, ``'return'``, ``'exception'`` or ``'opcode'``. *arg* depends on + the event type. + + The trace function is invoked (with *event* set to ``'call'``) whenever a new + local scope is entered; it should return a reference to a local trace + function to be used for the new scope, or ``None`` if the scope shouldn't be + traced. + + The local trace function should return a reference to itself (or to another + function for further tracing in that scope), or ``None`` to turn off tracing + in that scope. + + If there is any error occurred in the trace function, it will be unset, just + like ``settrace(None)`` is called. + + The events have the following meaning: + + ``'call'`` + A function is called (or some other code block entered). The + global trace function is called; *arg* is ``None``; the return value + specifies the local trace function. + + ``'line'`` + The interpreter is about to execute a new line of code or re-execute the + condition of a loop. The local trace function is called; *arg* is + ``None``; the return value specifies the new local trace function. See + :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this + works. + Per-line events may be disabled for a frame by setting + :attr:`f_trace_lines` to :const:`False` on that frame. + + ``'return'`` + A function (or other code block) is about to return. The local trace + function is called; *arg* is the value that will be returned, or ``None`` + if the event is caused by an exception being raised. The trace function's + return value is ignored. + + ``'exception'`` + An exception has occurred. The local trace function is called; *arg* is a + tuple ``(exception, value, traceback)``; the return value specifies the + new local trace function. + + ``'opcode'`` + The interpreter is about to execute a new opcode (see :mod:`dis` for + opcode details). The local trace function is called; *arg* is + ``None``; the return value specifies the new local trace function. + Per-opcode events are not emitted by default: they must be explicitly + requested by setting :attr:`f_trace_opcodes` to :const:`True` on the + frame. + + Note that as an exception is propagated down the chain of callers, an + ``'exception'`` event is generated at each level. + + For more fine-grained usage, it's possible to set a trace function by + assigning ``frame.f_trace = tracefunc`` explicitly, rather than relying on + it being set indirectly via the return value from an already installed + trace function. This is also required for activating the trace function on + the current frame, which :func:`settrace` doesn't do. Note that in order + for this to work, a global tracing function must have been installed + with :func:`settrace` in order to enable the runtime tracing machinery, + but it doesn't need to be the same tracing function (e.g. it could be a + low overhead tracing function that simply returns ``None`` to disable + itself immediately on each frame). + + For more information on code and frame objects, refer to :ref:`types`. + + .. audit-event:: sys.settrace "" sys.settrace + + .. impl-detail:: + + The :func:`settrace` function is intended only for implementing debuggers, + profilers, coverage tools and the like. Its behavior is part of the + implementation platform, rather than part of the language definition, and + thus may not be available in all Python implementations. + + .. versionchanged:: 3.7 + + ``'opcode'`` event type added; :attr:`f_trace_lines` and + :attr:`f_trace_opcodes` attributes added to frames + +.. function:: set_asyncgen_hooks(firstiter, finalizer) + + Accepts two optional keyword arguments which are callables that accept an + :term:`asynchronous generator iterator` as an argument. The *firstiter* + callable will be called when an asynchronous generator is iterated for the + first time. The *finalizer* will be called when an asynchronous generator + is about to be garbage collected. + + .. audit-event:: sys.set_asyncgen_hooks_firstiter "" sys.set_asyncgen_hooks + + .. audit-event:: sys.set_asyncgen_hooks_finalizer "" sys.set_asyncgen_hooks + + Two auditing events are raised because the underlying API consists of two + calls, each of which must raise its own event. + + .. versionadded:: 3.6 + See :pep:`525` for more details, and for a reference example of a + *finalizer* method see the implementation of + ``asyncio.Loop.shutdown_asyncgens`` in + :source:`Lib/asyncio/base_events.py` + + .. note:: + This function has been added on a provisional basis (see :pep:`411` + for details.) + +.. function:: set_coroutine_origin_tracking_depth(depth) + + Allows enabling or disabling coroutine origin tracking. When + enabled, the ``cr_origin`` attribute on coroutine objects will + contain a tuple of (filename, line number, function name) tuples + describing the traceback where the coroutine object was created, + with the most recent call first. When disabled, ``cr_origin`` will + be None. + + To enable, pass a *depth* value greater than zero; this sets the + number of frames whose information will be captured. To disable, + pass set *depth* to zero. + + This setting is thread-specific. + + .. versionadded:: 3.7 + + .. note:: + This function has been added on a provisional basis (see :pep:`411` + for details.) Use it only for debugging purposes. + +.. function:: _enablelegacywindowsfsencoding() + + Changes the default filesystem encoding and errors mode to 'mbcs' and + 'replace' respectively, for consistency with versions of Python prior to 3.6. + + This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` + environment variable before launching Python. + + .. availability:: Windows. + + .. versionadded:: 3.6 + See :pep:`529` for more details. + +.. data:: stdin + stdout + stderr + + :term:`File objects ` used by the interpreter for standard + input, output and errors: + + * ``stdin`` is used for all interactive input (including calls to + :func:`input`); + * ``stdout`` is used for the output of :func:`print` and :term:`expression` + statements and for the prompts of :func:`input`; + * The interpreter's own prompts and its error messages go to ``stderr``. + + These streams are regular :term:`text files ` like those + returned by the :func:`open` function. Their parameters are chosen as + follows: + + * The character encoding is platform-dependent. Non-Windows + platforms use the locale encoding (see + :meth:`locale.getpreferredencoding()`). + + On Windows, UTF-8 is used for the console device. Non-character + devices such as disk files and pipes use the system locale + encoding (i.e. the ANSI codepage). Non-console character + devices such as NUL (i.e. where ``isatty()`` returns ``True``) use the + value of the console input and output codepages at startup, + respectively for stdin and stdout/stderr. This defaults to the + system locale encoding if the process is not initially attached + to a console. + + The special behaviour of the console can be overridden + by setting the environment variable PYTHONLEGACYWINDOWSSTDIO + before starting Python. In that case, the console codepages are + used as for any other character device. + + Under all platforms, you can override the character encoding by + setting the :envvar:`PYTHONIOENCODING` environment variable before + starting Python or by using the new :option:`-X` ``utf8`` command + line option and :envvar:`PYTHONUTF8` environment variable. However, + for the Windows console, this only applies when + :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also set. + + * When interactive, the ``stdout`` stream is line-buffered. Otherwise, + it is block-buffered like regular text files. The ``stderr`` stream + is line-buffered in both cases. You can make both streams unbuffered + by passing the :option:`-u` command-line option or setting the + :envvar:`PYTHONUNBUFFERED` environment variable. + + .. versionchanged:: 3.9 + Non-interactive ``stderr`` is now line-buffered instead of fully + buffered. + + .. note:: + + To write or read binary data from/to the standard streams, use the + underlying binary :data:`~io.TextIOBase.buffer` object. For example, to + write bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``. + + However, if you are writing a library (and do not control in which + context its code will be executed), be aware that the standard streams + may be replaced with file-like objects like :class:`io.StringIO` which + do not support the :attr:`~io.BufferedIOBase.buffer` attribute. + + +.. data:: __stdin__ + __stdout__ + __stderr__ + + These objects contain the original values of ``stdin``, ``stderr`` and + ``stdout`` at the start of the program. They are used during finalization, + and could be useful to print to the actual standard stream no matter if the + ``sys.std*`` object has been redirected. + + It can also be used to restore the actual files to known working file objects + in case they have been overwritten with a broken object. However, the + preferred way to do this is to explicitly save the previous stream before + replacing it, and restore the saved object. + + .. note:: + Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the + original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be + ``None``. It is usually the case for Windows GUI apps that aren't connected + to a console and Python apps started with :program:`pythonw`. + + +.. data:: thread_info + + A :term:`named tuple` holding information about the thread + implementation. + + .. tabularcolumns:: |l|p{0.7\linewidth}| + + +------------------+---------------------------------------------------------+ + | Attribute | Explanation | + +==================+=========================================================+ + | :const:`name` | Name of the thread implementation: | + | | | + | | * ``'nt'``: Windows threads | + | | * ``'pthread'``: POSIX threads | + | | * ``'solaris'``: Solaris threads | + +------------------+---------------------------------------------------------+ + | :const:`lock` | Name of the lock implementation: | + | | | + | | * ``'semaphore'``: a lock uses a semaphore | + | | * ``'mutex+cond'``: a lock uses a mutex | + | | and a condition variable | + | | * ``None`` if this information is unknown | + +------------------+---------------------------------------------------------+ + | :const:`version` | Name and version of the thread library. It is a string, | + | | or ``None`` if this information is unknown. | + +------------------+---------------------------------------------------------+ + + .. versionadded:: 3.3 + + +.. data:: tracebacklimit + + When this variable is set to an integer value, it determines the maximum number + of levels of traceback information printed when an unhandled exception occurs. + The default is ``1000``. When set to ``0`` or less, all traceback information + is suppressed and only the exception type and value are printed. + + +.. function:: unraisablehook(unraisable, /) + + Handle an unraisable exception. + + Called when an exception has occurred but there is no way for Python to + handle it. For example, when a destructor raises an exception or during + garbage collection (:func:`gc.collect`). + + The *unraisable* argument has the following attributes: + + * *exc_type*: Exception type. + * *exc_value*: Exception value, can be ``None``. + * *exc_traceback*: Exception traceback, can be ``None``. + * *err_msg*: Error message, can be ``None``. + * *object*: Object causing the exception, can be ``None``. + + The default hook formats *err_msg* and *object* as: + ``f'{err_msg}: {object!r}'``; use "Exception ignored in" error message + if *err_msg* is ``None``. + + :func:`sys.unraisablehook` can be overridden to control how unraisable + exceptions are handled. + + Storing *exc_value* using a custom hook can create a reference cycle. It + should be cleared explicitly to break the reference cycle when the + exception is no longer needed. + + Storing *object* using a custom hook can resurrect it if it is set to an + object which is being finalized. Avoid storing *object* after the custom + hook completes to avoid resurrecting objects. + + See also :func:`excepthook` which handles uncaught exceptions. + + .. audit-event:: sys.unraisablehook hook,unraisable sys.unraisablehook + + Raise an auditing event ``sys.unraisablehook`` with arguments + ``hook``, ``unraisable`` when an exception that cannot be handled occurs. + The ``unraisable`` object is the same as what will be passed to the hook. + If no hook has been set, ``hook`` may be ``None``. + + .. versionadded:: 3.8 + +.. data:: version + + A string containing the version number of the Python interpreter plus additional + information on the build number and compiler used. This string is displayed + when the interactive interpreter is started. Do not extract version information + out of it, rather, use :data:`version_info` and the functions provided by the + :mod:`platform` module. + + +.. data:: api_version + + The C API version for this interpreter. Programmers may find this useful when + debugging version conflicts between Python and extension modules. + + +.. data:: version_info + + A tuple containing the five components of the version number: *major*, *minor*, + *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are + integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or + ``'final'``. The ``version_info`` value corresponding to the Python version 2.0 + is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name, + so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major`` + and so on. + + .. versionchanged:: 3.1 + Added named component attributes. + +.. data:: warnoptions + + This is an implementation detail of the warnings framework; do not modify this + value. Refer to the :mod:`warnings` module for more information on the warnings + framework. + + +.. data:: winver + + The version number used to form registry keys on Windows platforms. This is + stored as string resource 1000 in the Python DLL. The value is normally the + first three characters of :const:`version`. It is provided in the :mod:`sys` + module for informational purposes; modifying this value has no effect on the + registry keys used by Python. + + .. availability:: Windows. + + +.. data:: _xoptions + + A dictionary of the various implementation-specific flags passed through + the :option:`-X` command-line option. Option names are either mapped to + their values, if given explicitly, or to :const:`True`. Example: + + .. code-block:: shell-session + + $ ./python -Xa=b -Xc + Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50) + [GCC 4.4.3] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + >>> import sys + >>> sys._xoptions + {'a': 'b', 'c': True} + + .. impl-detail:: + + This is a CPython-specific way of accessing options passed through + :option:`-X`. Other implementations may export them through other + means, or not at all. + + .. versionadded:: 3.2 + + +.. rubric:: Citations + +.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ . diff --git a/Doc/library/typing.rst.bak b/Doc/library/typing.rst.bak new file mode 100644 index 00000000000000..323dac20822010 --- /dev/null +++ b/Doc/library/typing.rst.bak @@ -0,0 +1,1374 @@ +:mod:`typing` --- Support for type hints +======================================== + +.. module:: typing + :synopsis: Support for type hints (see :pep:`484`). + +.. versionadded:: 3.5 + +**Source code:** :source:`Lib/typing.py` + +.. note:: + + The Python runtime does not enforce function and variable type annotations. + They can be used by third party tools such as type checkers, IDEs, linters, + etc. + +-------------- + +This module provides runtime support for type hints as specified by +:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, and :pep:`591`. +The most fundamental support consists of the types :data:`Any`, :data:`Union`, +:data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and +:class:`Generic`. For full specification please see :pep:`484`. For +a simplified introduction to type hints see :pep:`483`. + + +The function below takes and returns a string and is annotated as follows:: + + def greeting(name: str) -> str: + return 'Hello ' + name + +In the function ``greeting``, the argument ``name`` is expected to be of type +:class:`str` and the return type :class:`str`. Subtypes are accepted as +arguments. + +Type aliases +------------ + +A type alias is defined by assigning the type to the alias. In this example, +``Vector`` and ``List[float]`` will be treated as interchangeable synonyms:: + + from typing import List + Vector = List[float] + + def scale(scalar: float, vector: Vector) -> Vector: + return [scalar * num for num in vector] + + # typechecks; a list of floats qualifies as a Vector. + new_vector = scale(2.0, [1.0, -4.2, 5.4]) + +Type aliases are useful for simplifying complex type signatures. For example:: + + from typing import Dict, Tuple, Sequence + + ConnectionOptions = Dict[str, str] + Address = Tuple[str, int] + Server = Tuple[Address, ConnectionOptions] + + def broadcast_message(message: str, servers: Sequence[Server]) -> None: + ... + + # The static type checker will treat the previous type signature as + # being exactly equivalent to this one. + def broadcast_message( + message: str, + servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: + ... + +Note that ``None`` as a type hint is a special case and is replaced by +``type(None)``. + +.. _distinct: + +NewType +------- + +Use the :func:`NewType` helper function to create distinct types:: + + from typing import NewType + + UserId = NewType('UserId', int) + some_id = UserId(524313) + +The static type checker will treat the new type as if it were a subclass +of the original type. This is useful in helping catch logical errors:: + + def get_user_name(user_id: UserId) -> str: + ... + + # typechecks + user_a = get_user_name(UserId(42351)) + + # does not typecheck; an int is not a UserId + user_b = get_user_name(-1) + +You may still perform all ``int`` operations on a variable of type ``UserId``, +but the result will always be of type ``int``. This lets you pass in a +``UserId`` wherever an ``int`` might be expected, but will prevent you from +accidentally creating a ``UserId`` in an invalid way:: + + # 'output' is of type 'int', not 'UserId' + output = UserId(23413) + UserId(54341) + +Note that these checks are enforced only by the static type checker. At runtime, +the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a +function that immediately returns whatever parameter you pass it. That means +the expression ``Derived(some_value)`` does not create a new class or introduce +any overhead beyond that of a regular function call. + +More precisely, the expression ``some_value is Derived(some_value)`` is always +true at runtime. + +This also means that it is not possible to create a subtype of ``Derived`` +since it is an identity function at runtime, not an actual type:: + + from typing import NewType + + UserId = NewType('UserId', int) + + # Fails at runtime and does not typecheck + class AdminUserId(UserId): pass + +However, it is possible to create a :func:`NewType` based on a 'derived' ``NewType``:: + + from typing import NewType + + UserId = NewType('UserId', int) + + ProUserId = NewType('ProUserId', UserId) + +and typechecking for ``ProUserId`` will work as expected. + +See :pep:`484` for more details. + +.. note:: + + Recall that the use of a type alias declares two types to be *equivalent* to + one another. Doing ``Alias = Original`` will make the static type checker + treat ``Alias`` as being *exactly equivalent* to ``Original`` in all cases. + This is useful when you want to simplify complex type signatures. + + In contrast, ``NewType`` declares one type to be a *subtype* of another. + Doing ``Derived = NewType('Derived', Original)`` will make the static type + checker treat ``Derived`` as a *subclass* of ``Original``, which means a + value of type ``Original`` cannot be used in places where a value of type + ``Derived`` is expected. This is useful when you want to prevent logic + errors with minimal runtime cost. + +.. versionadded:: 3.5.2 + +Callable +-------- + +Frameworks expecting callback functions of specific signatures might be +type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``. + +For example:: + + from typing import Callable + + def feeder(get_next_item: Callable[[], str]) -> None: + # Body + + def async_query(on_success: Callable[[int], None], + on_error: Callable[[int, Exception], None]) -> None: + # Body + +It is possible to declare the return type of a callable without specifying +the call signature by substituting a literal ellipsis +for the list of arguments in the type hint: ``Callable[..., ReturnType]``. + +.. _generics: + +Generics +-------- + +Since type information about objects kept in containers cannot be statically +inferred in a generic way, abstract base classes have been extended to support +subscription to denote expected types for container elements. + +:: + + from typing import Mapping, Sequence + + def notify_by_email(employees: Sequence[Employee], + overrides: Mapping[str, str]) -> None: ... + +Generics can be parameterized by using a new factory available in typing +called :class:`TypeVar`. + +:: + + from typing import Sequence, TypeVar + + T = TypeVar('T') # Declare type variable + + def first(l: Sequence[T]) -> T: # Generic function + return l[0] + + +User-defined generic types +-------------------------- + +A user-defined class can be defined as a generic class. + +:: + + from typing import TypeVar, Generic + from logging import Logger + + T = TypeVar('T') + + class LoggedVar(Generic[T]): + def __init__(self, value: T, name: str, logger: Logger) -> None: + self.name = name + self.logger = logger + self.value = value + + def set(self, new: T) -> None: + self.log('Set ' + repr(self.value)) + self.value = new + + def get(self) -> T: + self.log('Get ' + repr(self.value)) + return self.value + + def log(self, message: str) -> None: + self.logger.info('%s: %s', self.name, message) + +``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a +single type parameter ``T`` . This also makes ``T`` valid as a type within the +class body. + +The :class:`Generic` base class defines :meth:`__class_getitem__` so that +``LoggedVar[t]`` is valid as a type:: + + from typing import Iterable + + def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None: + for var in vars: + var.set(0) + +A generic type can have any number of type variables, and type variables may +be constrained:: + + from typing import TypeVar, Generic + ... + + T = TypeVar('T') + S = TypeVar('S', int, str) + + class StrangePair(Generic[T, S]): + ... + +Each type variable argument to :class:`Generic` must be distinct. +This is thus invalid:: + + from typing import TypeVar, Generic + ... + + T = TypeVar('T') + + class Pair(Generic[T, T]): # INVALID + ... + +You can use multiple inheritance with :class:`Generic`:: + + from typing import TypeVar, Generic, Sized + + T = TypeVar('T') + + class LinkedList(Sized, Generic[T]): + ... + +When inheriting from generic classes, some type variables could be fixed:: + + from typing import TypeVar, Mapping + + T = TypeVar('T') + + class MyDict(Mapping[str, T]): + ... + +In this case ``MyDict`` has a single parameter, ``T``. + +Using a generic class without specifying type parameters assumes +:data:`Any` for each position. In the following example, ``MyIterable`` is +not generic but implicitly inherits from ``Iterable[Any]``:: + + from typing import Iterable + + class MyIterable(Iterable): # Same as Iterable[Any] + +User defined generic type aliases are also supported. Examples:: + + from typing import TypeVar, Iterable, Tuple, Union + S = TypeVar('S') + Response = Union[Iterable[S], int] + + # Return type here is same as Union[Iterable[str], int] + def response(query: str) -> Response[str]: + ... + + T = TypeVar('T', int, float, complex) + Vec = Iterable[Tuple[T, T]] + + def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]] + return sum(x*y for x, y in v) + +.. versionchanged:: 3.7 + :class:`Generic` no longer has a custom metaclass. + +A user-defined generic class can have ABCs as base classes without a metaclass +conflict. Generic metaclasses are not supported. The outcome of parameterizing +generics is cached, and most types in the typing module are hashable and +comparable for equality. + + +The :data:`Any` type +-------------------- + +A special kind of type is :data:`Any`. A static type checker will treat +every type as being compatible with :data:`Any` and :data:`Any` as being +compatible with every type. + +This means that it is possible to perform any operation or method call on a +value of type on :data:`Any` and assign it to any variable:: + + from typing import Any + + a = None # type: Any + a = [] # OK + a = 2 # OK + + s = '' # type: str + s = a # OK + + def foo(item: Any) -> int: + # Typechecks; 'item' could be any type, + # and that type might have a 'bar' method + item.bar() + ... + +Notice that no typechecking is performed when assigning a value of type +:data:`Any` to a more precise type. For example, the static type checker did +not report an error when assigning ``a`` to ``s`` even though ``s`` was +declared to be of type :class:`str` and receives an :class:`int` value at +runtime! + +Furthermore, all functions without a return type or parameter types will +implicitly default to using :data:`Any`:: + + def legacy_parser(text): + ... + return data + + # A static type checker will treat the above + # as having the same signature as: + def legacy_parser(text: Any) -> Any: + ... + return data + +This behavior allows :data:`Any` to be used as an *escape hatch* when you +need to mix dynamically and statically typed code. + +Contrast the behavior of :data:`Any` with the behavior of :class:`object`. +Similar to :data:`Any`, every type is a subtype of :class:`object`. However, +unlike :data:`Any`, the reverse is not true: :class:`object` is *not* a +subtype of every other type. + +That means when the type of a value is :class:`object`, a type checker will +reject almost all operations on it, and assigning it to a variable (or using +it as a return value) of a more specialized type is a type error. For example:: + + def hash_a(item: object) -> int: + # Fails; an object does not have a 'magic' method. + item.magic() + ... + + def hash_b(item: Any) -> int: + # Typechecks + item.magic() + ... + + # Typechecks, since ints and strs are subclasses of object + hash_a(42) + hash_a("foo") + + # Typechecks, since Any is compatible with all types + hash_b(42) + hash_b("foo") + +Use :class:`object` to indicate that a value could be any type in a typesafe +manner. Use :data:`Any` to indicate that a value is dynamically typed. + + +Nominal vs structural subtyping +------------------------------- + +Initially :pep:`484` defined Python static type system as using +*nominal subtyping*. This means that a class ``A`` is allowed where +a class ``B`` is expected if and only if ``A`` is a subclass of ``B``. + +This requirement previously also applied to abstract base classes, such as +:class:`Iterable`. The problem with this approach is that a class had +to be explicitly marked to support them, which is unpythonic and unlike +what one would normally do in idiomatic dynamically typed Python code. +For example, this conforms to the :pep:`484`:: + + from typing import Sized, Iterable, Iterator + + class Bucket(Sized, Iterable[int]): + ... + def __len__(self) -> int: ... + def __iter__(self) -> Iterator[int]: ... + +:pep:`544` allows to solve this problem by allowing users to write +the above code without explicit base classes in the class definition, +allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized`` +and ``Iterable[int]`` by static type checkers. This is known as +*structural subtyping* (or static duck-typing):: + + from typing import Iterator, Iterable + + class Bucket: # Note: no base classes + ... + def __len__(self) -> int: ... + def __iter__(self) -> Iterator[int]: ... + + def collect(items: Iterable[int]) -> int: ... + result = collect(Bucket()) # Passes type check + +Moreover, by subclassing a special class :class:`Protocol`, a user +can define new custom protocols to fully enjoy structural subtyping +(see examples below). + + +Classes, functions, and decorators +---------------------------------- + +The module defines the following classes, functions and decorators: + +.. class:: TypeVar + + Type variable. + + Usage:: + + T = TypeVar('T') # Can be anything + A = TypeVar('A', str, bytes) # Must be str or bytes + + Type variables exist primarily for the benefit of static type + checkers. They serve as the parameters for generic types as well + as for generic function definitions. See class Generic for more + information on generic types. Generic functions work as follows:: + + def repeat(x: T, n: int) -> Sequence[T]: + """Return a list containing n references to x.""" + return [x]*n + + def longest(x: A, y: A) -> A: + """Return the longest of two strings.""" + return x if len(x) >= len(y) else y + + The latter example's signature is essentially the overloading + of ``(str, str) -> str`` and ``(bytes, bytes) -> bytes``. Also note + that if the arguments are instances of some subclass of :class:`str`, + the return type is still plain :class:`str`. + + At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`. In general, + :func:`isinstance` and :func:`issubclass` should not be used with types. + + Type variables may be marked covariant or contravariant by passing + ``covariant=True`` or ``contravariant=True``. See :pep:`484` for more + details. By default type variables are invariant. Alternatively, + a type variable may specify an upper bound using ``bound=``. + This means that an actual type substituted (explicitly or implicitly) + for the type variable must be a subclass of the boundary type, + see :pep:`484`. + +.. class:: Generic + + Abstract base class for generic types. + + A generic type is typically declared by inheriting from an + instantiation of this class with one or more type variables. + For example, a generic mapping type might be defined as:: + + class Mapping(Generic[KT, VT]): + def __getitem__(self, key: KT) -> VT: + ... + # Etc. + + This class can then be used as follows:: + + X = TypeVar('X') + Y = TypeVar('Y') + + def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: + try: + return mapping[key] + except KeyError: + return default + +.. class:: Protocol(Generic) + + Base class for protocol classes. Protocol classes are defined like this:: + + class Proto(Protocol): + def meth(self) -> int: + ... + + Such classes are primarily used with static type checkers that recognize + structural subtyping (static duck-typing), for example:: + + class C: + def meth(self) -> int: + return 0 + + def func(x: Proto) -> int: + return x.meth() + + func(C()) # Passes static type check + + See :pep:`544` for details. Protocol classes decorated with + :func:`runtime_checkable` (described later) act as simple-minded runtime + protocols that check only the presence of given attributes, ignoring their + type signatures. + + Protocol classes can be generic, for example:: + + class GenProto(Protocol[T]): + def meth(self) -> T: + ... + + .. versionadded:: 3.8 + +.. class:: Type(Generic[CT_co]) + + A variable annotated with ``C`` may accept a value of type ``C``. In + contrast, a variable annotated with ``Type[C]`` may accept values that are + classes themselves -- specifically, it will accept the *class object* of + ``C``. For example:: + + a = 3 # Has type 'int' + b = int # Has type 'Type[int]' + c = type(a) # Also has type 'Type[int]' + + Note that ``Type[C]`` is covariant:: + + class User: ... + class BasicUser(User): ... + class ProUser(User): ... + class TeamUser(User): ... + + # Accepts User, BasicUser, ProUser, TeamUser, ... + def make_new_user(user_class: Type[User]) -> User: + # ... + return user_class() + + The fact that ``Type[C]`` is covariant implies that all subclasses of + ``C`` should implement the same constructor signature and class method + signatures as ``C``. The type checker should flag violations of this, + but should also allow constructor calls in subclasses that match the + constructor calls in the indicated base class. How the type checker is + required to handle this particular case may change in future revisions of + :pep:`484`. + + The only legal parameters for :class:`Type` are classes, :data:`Any`, + :ref:`type variables `, and unions of any of these types. + For example:: + + def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ... + + ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent + to ``type``, which is the root of Python's metaclass hierarchy. + + .. versionadded:: 3.5.2 + +.. class:: Iterable(Generic[T_co]) + + A generic version of :class:`collections.abc.Iterable`. + +.. class:: Iterator(Iterable[T_co]) + + A generic version of :class:`collections.abc.Iterator`. + +.. class:: Reversible(Iterable[T_co]) + + A generic version of :class:`collections.abc.Reversible`. + +.. class:: SupportsInt + + An ABC with one abstract method ``__int__``. + +.. class:: SupportsFloat + + An ABC with one abstract method ``__float__``. + +.. class:: SupportsComplex + + An ABC with one abstract method ``__complex__``. + +.. class:: SupportsBytes + + An ABC with one abstract method ``__bytes__``. + +.. class:: SupportsIndex + + An ABC with one abstract method ``__index__``. + + .. versionadded:: 3.8 + +.. class:: SupportsAbs + + An ABC with one abstract method ``__abs__`` that is covariant + in its return type. + +.. class:: SupportsRound + + An ABC with one abstract method ``__round__`` + that is covariant in its return type. + +.. class:: Container(Generic[T_co]) + + A generic version of :class:`collections.abc.Container`. + +.. class:: Hashable + + An alias to :class:`collections.abc.Hashable` + +.. class:: Sized + + An alias to :class:`collections.abc.Sized` + +.. class:: Collection(Sized, Iterable[T_co], Container[T_co]) + + A generic version of :class:`collections.abc.Collection` + + .. versionadded:: 3.6.0 + +.. class:: AbstractSet(Sized, Collection[T_co]) + + A generic version of :class:`collections.abc.Set`. + +.. class:: MutableSet(AbstractSet[T]) + + A generic version of :class:`collections.abc.MutableSet`. + +.. class:: Mapping(Sized, Collection[KT], Generic[VT_co]) + + A generic version of :class:`collections.abc.Mapping`. + This type can be used as follows:: + + def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: + return word_list[word] + +.. class:: MutableMapping(Mapping[KT, VT]) + + A generic version of :class:`collections.abc.MutableMapping`. + +.. class:: Sequence(Reversible[T_co], Collection[T_co]) + + A generic version of :class:`collections.abc.Sequence`. + +.. class:: MutableSequence(Sequence[T]) + + A generic version of :class:`collections.abc.MutableSequence`. + +.. class:: ByteString(Sequence[int]) + + A generic version of :class:`collections.abc.ByteString`. + + This type represents the types :class:`bytes`, :class:`bytearray`, + and :class:`memoryview`. + + As a shorthand for this type, :class:`bytes` can be used to + annotate arguments of any of the types mentioned above. + +.. class:: Deque(deque, MutableSequence[T]) + + A generic version of :class:`collections.deque`. + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.1 + +.. class:: List(list, MutableSequence[T]) + + Generic version of :class:`list`. + Useful for annotating return types. To annotate arguments it is preferred + to use an abstract collection type such as :class:`Sequence` or + :class:`Iterable`. + + This type may be used as follows:: + + T = TypeVar('T', int, float) + + def vec2(x: T, y: T) -> List[T]: + return [x, y] + + def keep_positives(vector: Sequence[T]) -> List[T]: + return [item for item in vector if item > 0] + +.. class:: Set(set, MutableSet[T]) + + A generic version of :class:`builtins.set `. + Useful for annotating return types. To annotate arguments it is preferred + to use an abstract collection type such as :class:`AbstractSet`. + +.. class:: FrozenSet(frozenset, AbstractSet[T_co]) + + A generic version of :class:`builtins.frozenset `. + +.. class:: MappingView(Sized, Iterable[T_co]) + + A generic version of :class:`collections.abc.MappingView`. + +.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co]) + + A generic version of :class:`collections.abc.KeysView`. + +.. class:: ItemsView(MappingView, Generic[KT_co, VT_co]) + + A generic version of :class:`collections.abc.ItemsView`. + +.. class:: ValuesView(MappingView[VT_co]) + + A generic version of :class:`collections.abc.ValuesView`. + +.. class:: Awaitable(Generic[T_co]) + + A generic version of :class:`collections.abc.Awaitable`. + + .. versionadded:: 3.5.2 + +.. class:: Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co]) + + A generic version of :class:`collections.abc.Coroutine`. + The variance and order of type variables + correspond to those of :class:`Generator`, for example:: + + from typing import List, Coroutine + c = None # type: Coroutine[List[str], str, int] + ... + x = c.send('hi') # type: List[str] + async def bar() -> None: + x = await c # type: int + + .. versionadded:: 3.5.3 + +.. class:: AsyncIterable(Generic[T_co]) + + A generic version of :class:`collections.abc.AsyncIterable`. + + .. versionadded:: 3.5.2 + +.. class:: AsyncIterator(AsyncIterable[T_co]) + + A generic version of :class:`collections.abc.AsyncIterator`. + + .. versionadded:: 3.5.2 + +.. class:: ContextManager(Generic[T_co]) + + A generic version of :class:`contextlib.AbstractContextManager`. + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.0 + +.. class:: AsyncContextManager(Generic[T_co]) + + A generic version of :class:`contextlib.AbstractAsyncContextManager`. + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.2 + +.. class:: Dict(dict, MutableMapping[KT, VT]) + + A generic version of :class:`dict`. + Useful for annotating return types. To annotate arguments it is preferred + to use an abstract collection type such as :class:`Mapping`. + + This type can be used as follows:: + + def count_words(text: str) -> Dict[str, int]: + ... + +.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT]) + + A generic version of :class:`collections.defaultdict`. + + .. versionadded:: 3.5.2 + +.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT]) + + A generic version of :class:`collections.OrderedDict`. + + .. versionadded:: 3.7.2 + +.. class:: Counter(collections.Counter, Dict[T, int]) + + A generic version of :class:`collections.Counter`. + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.1 + +.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT]) + + A generic version of :class:`collections.ChainMap`. + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.1 + +.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co]) + + A generator can be annotated by the generic type + ``Generator[YieldType, SendType, ReturnType]``. For example:: + + def echo_round() -> Generator[int, float, str]: + sent = yield 0 + while sent >= 0: + sent = yield round(sent) + return 'Done' + + Note that unlike many other generics in the typing module, the ``SendType`` + of :class:`Generator` behaves contravariantly, not covariantly or + invariantly. + + If your generator will only yield values, set the ``SendType`` and + ``ReturnType`` to ``None``:: + + def infinite_stream(start: int) -> Generator[int, None, None]: + while True: + yield start + start += 1 + + Alternatively, annotate your generator as having a return type of + either ``Iterable[YieldType]`` or ``Iterator[YieldType]``:: + + def infinite_stream(start: int) -> Iterator[int]: + while True: + yield start + start += 1 + +.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra]) + + An async generator can be annotated by the generic type + ``AsyncGenerator[YieldType, SendType]``. For example:: + + async def echo_round() -> AsyncGenerator[int, float]: + sent = yield 0 + while sent >= 0.0: + rounded = await round(sent) + sent = yield rounded + + Unlike normal generators, async generators cannot return a value, so there + is no ``ReturnType`` type parameter. As with :class:`Generator`, the + ``SendType`` behaves contravariantly. + + If your generator will only yield values, set the ``SendType`` to + ``None``:: + + async def infinite_stream(start: int) -> AsyncGenerator[int, None]: + while True: + yield start + start = await increment(start) + + Alternatively, annotate your generator as having a return type of + either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``:: + + async def infinite_stream(start: int) -> AsyncIterator[int]: + while True: + yield start + start = await increment(start) + + .. versionadded:: 3.6.1 + +.. class:: Text + + ``Text`` is an alias for ``str``. It is provided to supply a forward + compatible path for Python 2 code: in Python 2, ``Text`` is an alias for + ``unicode``. + + Use ``Text`` to indicate that a value must contain a unicode string in + a manner that is compatible with both Python 2 and Python 3:: + + def add_unicode_checkmark(text: Text) -> Text: + return text + u' \u2713' + + .. versionadded:: 3.5.2 + +.. class:: IO + TextIO + BinaryIO + + Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])`` + and ``BinaryIO(IO[bytes])`` + represent the types of I/O streams such as returned by + :func:`open`. + +.. class:: Pattern + Match + + These type aliases + correspond to the return types from :func:`re.compile` and + :func:`re.match`. These types (and the corresponding functions) + are generic in ``AnyStr`` and can be made specific by writing + ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or + ``Match[bytes]``. + +.. class:: NamedTuple + + Typed version of :func:`collections.namedtuple`. + + Usage:: + + class Employee(NamedTuple): + name: str + id: int + + This is equivalent to:: + + Employee = collections.namedtuple('Employee', ['name', 'id']) + + To give a field a default value, you can assign to it in the class body:: + + class Employee(NamedTuple): + name: str + id: int = 3 + + employee = Employee('Guido') + assert employee.id == 3 + + Fields with a default value must come after any fields without a default. + + The resulting class has an extra attribute ``__annotations__`` giving a + dict that maps the field names to the field types. (The field names are in + the ``_fields`` attribute and the default values are in the + ``_field_defaults`` attribute both of which are part of the namedtuple + API.) + + ``NamedTuple`` subclasses can also have docstrings and methods:: + + class Employee(NamedTuple): + """Represents an employee.""" + name: str + id: int = 3 + + def __repr__(self) -> str: + return f'' + + Backward-compatible usage:: + + Employee = NamedTuple('Employee', [('name', str), ('id', int)]) + + .. versionchanged:: 3.6 + Added support for :pep:`526` variable annotation syntax. + + .. versionchanged:: 3.6.1 + Added support for default values, methods, and docstrings. + + .. versionchanged:: 3.8 + Deprecated the ``_field_types`` attribute in favor of the more + standard ``__annotations__`` attribute which has the same information. + + .. versionchanged:: 3.8 + The ``_field_types`` and ``__annotations__`` attributes are + now regular dictionaries instead of instances of ``OrderedDict``. + +.. class:: TypedDict(dict) + + A simple typed namespace. At runtime it is equivalent to + a plain :class:`dict`. + + ``TypedDict`` creates a dictionary type that expects all of its + instances to have a certain set of keys, where each key is + associated with a value of a consistent type. This expectation + is not checked at runtime but is only enforced by type checkers. + Usage:: + + class Point2D(TypedDict): + x: int + y: int + label: str + + a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK + b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check + + assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') + + The type info for introspection can be accessed via ``Point2D.__annotations__`` + and ``Point2D.__total__``. To allow using this feature with older versions + of Python that do not support :pep:`526`, ``TypedDict`` supports two additional + equivalent syntactic forms:: + + Point2D = TypedDict('Point2D', x=int, y=int, label=str) + Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) + + See :pep:`589` for more examples and detailed rules of using ``TypedDict`` + with type checkers. + + .. versionadded:: 3.8 + +.. class:: ForwardRef + + A class used for internal typing representation of string forward references. + For example, ``List["SomeClass"]`` is implicitly transformed into + ``List[ForwardRef("SomeClass")]``. This class should not be instantiated by + a user, but may be used by introspection tools. + +.. function:: NewType(typ) + + A helper function to indicate a distinct types to a typechecker, + see :ref:`distinct`. At runtime it returns a function that returns + its argument. Usage:: + + UserId = NewType('UserId', int) + first_user = UserId(1) + + .. versionadded:: 3.5.2 + +.. function:: cast(typ, val) + + Cast a value to a type. + + This returns the value unchanged. To the type checker this + signals that the return value has the designated type, but at + runtime we intentionally don't check anything (we want this + to be as fast as possible). + +.. function:: get_type_hints(obj[, globals[, locals]]) + + Return a dictionary containing type hints for a function, method, module + or class object. + + This is often the same as ``obj.__annotations__``. In addition, + forward references encoded as string literals are handled by evaluating + them in ``globals`` and ``locals`` namespaces. If necessary, + ``Optional[t]`` is added for function and method annotations if a default + value equal to ``None`` is set. For a class ``C``, return + a dictionary constructed by merging all the ``__annotations__`` along + ``C.__mro__`` in reverse order. + +.. function:: get_origin(tp) +.. function:: get_args(tp) + + Provide basic introspection for generic types and special typing forms. + + For a typing object of the form ``X[Y, Z, ...]`` these functions return + ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or + :mod:`collections` class, it gets normalized to the original class. + For unsupported objects return ``None`` and ``()`` correspondingly. + Examples:: + + assert get_origin(Dict[str, int]) is dict + assert get_args(Dict[int, str]) == (int, str) + + assert get_origin(Union[int, str]) is Union + assert get_args(Union[int, str]) == (int, str) + + .. versionadded:: 3.8 + +.. decorator:: overload + + The ``@overload`` decorator allows describing functions and methods + that support multiple different combinations of argument types. A series + of ``@overload``-decorated definitions must be followed by exactly one + non-``@overload``-decorated definition (for the same function/method). + The ``@overload``-decorated definitions are for the benefit of the + type checker only, since they will be overwritten by the + non-``@overload``-decorated definition, while the latter is used at + runtime but should be ignored by a type checker. At runtime, calling + a ``@overload``-decorated function directly will raise + :exc:`NotImplementedError`. An example of overload that gives a more + precise type than can be expressed using a union or a type variable:: + + @overload + def process(response: None) -> None: + ... + @overload + def process(response: int) -> Tuple[int, str]: + ... + @overload + def process(response: bytes) -> str: + ... + def process(response): + + + See :pep:`484` for details and comparison with other typing semantics. + +.. decorator:: final + + A decorator to indicate to type checkers that the decorated method + cannot be overridden, and the decorated class cannot be subclassed. + For example:: + + class Base: + @final + def done(self) -> None: + ... + class Sub(Base): + def done(self) -> None: # Error reported by type checker + ... + + @final + class Leaf: + ... + class Other(Leaf): # Error reported by type checker + ... + + There is no runtime checking of these properties. See :pep:`591` for + more details. + + .. versionadded:: 3.8 + +.. decorator:: no_type_check + + Decorator to indicate that annotations are not type hints. + + This works as class or function :term:`decorator`. With a class, it + applies recursively to all methods defined in that class (but not + to methods defined in its superclasses or subclasses). + + This mutates the function(s) in place. + +.. decorator:: no_type_check_decorator + + Decorator to give another decorator the :func:`no_type_check` effect. + + This wraps the decorator with something that wraps the decorated + function in :func:`no_type_check`. + +.. decorator:: type_check_only + + Decorator to mark a class or function to be unavailable at runtime. + + This decorator is itself not available at runtime. It is mainly + intended to mark classes that are defined in type stub files if + an implementation returns an instance of a private class:: + + @type_check_only + class Response: # private or not available at runtime + code: int + def get_header(self, name: str) -> str: ... + + def fetch_response() -> Response: ... + + Note that returning instances of private classes is not recommended. + It is usually preferable to make such classes public. + +.. decorator:: runtime_checkable + + Mark a protocol class as a runtime protocol. + + Such a protocol can be used with :func:`isinstance` and :func:`issubclass`. + This raises :exc:`TypeError` when applied to a non-protocol class. This + allows a simple-minded structural check, very similar to "one trick ponies" + in :mod:`collections.abc` such as :class:`Iterable`. For example:: + + @runtime_checkable + class Closable(Protocol): + def close(self): ... + + assert isinstance(open('/some/file'), Closable) + + **Warning:** this will check only the presence of the required methods, + not their type signatures! + + .. versionadded:: 3.8 + +.. data:: Any + + Special type indicating an unconstrained type. + + * Every type is compatible with :data:`Any`. + * :data:`Any` is compatible with every type. + +.. data:: NoReturn + + Special type indicating that a function never returns. + For example:: + + from typing import NoReturn + + def stop() -> NoReturn: + raise RuntimeError('no way') + + .. versionadded:: 3.5.4 + .. versionadded:: 3.6.2 + +.. data:: Union + + Union type; ``Union[X, Y]`` means either X or Y. + + To define a union, use e.g. ``Union[int, str]``. Details: + + * The arguments must be types and there must be at least one. + + * Unions of unions are flattened, e.g.:: + + Union[Union[int, str], float] == Union[int, str, float] + + * Unions of a single argument vanish, e.g.:: + + Union[int] == int # The constructor actually returns int + + * Redundant arguments are skipped, e.g.:: + + Union[int, str, int] == Union[int, str] + + * When comparing unions, the argument order is ignored, e.g.:: + + Union[int, str] == Union[str, int] + + * You cannot subclass or instantiate a union. + + * You cannot write ``Union[X][Y]``. + + * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``. + + .. versionchanged:: 3.7 + Don't remove explicit subclasses from unions at runtime. + +.. data:: Optional + + Optional type. + + ``Optional[X]`` is equivalent to ``Union[X, None]``. + + Note that this is not the same concept as an optional argument, + which is one that has a default. An optional argument with a + default does not require the ``Optional`` qualifier on its type + annotation just because it is optional. For example:: + + def foo(arg: int = 0) -> None: + ... + + On the other hand, if an explicit value of ``None`` is allowed, the + use of ``Optional`` is appropriate, whether the argument is optional + or not. For example:: + + def foo(arg: Optional[int] = None) -> None: + ... + +.. data:: Tuple + + Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items + with the first item of type X and the second of type Y. The type of + the empty tuple can be written as ``Tuple[()]``. + + Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding + to type variables T1 and T2. ``Tuple[int, float, str]`` is a tuple + of an int, a float and a string. + + To specify a variable-length tuple of homogeneous type, + use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple` + is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`. + +.. data:: Callable + + Callable type; ``Callable[[int], str]`` is a function of (int) -> str. + + The subscription syntax must always be used with exactly two + values: the argument list and the return type. The argument list + must be a list of types or an ellipsis; the return type must be + a single type. + + There is no syntax to indicate optional or keyword arguments; + such function types are rarely used as callback types. + ``Callable[..., ReturnType]`` (literal ellipsis) can be used to + type hint a callable taking any number of arguments and returning + ``ReturnType``. A plain :data:`Callable` is equivalent to + ``Callable[..., Any]``, and in turn to + :class:`collections.abc.Callable`. + +.. data:: Literal + + A type that can be used to indicate to type checkers that the + corresponding variable or function parameter has a value equivalent to + the provided literal (or one of several literals). For example:: + + def validate_simple(data: Any) -> Literal[True]: # always returns True + ... + + MODE = Literal['r', 'rb', 'w', 'wb'] + def open_helper(file: str, mode: MODE) -> str: + ... + + open_helper('/some/path', 'r') # Passes type check + open_helper('/other/path', 'typo') # Error in type checker + + ``Literal[...]`` cannot be subclassed. At runtime, an arbitrary value + is allowed as type argument to ``Literal[...]``, but type checkers may + impose restrictions. See :pep:`586` for more details about literal types. + + .. versionadded:: 3.8 + +.. data:: ClassVar + + Special type construct to mark class variables. + + As introduced in :pep:`526`, a variable annotation wrapped in ClassVar + indicates that a given attribute is intended to be used as a class variable + and should not be set on instances of that class. Usage:: + + class Starship: + stats: ClassVar[Dict[str, int]] = {} # class variable + damage: int = 10 # instance variable + + :data:`ClassVar` accepts only types and cannot be further subscribed. + + :data:`ClassVar` is not a class itself, and should not + be used with :func:`isinstance` or :func:`issubclass`. + :data:`ClassVar` does not change Python runtime behavior, but + it can be used by third-party type checkers. For example, a type checker + might flag the following code as an error:: + + enterprise_d = Starship(3000) + enterprise_d.stats = {} # Error, setting class variable on instance + Starship.stats = {} # This is OK + + .. versionadded:: 3.5.3 + +.. data:: Final + + A special typing construct to indicate to type checkers that a name + cannot be re-assigned or overridden in a subclass. For example:: + + MAX_SIZE: Final = 9000 + MAX_SIZE += 1 # Error reported by type checker + + class Connection: + TIMEOUT: Final[int] = 10 + + class FastConnector(Connection): + TIMEOUT = 1 # Error reported by type checker + + There is no runtime checking of these properties. See :pep:`591` for + more details. + + .. versionadded:: 3.8 + +.. data:: AnyStr + + ``AnyStr`` is a type variable defined as + ``AnyStr = TypeVar('AnyStr', str, bytes)``. + + It is meant to be used for functions that may accept any kind of string + without allowing different kinds of strings to mix. For example:: + + def concat(a: AnyStr, b: AnyStr) -> AnyStr: + return a + b + + concat(u"foo", u"bar") # Ok, output has type 'unicode' + concat(b"foo", b"bar") # Ok, output has type 'bytes' + concat(u"foo", b"bar") # Error, cannot mix unicode and bytes + +.. data:: TYPE_CHECKING + + A special constant that is assumed to be ``True`` by 3rd party static + type checkers. It is ``False`` at runtime. Usage:: + + if TYPE_CHECKING: + import expensive_mod + + def fun(arg: 'expensive_mod.SomeType') -> None: + local_var: expensive_mod.AnotherType = other_fun() + + Note that the first type annotation must be enclosed in quotes, making it a + "forward reference", to hide the ``expensive_mod`` reference from the + interpreter runtime. Type annotations for local variables are not + evaluated, so the second annotation does not need to be enclosed in quotes. + + .. versionadded:: 3.5.2 diff --git a/Doc/tutorial/errors.rst.bak b/Doc/tutorial/errors.rst.bak new file mode 100644 index 00000000000000..8f86eca02483a2 --- /dev/null +++ b/Doc/tutorial/errors.rst.bak @@ -0,0 +1,474 @@ +.. _tut-errors: + +********************* +Errors and Exceptions +********************* + +Until now error messages haven't been more than mentioned, but if you have tried +out the examples you have probably seen some. There are (at least) two +distinguishable kinds of errors: *syntax errors* and *exceptions*. + + +.. _tut-syntaxerrors: + +Syntax Errors +============= + +Syntax errors, also known as parsing errors, are perhaps the most common kind of +complaint you get while you are still learning Python:: + + >>> while True print('Hello world') + File "", line 1 + while True print('Hello world') + ^ + SyntaxError: invalid syntax + +The parser repeats the offending line and displays a little 'arrow' pointing at +the earliest point in the line where the error was detected. The error is +caused by (or at least detected at) the token *preceding* the arrow: in the +example, the error is detected at the function :func:`print`, since a colon +(``':'``) is missing before it. File name and line number are printed so you +know where to look in case the input came from a script. + + +.. _tut-exceptions: + +Exceptions +========== + +Even if a statement or expression is syntactically correct, it may cause an +error when an attempt is made to execute it. Errors detected during execution +are called *exceptions* and are not unconditionally fatal: you will soon learn +how to handle them in Python programs. Most exceptions are not handled by +programs, however, and result in error messages as shown here:: + + >>> 10 * (1/0) + Traceback (most recent call last): + File "", line 1, in + ZeroDivisionError: division by zero + >>> 4 + spam*3 + Traceback (most recent call last): + File "", line 1, in + NameError: name 'spam' is not defined + >>> '2' + 2 + Traceback (most recent call last): + File "", line 1, in + TypeError: Can't convert 'int' object to str implicitly + +The last line of the error message indicates what happened. Exceptions come in +different types, and the type is printed as part of the message: the types in +the example are :exc:`ZeroDivisionError`, :exc:`NameError` and :exc:`TypeError`. +The string printed as the exception type is the name of the built-in exception +that occurred. This is true for all built-in exceptions, but need not be true +for user-defined exceptions (although it is a useful convention). Standard +exception names are built-in identifiers (not reserved keywords). + +The rest of the line provides detail based on the type of exception and what +caused it. + +The preceding part of the error message shows the context where the exception +happened, in the form of a stack traceback. In general it contains a stack +traceback listing source lines; however, it will not display lines read from +standard input. + +:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. + + +.. _tut-handling: + +Handling Exceptions +=================== + +It is possible to write programs that handle selected exceptions. Look at the +following example, which asks the user for input until a valid integer has been +entered, but allows the user to interrupt the program (using :kbd:`Control-C` or +whatever the operating system supports); note that a user-generated interruption +is signalled by raising the :exc:`KeyboardInterrupt` exception. :: + + >>> while True: + ... try: + ... x = int(input("Please enter a number: ")) + ... break + ... except ValueError: + ... print("Oops! That was no valid number. Try again...") + ... + +The :keyword:`try` statement works as follows. + +* First, the *try clause* (the statement(s) between the :keyword:`try` and + :keyword:`except` keywords) is executed. + +* If no exception occurs, the *except clause* is skipped and execution of the + :keyword:`try` statement is finished. + +* If an exception occurs during execution of the try clause, the rest of the + clause is skipped. Then if its type matches the exception named after the + :keyword:`except` keyword, the except clause is executed, and then execution + continues after the :keyword:`try` statement. + +* If an exception occurs which does not match the exception named in the except + clause, it is passed on to outer :keyword:`try` statements; if no handler is + found, it is an *unhandled exception* and execution stops with a message as + shown above. + +A :keyword:`try` statement may have more than one except clause, to specify +handlers for different exceptions. At most one handler will be executed. +Handlers only handle exceptions that occur in the corresponding try clause, not +in other handlers of the same :keyword:`!try` statement. An except clause may +name multiple exceptions as a parenthesized tuple, for example:: + + ... except (RuntimeError, TypeError, NameError): + ... pass + +A class in an :keyword:`except` clause is compatible with an exception if it is +the same class or a base class thereof (but not the other way around --- an +except clause listing a derived class is not compatible with a base class). For +example, the following code will print B, C, D in that order:: + + class B(Exception): + pass + + class C(B): + pass + + class D(C): + pass + + for cls in [B, C, D]: + try: + raise cls() + except D: + print("D") + except C: + print("C") + except B: + print("B") + +Note that if the except clauses were reversed (with ``except B`` first), it +would have printed B, B, B --- the first matching except clause is triggered. + +The last except clause may omit the exception name(s), to serve as a wildcard. +Use this with extreme caution, since it is easy to mask a real programming error +in this way! It can also be used to print an error message and then re-raise +the exception (allowing a caller to handle the exception as well):: + + import sys + + try: + f = open('myfile.txt') + s = f.readline() + i = int(s.strip()) + except OSError as err: + print("OS error: {0}".format(err)) + except ValueError: + print("Could not convert data to an integer.") + except: + print("Unexpected error:", sys.exc_info()[0]) + raise + +The :keyword:`try` ... :keyword:`except` statement has an optional *else +clause*, which, when present, must follow all except clauses. It is useful for +code that must be executed if the try clause does not raise an exception. For +example:: + + for arg in sys.argv[1:]: + try: + f = open(arg, 'r') + except OSError: + print('cannot open', arg) + else: + print(arg, 'has', len(f.readlines()), 'lines') + f.close() + +The use of the :keyword:`!else` clause is better than adding additional code to +the :keyword:`try` clause because it avoids accidentally catching an exception +that wasn't raised by the code being protected by the :keyword:`!try` ... +:keyword:`!except` statement. + +When an exception occurs, it may have an associated value, also known as the +exception's *argument*. The presence and type of the argument depend on the +exception type. + +The except clause may specify a variable after the exception name. The +variable is bound to an exception instance with the arguments stored in +``instance.args``. For convenience, the exception instance defines +:meth:`__str__` so the arguments can be printed directly without having to +reference ``.args``. One may also instantiate an exception first before +raising it and add any attributes to it as desired. :: + + >>> try: + ... raise Exception('spam', 'eggs') + ... except Exception as inst: + ... print(type(inst)) # the exception instance + ... print(inst.args) # arguments stored in .args + ... print(inst) # __str__ allows args to be printed directly, + ... # but may be overridden in exception subclasses + ... x, y = inst.args # unpack args + ... print('x =', x) + ... print('y =', y) + ... + + ('spam', 'eggs') + ('spam', 'eggs') + x = spam + y = eggs + +If an exception has arguments, they are printed as the last part ('detail') of +the message for unhandled exceptions. + +Exception handlers don't just handle exceptions if they occur immediately in the +try clause, but also if they occur inside functions that are called (even +indirectly) in the try clause. For example:: + + >>> def this_fails(): + ... x = 1/0 + ... + >>> try: + ... this_fails() + ... except ZeroDivisionError as err: + ... print('Handling run-time error:', err) + ... + Handling run-time error: division by zero + + +.. _tut-raising: + +Raising Exceptions +================== + +The :keyword:`raise` statement allows the programmer to force a specified +exception to occur. For example:: + + >>> raise NameError('HiThere') + Traceback (most recent call last): + File "", line 1, in + NameError: HiThere + +The sole argument to :keyword:`raise` indicates the exception to be raised. +This must be either an exception instance or an exception class (a class that +derives from :class:`Exception`). If an exception class is passed, it will +be implicitly instantiated by calling its constructor with no arguments:: + + raise ValueError # shorthand for 'raise ValueError()' + +If you need to determine whether an exception was raised but don't intend to +handle it, a simpler form of the :keyword:`raise` statement allows you to +re-raise the exception:: + + >>> try: + ... raise NameError('HiThere') + ... except NameError: + ... print('An exception flew by!') + ... raise + ... + An exception flew by! + Traceback (most recent call last): + File "", line 2, in + NameError: HiThere + + +.. _tut-exception-chaining: + +Exception Chaining +================== + +The :keyword:`raise` statement allows an optional :keyword:`from` which enables +chaining exceptions by setting the ``__cause__`` attribute of the raised +exception. For example:: + + raise RuntimeError from OSError + +This can be useful when you are transforming exceptions. For example:: + + >>> def func(): + ... raise IOError + ... + >>> try: + ... func() + ... except IOError as exc: + ... raise RuntimeError('Failed to open database') from exc + ... + Traceback (most recent call last): + File "", line 2, in + File "", line 2, in func + OSError + + The above exception was the direct cause of the following exception: + + Traceback (most recent call last): + File "", line 4, in + RuntimeError + +The expression following the :keyword:`from` must be either an exception or +``None``. Exception chaining happens automatically when an exception is raised +inside an exception handler or :keyword:`finally` section. Exception chaining +can be disabled by using ``from None`` idiom: + + >>> try: + ... open('database.sqlite') + ... except IOError: + ... raise RuntimeError from None + ... + Traceback (most recent call last): + File "", line 4, in + RuntimeError + + +.. _tut-userexceptions: + +User-defined Exceptions +======================= + +Programs may name their own exceptions by creating a new exception class (see +:ref:`tut-classes` for more about Python classes). Exceptions should typically +be derived from the :exc:`Exception` class, either directly or indirectly. + +Exception classes can be defined which do anything any other class can do, but +are usually kept simple, often only offering a number of attributes that allow +information about the error to be extracted by handlers for the exception. When +creating a module that can raise several distinct errors, a common practice is +to create a base class for exceptions defined by that module, and subclass that +to create specific exception classes for different error conditions:: + + class Error(Exception): + """Base class for exceptions in this module.""" + pass + + class InputError(Error): + """Exception raised for errors in the input. + + Attributes: + expression -- input expression in which the error occurred + message -- explanation of the error + """ + + def __init__(self, expression, message): + self.expression = expression + self.message = message + + class TransitionError(Error): + """Raised when an operation attempts a state transition that's not + allowed. + + Attributes: + previous -- state at beginning of transition + next -- attempted new state + message -- explanation of why the specific transition is not allowed + """ + + def __init__(self, previous, next, message): + self.previous = previous + self.next = next + self.message = message + +Most exceptions are defined with names that end in "Error", similar to the +naming of the standard exceptions. + +Many standard modules define their own exceptions to report errors that may +occur in functions they define. More information on classes is presented in +chapter :ref:`tut-classes`. + + +.. _tut-cleanup: + +Defining Clean-up Actions +========================= + +The :keyword:`try` statement has another optional clause which is intended to +define clean-up actions that must be executed under all circumstances. For +example:: + + >>> try: + ... raise KeyboardInterrupt + ... finally: + ... print('Goodbye, world!') + ... + Goodbye, world! + Traceback (most recent call last): + File "", line 2, in + KeyboardInterrupt + +If a :keyword:`finally` clause is present, the :keyword:`finally` clause will execute as the last task before the :keyword:`try` statement completes. The :keyword:`finally` clause runs whether or not the :keyword:`try` statement produces an exception. The following points discuss more complex cases when an exception occurs: + +* If an exception occurs during execution of the :keyword:`!try` clause, the exception may be handled by an :keyword:`except` clause. If the exception is not handled by an :keyword:`except` clause, the exception is re-raised after the :keyword:`!finally` clause has been executed. + +* An exception could occur during execution of an :keyword:`!except` or :keyword:`!else` clause. Again, the exception is re-raised after the :keyword:`!finally` clause has been executed. + +* If the :keyword:`!try` statement reaches a :keyword:`break`, :keyword:`continue` or :keyword:`return` statement, the :keyword:`finally` clause will execute just prior to the :keyword:`break`, :keyword:`continue` or :keyword:`return` statement's execution. + +* If a :keyword:`finally` clause includes a :keyword:`return` statement, the :keyword:`finally` clause's :keyword:`return` statement will execute before, and instead of, the :keyword:`return` statement in a :keyword:`try` clause. + +For example:: + + >>> def bool_return(): + ... try: + ... return True + ... finally: + ... return False + ... + >>> bool_return() + False + +A more complicated example:: + + >>> def divide(x, y): + ... try: + ... result = x / y + ... except ZeroDivisionError: + ... print("division by zero!") + ... else: + ... print("result is", result) + ... finally: + ... print("executing finally clause") + ... + >>> divide(2, 1) + result is 2.0 + executing finally clause + >>> divide(2, 0) + division by zero! + executing finally clause + >>> divide("2", "1") + executing finally clause + Traceback (most recent call last): + File "", line 1, in + File "", line 3, in divide + TypeError: unsupported operand type(s) for /: 'str' and 'str' + +As you can see, the :keyword:`finally` clause is executed in any event. The +:exc:`TypeError` raised by dividing two strings is not handled by the +:keyword:`except` clause and therefore re-raised after the :keyword:`!finally` +clause has been executed. + +In real world applications, the :keyword:`finally` clause is useful for +releasing external resources (such as files or network connections), regardless +of whether the use of the resource was successful. + + +.. _tut-cleanup-with: + +Predefined Clean-up Actions +=========================== + +Some objects define standard clean-up actions to be undertaken when the object +is no longer needed, regardless of whether or not the operation using the object +succeeded or failed. Look at the following example, which tries to open a file +and print its contents to the screen. :: + + for line in open("myfile.txt"): + print(line, end="") + +The problem with this code is that it leaves the file open for an indeterminate +amount of time after this part of the code has finished executing. +This is not an issue in simple scripts, but can be a problem for larger +applications. The :keyword:`with` statement allows objects like files to be +used in a way that ensures they are always cleaned up promptly and correctly. :: + + with open("myfile.txt") as f: + for line in f: + print(line, end="") + +After the statement is executed, the file *f* is always closed, even if a +problem was encountered while processing the lines. Objects which, like files, +provide predefined clean-up actions will indicate this in their documentation. + + diff --git a/Doc/whatsnew/3.8.rst.bak b/Doc/whatsnew/3.8.rst.bak new file mode 100644 index 00000000000000..fabc1c597eca70 --- /dev/null +++ b/Doc/whatsnew/3.8.rst.bak @@ -0,0 +1,2216 @@ +**************************** + What's New In Python 3.8 +**************************** + +.. Rules for maintenance: + + * Anyone can add text to this document. Do not spend very much time + on the wording of your changes, because your text will probably + get rewritten to some degree. + + * The maintainer will go through Misc/NEWS periodically and add + changes; it's therefore more important to add your changes to + Misc/NEWS than to this file. + + * This is not a complete list of every single change; completeness + is the purpose of Misc/NEWS. Some changes I consider too small + or esoteric to include. If such a change is added to the text, + I'll just remove it. (This is another reason you shouldn't spend + too much time on writing your addition.) + + * If you want to draw your new text to the attention of the + maintainer, add 'XXX' to the beginning of the paragraph or + section. + + * It's OK to just add a fragmentary note about a change. For + example: "XXX Describe the transmogrify() function added to the + socket module." The maintainer will research the change and + write the necessary text. + + * You can comment out your additions if you like, but it's not + necessary (especially when a final release is some months away). + + * Credit the author of a patch or bugfix. Just the name is + sufficient; the e-mail address isn't necessary. + + * It's helpful to add the bug/patch number as a comment: + + XXX Describe the transmogrify() function added to the socket + module. + (Contributed by P.Y. Developer in :issue:`12345`.) + + This saves the maintainer the effort of going through the Git log + when researching a change. + +:Editor: Raymond Hettinger + +This article explains the new features in Python 3.8, compared to 3.7. +For full details, see the :ref:`changelog `. + +.. testsetup:: + + from datetime import date + from math import cos, radians + from unicodedata import normalize + import re + import math + + +Summary -- Release highlights +============================= + +.. This section singles out the most important changes in Python 3.8. + Brevity is key. + + +.. PEP-sized items next. + + + +New Features +============ + +Assignment expressions +---------------------- + +There is new syntax ``:=`` that assigns values to variables as part of a larger +expression. It is affectionately known as "the walrus operator" due to +its resemblance to `the eyes and tusks of a walrus +`_. + +In this example, the assignment expression helps avoid calling +:func:`len` twice:: + + if (n := len(a)) > 10: + print(f"List is too long ({n} elements, expected <= 10)") + +A similar benefit arises during regular expression matching where +match objects are needed twice, once to test whether a match +occurred and another to extract a subgroup:: + + discount = 0.0 + if (mo := re.search(r'(\d+)% discount', advertisement)): + discount = float(mo.group(1)) / 100.0 + +The operator is also useful with while-loops that compute +a value to test loop termination and then need that same +value again in the body of the loop:: + + # Loop over fixed length blocks + while (block := f.read(256)) != '': + process(block) + +Another motivating use case arises in list comprehensions where +a value computed in a filtering condition is also needed in +the expression body:: + + [clean_name.title() for name in names + if (clean_name := normalize('NFC', name)) in allowed_names] + +Try to limit use of the walrus operator to clean cases that reduce +complexity and improve readability. + +See :pep:`572` for a full description. + +(Contributed by Emily Morehouse in :issue:`35224`.) + + +Positional-only parameters +-------------------------- + +There is a new function parameter syntax ``/`` to indicate that some +function parameters must be specified positionally and cannot be used as +keyword arguments. This is the same notation shown by ``help()`` for C +functions annotated with Larry Hastings' `Argument Clinic +`_ tool. + +In the following example, parameters *a* and *b* are positional-only, +while *c* or *d* can be positional or keyword, and *e* or *f* are +required to be keywords:: + + def f(a, b, /, c, d, *, e, f): + print(a, b, c, d, e, f) + +The following is a valid call:: + + f(10, 20, 30, d=40, e=50, f=60) + +However, these are invalid calls:: + + f(10, b=20, c=30, d=40, e=50, f=60) # b cannot be a keyword argument + f(10, 20, 30, 40, 50, f=60) # e must be a keyword argument + +One use case for this notation is that it allows pure Python functions +to fully emulate behaviors of existing C coded functions. For example, +the built-in :func:`pow` function does not accept keyword arguments:: + + def pow(x, y, z=None, /): + "Emulate the built in pow() function" + r = x ** y + return r if z is None else r%z + +Another use case is to preclude keyword arguments when the parameter +name is not helpful. For example, the builtin :func:`len` function has +the signature ``len(obj, /)``. This precludes awkward calls such as:: + + len(obj='hello') # The "obj" keyword argument impairs readability + +A further benefit of marking a parameter as positional-only is that it +allows the parameter name to be changed in the future without risk of +breaking client code. For example, in the :mod:`statistics` module, the +parameter name *dist* may be changed in the future. This was made +possible with the following function specification:: + + def quantiles(dist, /, *, n=4, method='exclusive') + ... + +Since the parameters to the left of ``/`` are not exposed as possible +keywords, the parameters names remain available for use in ``**kwargs``:: + + >>> def f(a, b, /, **kwargs): + ... print(a, b, kwargs) + ... + >>> f(10, 20, a=1, b=2, c=3) # a and b are used in two ways + 10 20 {'a': 1, 'b': 2, 'c': 3} + +This greatly simplifies the implementation of functions and methods +that need to accept arbitrary keyword arguments. For example, here +is an excerpt from code in the :mod:`collections` module:: + + class Counter(dict): + + def __init__(self, iterable=None, /, **kwds): + # Note "iterable" is a possible keyword argument + +See :pep:`570` for a full description. + +(Contributed by Pablo Galindo in :issue:`36540`.) + +.. TODO: Pablo will sprint on docs at PyCon US 2019. + + +Parallel filesystem cache for compiled bytecode files +----------------------------------------------------- + +The new :envvar:`PYTHONPYCACHEPREFIX` setting (also available as +:option:`-X` ``pycache_prefix``) configures the implicit bytecode +cache to use a separate parallel filesystem tree, rather than +the default ``__pycache__`` subdirectories within each source +directory. + +The location of the cache is reported in :data:`sys.pycache_prefix` +(:const:`None` indicates the default location in ``__pycache__`` +subdirectories). + +(Contributed by Carl Meyer in :issue:`33499`.) + + +Debug build uses the same ABI as release build +----------------------------------------------- + +Python now uses the same ABI whether it's built in release or debug mode. On +Unix, when Python is built in debug mode, it is now possible to load C +extensions built in release mode and C extensions built using the stable ABI. + +Release builds and debug builds are now ABI compatible: defining the +``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which +introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which +adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS` +environment variable, can be set using the new ``./configure --with-trace-refs`` +build option. +(Contributed by Victor Stinner in :issue:`36465`.) + +On Unix, C extensions are no longer linked to libpython except on Android +and Cygwin. +It is now possible +for a statically linked Python to load a C extension built using a shared +library Python. +(Contributed by Victor Stinner in :issue:`21536`.) + +On Unix, when Python is built in debug mode, import now also looks for C +extensions compiled in release mode and for C extensions compiled with the +stable ABI. +(Contributed by Victor Stinner in :issue:`36722`.) + +To embed Python into an application, a new ``--embed`` option must be passed to +``python3-config --libs --embed`` to get ``-lpython3.8`` (link the application +to libpython). To support both 3.8 and older, try ``python3-config --libs +--embed`` first and fallback to ``python3-config --libs`` (without ``--embed``) +if the previous command fails. + +Add a pkg-config ``python-3.8-embed`` module to embed Python into an +application: ``pkg-config python-3.8-embed --libs`` includes ``-lpython3.8``. +To support both 3.8 and older, try ``pkg-config python-X.Y-embed --libs`` first +and fallback to ``pkg-config python-X.Y --libs`` (without ``--embed``) if the +previous command fails (replace ``X.Y`` with the Python version). + +On the other hand, ``pkg-config python3.8 --libs`` no longer contains +``-lpython3.8``. C extensions must not be linked to libpython (except on +Android and Cygwin, whose cases are handled by the script); +this change is backward incompatible on purpose. +(Contributed by Victor Stinner in :issue:`36721`.) + + +f-strings support ``=`` for self-documenting expressions and debugging +---------------------------------------------------------------------- + +Added an ``=`` specifier to :term:`f-string`\s. An f-string such as +``f'{expr=}'`` will expand to the text of the expression, an equal sign, +then the representation of the evaluated expression. For example: + + >>> user = 'eric_idle' + >>> member_since = date(1975, 7, 31) + >>> f'{user=} {member_since=}' + "user='eric_idle' member_since=datetime.date(1975, 7, 31)" + +The usual :ref:`f-string format specifiers ` allow more +control over how the result of the expression is displayed:: + + >>> delta = date.today() - member_since + >>> f'{user=!s} {delta.days=:,d}' + 'user=eric_idle delta.days=16,075' + +The ``=`` specifier will display the whole expression so that +calculations can be shown:: + + >>> print(f'{theta=} {cos(radians(theta))=:.3f}') + theta=30 cos(radians(theta))=0.866 + +(Contributed by Eric V. Smith and Larry Hastings in :issue:`36817`.) + + +PEP 578: Python Runtime Audit Hooks +----------------------------------- + +The PEP adds an Audit Hook and Verified Open Hook. Both are available from +Python and native code, allowing applications and frameworks written in pure +Python code to take advantage of extra notifications, while also allowing +embedders or system administrators to deploy builds of Python where auditing is +always enabled. + +See :pep:`578` for full details. + + +PEP 587: Python Initialization Configuration +-------------------------------------------- + +The :pep:`587` adds a new C API to configure the Python Initialization +providing finer control on the whole configuration and better error reporting. + +New structures: + +* :c:type:`PyConfig` +* :c:type:`PyPreConfig` +* :c:type:`PyStatus` +* :c:type:`PyWideStringList` + +New functions: + +* :c:func:`PyConfig_Clear` +* :c:func:`PyConfig_InitIsolatedConfig` +* :c:func:`PyConfig_InitPythonConfig` +* :c:func:`PyConfig_Read` +* :c:func:`PyConfig_SetArgv` +* :c:func:`PyConfig_SetBytesArgv` +* :c:func:`PyConfig_SetBytesString` +* :c:func:`PyConfig_SetString` +* :c:func:`PyPreConfig_InitIsolatedConfig` +* :c:func:`PyPreConfig_InitPythonConfig` +* :c:func:`PyStatus_Error` +* :c:func:`PyStatus_Exception` +* :c:func:`PyStatus_Exit` +* :c:func:`PyStatus_IsError` +* :c:func:`PyStatus_IsExit` +* :c:func:`PyStatus_NoMemory` +* :c:func:`PyStatus_Ok` +* :c:func:`PyWideStringList_Append` +* :c:func:`PyWideStringList_Insert` +* :c:func:`Py_BytesMain` +* :c:func:`Py_ExitStatusException` +* :c:func:`Py_InitializeFromConfig` +* :c:func:`Py_PreInitialize` +* :c:func:`Py_PreInitializeFromArgs` +* :c:func:`Py_PreInitializeFromBytesArgs` +* :c:func:`Py_RunMain` + +This PEP also adds ``_PyRuntimeState.preconfig`` (:c:type:`PyPreConfig` type) +and ``PyInterpreterState.config`` (:c:type:`PyConfig` type) fields to these +internal structures. ``PyInterpreterState.config`` becomes the new +reference configuration, replacing global configuration variables and +other private variables. + +See :ref:`Python Initialization Configuration ` for the +documentation. + +See :pep:`587` for a full description. + +(Contributed by Victor Stinner in :issue:`36763`.) + + +PEP 590: Vectorcall: a fast calling protocol for CPython +-------------------------------------------------------- + +:ref:`vectorcall` is added to the Python/C API. +It is meant to formalize existing optimizations which were already done +for various classes. +Any static type implementing a callable can use this protocol. + +This is currently provisional. +The aim is to make it fully public in Python 3.9. + +See :pep:`590` for a full description. + +(Contributed by Jeroen Demeyer, Mark Shannon and Petr Viktorin in :issue:`36974`.) + + +Pickle protocol 5 with out-of-band data buffers +----------------------------------------------- + +When :mod:`pickle` is used to transfer large data between Python processes +in order to take advantage of multi-core or multi-machine processing, +it is important to optimize the transfer by reducing memory copies, and +possibly by applying custom techniques such as data-dependent compression. + +The :mod:`pickle` protocol 5 introduces support for out-of-band buffers +where :pep:`3118`-compatible data can be transmitted separately from the +main pickle stream, at the discretion of the communication layer. + +See :pep:`574` for a full description. + +(Contributed by Antoine Pitrou in :issue:`36785`.) + + +Other Language Changes +====================== + +* A :keyword:`continue` statement was illegal in the :keyword:`finally` clause + due to a problem with the implementation. In Python 3.8 this restriction + was lifted. + (Contributed by Serhiy Storchaka in :issue:`32489`.) + +* The :class:`bool`, :class:`int`, and :class:`fractions.Fraction` types + now have an :meth:`~int.as_integer_ratio` method like that found in + :class:`float` and :class:`decimal.Decimal`. This minor API extension + makes it possible to write ``numerator, denominator = + x.as_integer_ratio()`` and have it work across multiple numeric types. + (Contributed by Lisa Roach in :issue:`33073` and Raymond Hettinger in + :issue:`37819`.) + +* Constructors of :class:`int`, :class:`float` and :class:`complex` will now + use the :meth:`~object.__index__` special method, if available and the + corresponding method :meth:`~object.__int__`, :meth:`~object.__float__` + or :meth:`~object.__complex__` is not available. + (Contributed by Serhiy Storchaka in :issue:`20092`.) + +* Added support of ``\N{name}`` escapes in :mod:`regular expressions `:: + + >>> notice = 'Copyright © 2019' + >>> copyright_year_pattern = re.compile(r'\N{copyright sign}\s*(\d{4})') + >>> int(copyright_year_pattern.search(notice).group(1)) + 2019 + + (Contributed by Jonathan Eunice and Serhiy Storchaka in :issue:`30688`.) + +* Dict and dictviews are now iterable in reversed insertion order using + :func:`reversed`. (Contributed by Rémi Lapeyre in :issue:`33462`.) + +* The syntax allowed for keyword names in function calls was further + restricted. In particular, ``f((keyword)=arg)`` is no longer allowed. It was + never intended to permit more than a bare name on the left-hand side of a + keyword argument assignment term. + (Contributed by Benjamin Peterson in :issue:`34641`.) + +* Generalized iterable unpacking in :keyword:`yield` and + :keyword:`return` statements no longer requires enclosing parentheses. + This brings the *yield* and *return* syntax into better agreement with + normal assignment syntax:: + + >>> def parse(family): + lastname, *members = family.split() + return lastname.upper(), *members + + >>> parse('simpsons homer marge bart lisa sally') + ('SIMPSONS', 'homer', 'marge', 'bart', 'lisa', 'sally') + + (Contributed by David Cuthbert and Jordan Chapman in :issue:`32117`.) + +* When a comma is missed in code such as ``[(10, 20) (30, 40)]``, the + compiler displays a :exc:`SyntaxWarning` with a helpful suggestion. + This improves on just having a :exc:`TypeError` indicating that the + first tuple was not callable. (Contributed by Serhiy Storchaka in + :issue:`15248`.) + +* Arithmetic operations between subclasses of :class:`datetime.date` or + :class:`datetime.datetime` and :class:`datetime.timedelta` objects now return + an instance of the subclass, rather than the base class. This also affects + the return type of operations whose implementation (directly or indirectly) + uses :class:`datetime.timedelta` arithmetic, such as + :meth:`~datetime.datetime.astimezone`. + (Contributed by Paul Ganssle in :issue:`32417`.) + +* When the Python interpreter is interrupted by Ctrl-C (SIGINT) and the + resulting :exc:`KeyboardInterrupt` exception is not caught, the Python process + now exits via a SIGINT signal or with the correct exit code such that the + calling process can detect that it died due to a Ctrl-C. Shells on POSIX + and Windows use this to properly terminate scripts in interactive sessions. + (Contributed by Google via Gregory P. Smith in :issue:`1054041`.) + +* Some advanced styles of programming require updating the + :class:`types.CodeType` object for an existing function. Since code + objects are immutable, a new code object needs to be created, one + that is modeled on the existing code object. With 19 parameters, + this was somewhat tedious. Now, the new ``replace()`` method makes + it possible to create a clone with a few altered parameters. + + Here's an example that alters the :func:`statistics.mean` function to + prevent the *data* parameter from being used as a keyword argument:: + + >>> from statistics import mean + >>> mean(data=[10, 20, 90]) + 40 + >>> mean.__code__ = mean.__code__.replace(co_posonlyargcount=1) + >>> mean(data=[10, 20, 90]) + Traceback (most recent call last): + ... + TypeError: mean() got some positional-only arguments passed as keyword arguments: 'data' + + (Contributed by Victor Stinner in :issue:`37032`.) + +* For integers, the three-argument form of the :func:`pow` function now + permits the exponent to be negative in the case where the base is + relatively prime to the modulus. It then computes a modular inverse to + the base when the exponent is ``-1``, and a suitable power of that + inverse for other negative exponents. For example, to compute the + `modular multiplicative inverse + `_ of 38 + modulo 137, write:: + + >>> pow(38, -1, 137) + 119 + >>> 119 * 38 % 137 + 1 + + Modular inverses arise in the solution of `linear Diophantine + equations `_. + For example, to find integer solutions for ``4258𝑥 + 147𝑦 = 369``, + first rewrite as ``4258𝑥 ≡ 369 (mod 147)`` then solve: + + >>> x = 369 * pow(4258, -1, 147) % 147 + >>> y = (4258 * x - 369) // -147 + >>> 4258 * x + 147 * y + 369 + + (Contributed by Mark Dickinson in :issue:`36027`.) + +* Dict comprehensions have been synced-up with dict literals so that the + key is computed first and the value second:: + + >>> # Dict comprehension + >>> cast = {input('role? '): input('actor? ') for i in range(2)} + role? King Arthur + actor? Chapman + role? Black Knight + actor? Cleese + + >>> # Dict literal + >>> cast = {input('role? '): input('actor? ')} + role? Sir Robin + actor? Eric Idle + + The guaranteed execution order is helpful with assignment expressions + because variables assigned in the key expression will be available in + the value expression:: + + >>> names = ['Martin von Löwis', 'Łukasz Langa', 'Walter Dörwald'] + >>> {(n := normalize('NFC', name)).casefold() : n for name in names} + {'martin von löwis': 'Martin von Löwis', + 'łukasz langa': 'Łukasz Langa', + 'walter dörwald': 'Walter Dörwald'} + + (Contributed by Jörn Heissler in :issue:`35224`.) + +* The :meth:`object.__reduce__` method can now return a tuple from two to + six elements long. Formerly, five was the limit. The new, optional sixth + element is a callable with a ``(obj, state)`` signature. This allows the + direct control over the state-updating behavior of a specific object. If + not *None*, this callable will have priority over the object's + :meth:`~__setstate__` method. + (Contributed by Pierre Glaser and Olivier Grisel in :issue:`35900`.) + +New Modules +=========== + +* The new :mod:`importlib.metadata` module provides (provisional) support for + reading metadata from third-party packages. For example, it can extract an + installed package's version number, list of entry points, and more:: + + >>> # Note following example requires that the popular "requests" + >>> # package has been installed. + >>> + >>> from importlib.metadata import version, requires, files + >>> version('requests') + '2.22.0' + >>> list(requires('requests')) + ['chardet (<3.1.0,>=3.0.2)'] + >>> list(files('requests'))[:5] + [PackagePath('requests-2.22.0.dist-info/INSTALLER'), + PackagePath('requests-2.22.0.dist-info/LICENSE'), + PackagePath('requests-2.22.0.dist-info/METADATA'), + PackagePath('requests-2.22.0.dist-info/RECORD'), + PackagePath('requests-2.22.0.dist-info/WHEEL')] + + (Contributed by Barry Warsaw and Jason R. Coombs in :issue:`34632`.) + + +Improved Modules +================ + +ast +--- + +AST nodes now have ``end_lineno`` and ``end_col_offset`` attributes, +which give the precise location of the end of the node. (This only +applies to nodes that have ``lineno`` and ``col_offset`` attributes.) + +New function :func:`ast.get_source_segment` returns the source code +for a specific AST node. + +(Contributed by Ivan Levkivskyi in :issue:`33416`.) + +The :func:`ast.parse` function has some new flags: + +* ``type_comments=True`` causes it to return the text of :pep:`484` and + :pep:`526` type comments associated with certain AST nodes; + +* ``mode='func_type'`` can be used to parse :pep:`484` "signature type + comments" (returned for function definition AST nodes); + +* ``feature_version=(3, N)`` allows specifying an earlier Python 3 + version. For example, ``feature_version=(3, 4)`` will treat + :keyword:`async` and :keyword:`await` as non-reserved words. + +(Contributed by Guido van Rossum in :issue:`35766`.) + + +asyncio +------- + +:func:`asyncio.run` has graduated from the provisional to stable API. This +function can be used to execute a :term:`coroutine` and return the result while +automatically managing the event loop. For example:: + + import asyncio + + async def main(): + await asyncio.sleep(0) + return 42 + + asyncio.run(main()) + +This is *roughly* equivalent to:: + + import asyncio + + async def main(): + await asyncio.sleep(0) + return 42 + + loop = asyncio.new_event_loop() + asyncio.set_event_loop(loop) + try: + loop.run_until_complete(main()) + finally: + asyncio.set_event_loop(None) + loop.close() + + +The actual implementation is significantly more complex. Thus, +:func:`asyncio.run` should be the preferred way of running asyncio programs. + +(Contributed by Yury Selivanov in :issue:`32314`.) + +Running ``python -m asyncio`` launches a natively async REPL. This allows rapid +experimentation with code that has a top-level :keyword:`await`. There is no +longer a need to directly call ``asyncio.run()`` which would spawn a new event +loop on every invocation: + +.. code-block:: none + + $ python -m asyncio + asyncio REPL 3.8.0 + Use "await" directly instead of "asyncio.run()". + Type "help", "copyright", "credits" or "license" for more information. + >>> import asyncio + >>> await asyncio.sleep(10, result='hello') + hello + +(Contributed by Yury Selivanov in :issue:`37028`.) + +The exception :class:`asyncio.CancelledError` now inherits from +:class:`BaseException` rather than :class:`Exception`. +(Contributed by Yury Selivanov in :issue:`32528`.) + +On Windows, the default event loop is now :class:`~asyncio.ProactorEventLoop`. +(Contributed by Victor Stinner in :issue:`34687`.) + +:class:`~asyncio.ProactorEventLoop` now also supports UDP. +(Contributed by Adam Meily and Andrew Svetlov in :issue:`29883`.) + +:class:`~asyncio.ProactorEventLoop` can now be interrupted by +:exc:`KeyboardInterrupt` ("CTRL+C"). +(Contributed by Vladimir Matveev in :issue:`23057`.) + +Added :meth:`asyncio.Task.get_coro` for getting the wrapped coroutine +within an :class:`asyncio.Task`. +(Contributed by Alex Grönholm in :issue:`36999`.) + +Asyncio tasks can now be named, either by passing the ``name`` keyword +argument to :func:`asyncio.create_task` or +the :meth:`~asyncio.loop.create_task` event loop method, or by +calling the :meth:`~asyncio.Task.set_name` method on the task object. The +task name is visible in the ``repr()`` output of :class:`asyncio.Task` and +can also be retrieved using the :meth:`~asyncio.Task.get_name` method. +(Contributed by Alex Grönholm in :issue:`34270`.) + +Added support for +`Happy Eyeballs `_ to +:func:`asyncio.loop.create_connection`. To specify the behavior, two new +parameters have been added: *happy_eyeballs_delay* and *interleave*. The Happy +Eyeballs algorithm improves responsiveness in applications that support IPv4 +and IPv6 by attempting to simultaneously connect using both. +(Contributed by twisteroid ambassador in :issue:`33530`.) + + +builtins +-------- + +The :func:`compile` built-in has been improved to accept the +``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` flag. With this new flag passed, +:func:`compile` will allow top-level ``await``, ``async for`` and ``async with`` +constructs that are usually considered invalid syntax. Asynchronous code object +marked with the ``CO_COROUTINE`` flag may then be returned. +(Contributed by Matthias Bussonnier in :issue:`34616`) + + +collections +----------- + +The :meth:`~collections.somenamedtuple._asdict` method for +:func:`collections.namedtuple` now returns a :class:`dict` instead of a +:class:`collections.OrderedDict`. This works because regular dicts have +guaranteed ordering since Python 3.7. If the extra features of +:class:`OrderedDict` are required, the suggested remediation is to cast the +result to the desired type: ``OrderedDict(nt._asdict())``. +(Contributed by Raymond Hettinger in :issue:`35864`.) + + +cProfile +-------- + +The :class:`cProfile.Profile ` class can now be used as a context manager. +Profile a block of code by running:: + + import cProfile + + with cProfile.Profile() as profiler: + # code to be profiled + ... + +(Contributed by Scott Sanderson in :issue:`29235`.) + + +csv +--- + +The :class:`csv.DictReader` now returns instances of :class:`dict` instead of +a :class:`collections.OrderedDict`. The tool is now faster and uses less +memory while still preserving the field order. +(Contributed by Michael Selik in :issue:`34003`.) + + +curses +------- + +Added a new variable holding structured version information for the +underlying ncurses library: :data:`~curses.ncurses_version`. +(Contributed by Serhiy Storchaka in :issue:`31680`.) + + +ctypes +------ + +On Windows, :class:`~ctypes.CDLL` and subclasses now accept a *winmode* parameter +to specify flags for the underlying ``LoadLibraryEx`` call. The default flags are +set to only load DLL dependencies from trusted locations, including the path +where the DLL is stored (if a full or partial path is used to load the initial +DLL) and paths added by :func:`~os.add_dll_directory`. +(Contributed by Steve Dower in :issue:`36085`.) + + +datetime +-------- + +Added new alternate constructors :meth:`datetime.date.fromisocalendar` and +:meth:`datetime.datetime.fromisocalendar`, which construct :class:`date` and +:class:`datetime` objects respectively from ISO year, week number, and weekday; +these are the inverse of each class's ``isocalendar`` method. +(Contributed by Paul Ganssle in :issue:`36004`.) + + +functools +--------- + +:func:`functools.lru_cache` can now be used as a straight decorator rather +than as a function returning a decorator. So both of these are now supported:: + + @lru_cache + def f(x): + ... + + @lru_cache(maxsize=256) + def f(x): + ... + +(Contributed by Raymond Hettinger in :issue:`36772`.) + +Added a new :func:`functools.cached_property` decorator, for computed properties +cached for the life of the instance. :: + + import functools + import statistics + + class Dataset: + def __init__(self, sequence_of_numbers): + self.data = sequence_of_numbers + + @functools.cached_property + def variance(self): + return statistics.variance(self.data) + +(Contributed by Carl Meyer in :issue:`21145`) + + +Added a new :func:`functools.singledispatchmethod` decorator that converts +methods into :term:`generic functions ` using +:term:`single dispatch`:: + + from functools import singledispatchmethod + from contextlib import suppress + + class TaskManager: + + def __init__(self, tasks): + self.tasks = list(tasks) + + @singledispatchmethod + def discard(self, value): + with suppress(ValueError): + self.tasks.remove(value) + + @discard.register(list) + def _(self, tasks): + targets = set(tasks) + self.tasks = [x for x in self.tasks if x not in targets] + +(Contributed by Ethan Smith in :issue:`32380`) + +gc +-- + +:func:`~gc.get_objects` can now receive an optional *generation* parameter +indicating a generation to get objects from. +(Contributed by Pablo Galindo in :issue:`36016`.) + + +gettext +------- + +Added :func:`~gettext.pgettext` and its variants. +(Contributed by Franz Glasner, Éric Araujo, and Cheryl Sabella in :issue:`2504`.) + + +gzip +---- + +Added the *mtime* parameter to :func:`gzip.compress` for reproducible output. +(Contributed by Guo Ci Teo in :issue:`34898`.) + +A :exc:`~gzip.BadGzipFile` exception is now raised instead of :exc:`OSError` +for certain types of invalid or corrupt gzip files. +(Contributed by Filip Gruszczyński, Michele Orrù, and Zackery Spytz in +:issue:`6584`.) + + +IDLE and idlelib +---------------- + +Output over N lines (50 by default) is squeezed down to a button. +N can be changed in the PyShell section of the General page of the +Settings dialog. Fewer, but possibly extra long, lines can be squeezed by +right clicking on the output. Squeezed output can be expanded in place +by double-clicking the button or into the clipboard or a separate window +by right-clicking the button. (Contributed by Tal Einat in :issue:`1529353`.) + +Add "Run Customized" to the Run menu to run a module with customized +settings. Any command line arguments entered are added to sys.argv. +They also re-appear in the box for the next customized run. One can also +suppress the normal Shell main module restart. (Contributed by Cheryl +Sabella, Terry Jan Reedy, and others in :issue:`5680` and :issue:`37627`.) + +Added optional line numbers for IDLE editor windows. Windows +open without line numbers unless set otherwise in the General +tab of the configuration dialog. Line numbers for an existing +window are shown and hidden in the Options menu. +(Contributed by Tal Einat and Saimadhav Heblikar in :issue:`17535`.) + +OS native encoding is now used for converting between Python strings and Tcl +objects. This allows IDLE to work with emoji and other non-BMP characters. +These characters can be displayed or copied and pasted to or from the +clipboard. Converting strings from Tcl to Python and back now never fails. +(Many people worked on this for eight years but the problem was finally +solved by Serhiy Storchaka in :issue:`13153`.) + +The changes above have been backported to 3.7 maintenance releases. + + +inspect +------- + +The :func:`inspect.getdoc` function can now find docstrings for ``__slots__`` +if that attribute is a :class:`dict` where the values are docstrings. +This provides documentation options similar to what we already have +for :func:`property`, :func:`classmethod`, and :func:`staticmethod`:: + + class AudioClip: + __slots__ = {'bit_rate': 'expressed in kilohertz to one decimal place', + 'duration': 'in seconds, rounded up to an integer'} + def __init__(self, bit_rate, duration): + self.bit_rate = round(bit_rate / 1000.0, 1) + self.duration = ceil(duration) + +(Contributed by Raymond Hettinger in :issue:`36326`.) + + +io +-- + +In development mode (:option:`-X` ``env``) and in debug build, the +:class:`io.IOBase` finalizer now logs the exception if the ``close()`` method +fails. The exception is ignored silently by default in release build. +(Contributed by Victor Stinner in :issue:`18748`.) + + +itertools +--------- + +The :func:`itertools.accumulate` function added an option *initial* keyword +argument to specify an initial value:: + + >>> from itertools import accumulate + >>> list(accumulate([10, 5, 30, 15], initial=1000)) + [1000, 1010, 1015, 1045, 1060] + +(Contributed by Lisa Roach in :issue:`34659`.) + + +json.tool +--------- + +Add option ``--json-lines`` to parse every input line as a separate JSON object. +(Contributed by Weipeng Hong in :issue:`31553`.) + + +logging +------- + +Added a *force* keyword argument to :func:`logging.basicConfig()` +When set to true, any existing handlers attached +to the root logger are removed and closed before carrying out the +configuration specified by the other arguments. + +This solves a long-standing problem. Once a logger or *basicConfig()* had +been called, subsequent calls to *basicConfig()* were silently ignored. +This made it difficult to update, experiment with, or teach the various +logging configuration options using the interactive prompt or a Jupyter +notebook. + +(Suggested by Raymond Hettinger, implemented by Dong-hee Na, and +reviewed by Vinay Sajip in :issue:`33897`.) + + +math +---- + +Added new function :func:`math.dist` for computing Euclidean distance +between two points. (Contributed by Raymond Hettinger in :issue:`33089`.) + +Expanded the :func:`math.hypot` function to handle multiple dimensions. +Formerly, it only supported the 2-D case. +(Contributed by Raymond Hettinger in :issue:`33089`.) + +Added new function, :func:`math.prod`, as analogous function to :func:`sum` +that returns the product of a 'start' value (default: 1) times an iterable of +numbers:: + + >>> prior = 0.8 + >>> likelihoods = [0.625, 0.84, 0.30] + >>> math.prod(likelihoods, start=prior) + 0.126 + +(Contributed by Pablo Galindo in :issue:`35606`.) + +Added two new combinatoric functions :func:`math.perm` and :func:`math.comb`:: + + >>> math.perm(10, 3) # Permutations of 10 things taken 3 at a time + 720 + >>> math.comb(10, 3) # Combinations of 10 things taken 3 at a time + 120 + +(Contributed by Yash Aggarwal, Keller Fuchs, Serhiy Storchaka, and Raymond +Hettinger in :issue:`37128`, :issue:`37178`, and :issue:`35431`.) + +Added a new function :func:`math.isqrt` for computing accurate integer square +roots without conversion to floating point. The new function supports +arbitrarily large integers. It is faster than ``floor(sqrt(n))`` but slower +than :func:`math.sqrt`:: + + >>> r = 650320427 + >>> s = r ** 2 + >>> isqrt(s - 1) # correct + 650320426 + >>> floor(sqrt(s - 1)) # incorrect + 650320427 + +(Contributed by Mark Dickinson in :issue:`36887`.) + +The function :func:`math.factorial` no longer accepts arguments that are not +int-like. (Contributed by Pablo Galindo in :issue:`33083`.) + + +mmap +---- + +The :class:`mmap.mmap` class now has an :meth:`~mmap.mmap.madvise` method to +access the ``madvise()`` system call. +(Contributed by Zackery Spytz in :issue:`32941`.) + + +multiprocessing +--------------- + +Added new :mod:`multiprocessing.shared_memory` module. +(Contributed by Davin Potts in :issue:`35813`.) + +On macOS, the *spawn* start method is now used by default. +(Contributed by Victor Stinner in :issue:`33725`.) + + +os +-- + +Added new function :func:`~os.add_dll_directory` on Windows for providing +additional search paths for native dependencies when importing extension +modules or loading DLLs using :mod:`ctypes`. +(Contributed by Steve Dower in :issue:`36085`.) + +A new :func:`os.memfd_create` function was added to wrap the +``memfd_create()`` syscall. +(Contributed by Zackery Spytz and Christian Heimes in :issue:`26836`.) + +On Windows, much of the manual logic for handling reparse points (including +symlinks and directory junctions) has been delegated to the operating system. +Specifically, :func:`os.stat` will now traverse anything supported by the +operating system, while :func:`os.lstat` will only open reparse points that +identify as "name surrogates" while others are opened as for :func:`os.stat`. +In all cases, :attr:`stat_result.st_mode` will only have ``S_IFLNK`` set for +symbolic links and not other kinds of reparse points. To identify other kinds +of reparse point, check the new :attr:`stat_result.st_reparse_tag` attribute. + +On Windows, :func:`os.readlink` is now able to read directory junctions. Note +that :func:`~os.path.islink` will return ``False`` for directory junctions, +and so code that checks ``islink`` first will continue to treat junctions as +directories, while code that handles errors from :func:`os.readlink` may now +treat junctions as links. + +(Contributed by Steve Dower in :issue:`37834`.) + + +os.path +------- + +:mod:`os.path` functions that return a boolean result like +:func:`~os.path.exists`, :func:`~os.path.lexists`, :func:`~os.path.isdir`, +:func:`~os.path.isfile`, :func:`~os.path.islink`, and :func:`~os.path.ismount` +now return ``False`` instead of raising :exc:`ValueError` or its subclasses +:exc:`UnicodeEncodeError` and :exc:`UnicodeDecodeError` for paths that contain +characters or bytes unrepresentable at the OS level. +(Contributed by Serhiy Storchaka in :issue:`33721`.) + +:func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE` +environment variable and does not use :envvar:`HOME`, which is not normally set +for regular user accounts. +(Contributed by Anthony Sottile in :issue:`36264`.) + +:func:`~os.path.isdir` on Windows no longer returns ``True`` for a link to a +non-existent directory. + +:func:`~os.path.realpath` on Windows now resolves reparse points, including +symlinks and directory junctions. + +(Contributed by Steve Dower in :issue:`37834`.) + + +pathlib +------- + +:mod:`pathlib.Path` methods that return a boolean result like +:meth:`~pathlib.Path.exists()`, :meth:`~pathlib.Path.is_dir()`, +:meth:`~pathlib.Path.is_file()`, :meth:`~pathlib.Path.is_mount()`, +:meth:`~pathlib.Path.is_symlink()`, :meth:`~pathlib.Path.is_block_device()`, +:meth:`~pathlib.Path.is_char_device()`, :meth:`~pathlib.Path.is_fifo()`, +:meth:`~pathlib.Path.is_socket()` now return ``False`` instead of raising +:exc:`ValueError` or its subclass :exc:`UnicodeEncodeError` for paths that +contain characters unrepresentable at the OS level. +(Contributed by Serhiy Storchaka in :issue:`33721`.) + +Added :meth:`pathlib.Path.link_to()` which creates a hard link pointing +to a path. +(Contributed by Joannah Nanjekye in :issue:`26978`) + + +pickle +------ + +:mod:`pickle` extensions subclassing the C-optimized :class:`~pickle.Pickler` +can now override the pickling logic of functions and classes by defining the +special :meth:`~pickle.Pickler.reducer_override` method. +(Contributed by Pierre Glaser and Olivier Grisel in :issue:`35900`.) + + +plistlib +-------- + +Added new :class:`plistlib.UID` and enabled support for reading and writing +NSKeyedArchiver-encoded binary plists. +(Contributed by Jon Janzen in :issue:`26707`.) + + +pprint +------ + +The :mod:`pprint` module added a *sort_dicts* parameter to several functions. +By default, those functions continue to sort dictionaries before rendering or +printing. However, if *sort_dicts* is set to false, the dictionaries retain +the order that keys were inserted. This can be useful for comparison to JSON +inputs during debugging. + +In addition, there is a convenience new function, :func:`pprint.pp` that is +like :func:`pprint.pprint` but with *sort_dicts* defaulting to ``False``:: + + >>> from pprint import pprint, pp + >>> d = dict(source='input.txt', operation='filter', destination='output.txt') + >>> pp(d, width=40) # Original order + {'source': 'input.txt', + 'operation': 'filter', + 'destination': 'output.txt'} + >>> pprint(d, width=40) # Keys sorted alphabetically + {'destination': 'output.txt', + 'operation': 'filter', + 'source': 'input.txt'} + +(Contributed by Rémi Lapeyre in :issue:`30670`.) + + +py_compile +---------- + +:func:`py_compile.compile` now supports silent mode. +(Contributed by Joannah Nanjekye in :issue:`22640`.) + + +shlex +----- + +The new :func:`shlex.join` function acts as the inverse of :func:`shlex.split`. +(Contributed by Bo Bayles in :issue:`32102`.) + + +shutil +------ + +:func:`shutil.copytree` now accepts a new ``dirs_exist_ok`` keyword argument. +(Contributed by Josh Bronson in :issue:`20849`.) + +:func:`shutil.make_archive` now defaults to the modern pax (POSIX.1-2001) +format for new archives to improve portability and standards conformance, +inherited from the corresponding change to the :mod:`tarfile` module. +(Contributed by C.A.M. Gerlach in :issue:`30661`.) + +:func:`shutil.rmtree` on Windows now removes directory junctions without +recursively removing their contents first. +(Contributed by Steve Dower in :issue:`37834`.) + + +socket +------ + +Added :meth:`~socket.create_server()` and :meth:`~socket.has_dualstack_ipv6()` +convenience functions to automate the necessary tasks usually involved when +creating a server socket, including accepting both IPv4 and IPv6 connections +on the same socket. (Contributed by Giampaolo Rodolà in :issue:`17561`.) + +The :func:`socket.if_nameindex()`, :func:`socket.if_nametoindex()`, and +:func:`socket.if_indextoname()` functions have been implemented on Windows. +(Contributed by Zackery Spytz in :issue:`37007`.) + + +ssl +--- + +Added :attr:`~ssl.SSLContext.post_handshake_auth` to enable and +:meth:`~ssl.SSLSocket.verify_client_post_handshake` to initiate TLS 1.3 +post-handshake authentication. +(Contributed by Christian Heimes in :issue:`34670`.) + + +statistics +---------- + +Added :func:`statistics.fmean` as a faster, floating point variant of +:func:`statistics.mean()`. (Contributed by Raymond Hettinger and +Steven D'Aprano in :issue:`35904`.) + +Added :func:`statistics.geometric_mean()` +(Contributed by Raymond Hettinger in :issue:`27181`.) + +Added :func:`statistics.multimode` that returns a list of the most +common values. (Contributed by Raymond Hettinger in :issue:`35892`.) + +Added :func:`statistics.quantiles` that divides data or a distribution +in to equiprobable intervals (e.g. quartiles, deciles, or percentiles). +(Contributed by Raymond Hettinger in :issue:`36546`.) + +Added :class:`statistics.NormalDist`, a tool for creating +and manipulating normal distributions of a random variable. +(Contributed by Raymond Hettinger in :issue:`36018`.) + +:: + + >>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14]) + >>> temperature_feb.mean + 6.0 + >>> temperature_feb.stdev + 6.356099432828281 + + >>> temperature_feb.cdf(3) # Chance of being under 3 degrees + 0.3184678262814532 + >>> # Relative chance of being 7 degrees versus 10 degrees + >>> temperature_feb.pdf(7) / temperature_feb.pdf(10) + 1.2039930378537762 + + >>> el_niño = NormalDist(4, 2.5) + >>> temperature_feb += el_niño # Add in a climate effect + >>> temperature_feb + NormalDist(mu=10.0, sigma=6.830080526611674) + + >>> temperature_feb * (9/5) + 32 # Convert to Fahrenheit + NormalDist(mu=50.0, sigma=12.294144947901014) + >>> temperature_feb.samples(3) # Generate random samples + [7.672102882379219, 12.000027119750287, 4.647488369766392] + + +sys +--- + +Add new :func:`sys.unraisablehook` function which can be overridden to control +how "unraisable exceptions" are handled. It is called when an exception has +occurred but there is no way for Python to handle it. For example, when a +destructor raises an exception or during garbage collection +(:func:`gc.collect`). +(Contributed by Victor Stinner in :issue:`36829`.) + + +tarfile +------- + +The :mod:`tarfile` module now defaults to the modern pax (POSIX.1-2001) +format for new archives, instead of the previous GNU-specific one. +This improves cross-platform portability with a consistent encoding (UTF-8) +in a standardized and extensible format, and offers several other benefits. +(Contributed by C.A.M. Gerlach in :issue:`36268`.) + + +threading +--------- + +Add a new :func:`threading.excepthook` function which handles uncaught +:meth:`threading.Thread.run` exception. It can be overridden to control how +uncaught :meth:`threading.Thread.run` exceptions are handled. +(Contributed by Victor Stinner in :issue:`1230540`.) + +Add a new :func:`threading.get_native_id` function and +a :data:`~threading.Thread.native_id` +attribute to the :class:`threading.Thread` class. These return the native +integral Thread ID of the current thread assigned by the kernel. +This feature is only available on certain platforms, see +:func:`get_native_id ` for more information. +(Contributed by Jake Tesler in :issue:`36084`.) + + +tokenize +-------- + +The :mod:`tokenize` module now implicitly emits a ``NEWLINE`` token when +provided with input that does not have a trailing new line. This behavior +now matches what the C tokenizer does internally. +(Contributed by Ammar Askar in :issue:`33899`.) + + +tkinter +------- + +Added methods :meth:`~tkinter.Spinbox.selection_from`, +:meth:`~tkinter.Spinbox.selection_present`, +:meth:`~tkinter.Spinbox.selection_range` and +:meth:`~tkinter.Spinbox.selection_to` +in the :class:`tkinter.Spinbox` class. +(Contributed by Juliette Monsel in :issue:`34829`.) + +Added method :meth:`~tkinter.Canvas.moveto` +in the :class:`tkinter.Canvas` class. +(Contributed by Juliette Monsel in :issue:`23831`.) + +The :class:`tkinter.PhotoImage` class now has +:meth:`~tkinter.PhotoImage.transparency_get` and +:meth:`~tkinter.PhotoImage.transparency_set` methods. (Contributed by +Zackery Spytz in :issue:`25451`.) + + +time +---- + +Added new clock :data:`~time.CLOCK_UPTIME_RAW` for macOS 10.12. +(Contributed by Joannah Nanjekye in :issue:`35702`.) + + +typing +------ + +The :mod:`typing` module incorporates several new features: + +* A dictionary type with per-key types. See :pep:`589` and + :class:`typing.TypedDict`. + TypedDict uses only string keys. By default, every key is required + to be present. Specify "total=False" to allow keys to be optional:: + + class Location(TypedDict, total=False): + lat_long: tuple + grid_square: str + xy_coordinate: tuple + +* Literal types. See :pep:`586` and :class:`typing.Literal`. + Literal types indicate that a parameter or return value + is constrained to one or more specific literal values:: + + def get_status(port: int) -> Literal['connected', 'disconnected']: + ... + +* "Final" variables, functions, methods and classes. See :pep:`591`, + :class:`typing.Final` and :func:`typing.final`. + The final qualifier instructs a static type checker to restrict + subclassing, overriding, or reassignment:: + + pi: Final[float] = 3.1415926536 + +* Protocol definitions. See :pep:`544`, :class:`typing.Protocol` and + :func:`typing.runtime_checkable`. Simple ABCs like + :class:`typing.SupportsInt` are now ``Protocol`` subclasses. + +* New protocol class :class:`typing.SupportsIndex`. + +* New functions :func:`typing.get_origin` and :func:`typing.get_args`. + + +unicodedata +----------- + +The :mod:`unicodedata` module has been upgraded to use the `Unicode 12.1.0 +`_ release. + +New function :func:`~unicodedata.is_normalized` can be used to verify a string +is in a specific normal form, often much faster than by actually normalizing +the string. (Contributed by Max Belanger, David Euresti, and Greg Price in +:issue:`32285` and :issue:`37966`). + + +unittest +-------- + +Added :class:`~unittest.mock.AsyncMock` to support an asynchronous version of +:class:`~unittest.mock.Mock`. Appropriate new assert functions for testing +have been added as well. +(Contributed by Lisa Roach in :issue:`26467`). + +Added :func:`~unittest.addModuleCleanup()` and +:meth:`~unittest.TestCase.addClassCleanup()` to unittest to support +cleanups for :func:`~unittest.setUpModule()` and +:meth:`~unittest.TestCase.setUpClass()`. +(Contributed by Lisa Roach in :issue:`24412`.) + +Several mock assert functions now also print a list of actual calls upon +failure. (Contributed by Petter Strandmark in :issue:`35047`.) + +:mod:`unittest` module gained support for coroutines to be used as test cases +with :class:`unittest.IsolatedAsyncioTestCase`. +(Contributed by Andrew Svetlov in :issue:`32972`.) + +Example:: + + import unittest + + + class TestRequest(unittest.IsolatedAsyncioTestCase): + + async def asyncSetUp(self): + self.connection = await AsyncConnection() + + async def test_get(self): + response = await self.connection.get("https://example.com") + self.assertEqual(response.status_code, 200) + + async def asyncTearDown(self): + await self.connection.close() + + + if __name__ == "__main__": + unittest.main() + + +venv +---- + +:mod:`venv` now includes an ``Activate.ps1`` script on all platforms for +activating virtual environments under PowerShell Core 6.1. +(Contributed by Brett Cannon in :issue:`32718`.) + + +weakref +------- + +The proxy objects returned by :func:`weakref.proxy` now support the matrix +multiplication operators ``@`` and ``@=`` in addition to the other +numeric operators. (Contributed by Mark Dickinson in :issue:`36669`.) + + +xml +--- + +As mitigation against DTD and external entity retrieval, the +:mod:`xml.dom.minidom` and :mod:`xml.sax` modules no longer process +external entities by default. +(Contributed by Christian Heimes in :issue:`17239`.) + +The ``.find*()`` methods in the :mod:`xml.etree.ElementTree` module +support wildcard searches like ``{*}tag`` which ignores the namespace +and ``{namespace}*`` which returns all tags in the given namespace. +(Contributed by Stefan Behnel in :issue:`28238`.) + +The :mod:`xml.etree.ElementTree` module provides a new function +:func:`–xml.etree.ElementTree.canonicalize()` that implements C14N 2.0. +(Contributed by Stefan Behnel in :issue:`13611`.) + +The target object of :class:`xml.etree.ElementTree.XMLParser` can +receive namespace declaration events through the new callback methods +``start_ns()`` and ``end_ns()``. Additionally, the +:class:`xml.etree.ElementTree.TreeBuilder` target can be configured +to process events about comments and processing instructions to include +them in the generated tree. +(Contributed by Stefan Behnel in :issue:`36676` and :issue:`36673`.) + + +xmlrpc +------ + +:class:`xmlrpc.client.ServerProxy` now supports an optional *headers* keyword +argument for a sequence of HTTP headers to be sent with each request. Among +other things, this makes it possible to upgrade from default basic +authentication to faster session authentication. +(Contributed by Cédric Krier in :issue:`35153`.) + + +Optimizations +============= + +* The :mod:`subprocess` module can now use the :func:`os.posix_spawn` function + in some cases for better performance. Currently, it is only used on macOS + and Linux (using glibc 2.24 or newer) if all these conditions are met: + + * *close_fds* is false; + * *preexec_fn*, *pass_fds*, *cwd* and *start_new_session* parameters + are not set; + * the *executable* path contains a directory. + + (Contributed by Joannah Nanjekye and Victor Stinner in :issue:`35537`.) + +* :func:`shutil.copyfile`, :func:`shutil.copy`, :func:`shutil.copy2`, + :func:`shutil.copytree` and :func:`shutil.move` use platform-specific + "fast-copy" syscalls on Linux and macOS in order to copy the file + more efficiently. + "fast-copy" means that the copying operation occurs within the kernel, + avoiding the use of userspace buffers in Python as in + "``outfd.write(infd.read())``". + On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB + instead of 16 KiB) and a :func:`memoryview`-based variant of + :func:`shutil.copyfileobj` is used. + The speedup for copying a 512 MiB file within the same partition is about + +26% on Linux, +50% on macOS and +40% on Windows. Also, much less CPU cycles + are consumed. + See :ref:`shutil-platform-dependent-efficient-copy-operations` section. + (Contributed by Giampaolo Rodolà in :issue:`33671`.) + +* :func:`shutil.copytree` uses :func:`os.scandir` function and all copy + functions depending from it use cached :func:`os.stat` values. The speedup + for copying a directory with 8000 files is around +9% on Linux, +20% on + Windows and +30% on a Windows SMB share. Also the number of :func:`os.stat` + syscalls is reduced by 38% making :func:`shutil.copytree` especially faster + on network filesystems. (Contributed by Giampaolo Rodolà in :issue:`33695`.) + +* The default protocol in the :mod:`pickle` module is now Protocol 4, + first introduced in Python 3.4. It offers better performance and smaller + size compared to Protocol 3 available since Python 3.0. + +* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked + objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes. + (Contributed by Inada Naoki in :issue:`33597`.) + +* :class:`uuid.UUID` now uses ``__slots__`` to reduce its memory footprint. + (Contributed by Wouter Bolsterlee and Tal Einat in :issue:`30977`) + +* Improved performance of :func:`operator.itemgetter` by 33%. Optimized + argument handling and added a fast path for the common case of a single + non-negative integer index into a tuple (which is the typical use case in + the standard library). (Contributed by Raymond Hettinger in + :issue:`35664`.) + +* Sped-up field lookups in :func:`collections.namedtuple`. They are now more + than two times faster, making them the fastest form of instance variable + lookup in Python. (Contributed by Raymond Hettinger, Pablo Galindo, and + Joe Jevnik, Serhiy Storchaka in :issue:`32492`.) + +* The :class:`list` constructor does not overallocate the internal item buffer + if the input iterable has a known length (the input implements ``__len__``). + This makes the created list 12% smaller on average. (Contributed by + Raymond Hettinger and Pablo Galindo in :issue:`33234`.) + +* Doubled the speed of class variable writes. When a non-dunder attribute + was updated, there was an unnecessary call to update slots. + (Contributed by Stefan Behnel, Pablo Galindo Salgado, Raymond Hettinger, + Neil Schemenauer, and Serhiy Storchaka in :issue:`36012`.) + +* Reduced an overhead of converting arguments passed to many builtin functions + and methods. This sped up calling some simple builtin functions and + methods up to 20--50%. (Contributed by Serhiy Storchaka in :issue:`23867`, + :issue:`35582` and :issue:`36127`.) + +* ``LOAD_GLOBAL`` instruction now uses new "per opcode cache" mechanism. + It is about 40% faster now. (Contributed by Yury Selivanov and Inada Naoki in + :issue:`26219`.) + + +Build and C API Changes +======================= + +* Default :data:`sys.abiflags` became an empty string: the ``m`` flag for + pymalloc became useless (builds with and without pymalloc are ABI compatible) + and so has been removed. (Contributed by Victor Stinner in :issue:`36707`.) + + Example of changes: + + * Only ``python3.8`` program is installed, ``python3.8m`` program is gone. + * Only ``python3.8-config`` script is installed, ``python3.8m-config`` script + is gone. + * The ``m`` flag has been removed from the suffix of dynamic library + filenames: extension modules in the standard library as well as those + produced and installed by third-party packages, like those downloaded from + PyPI. On Linux, for example, the Python 3.7 suffix + ``.cpython-37m-x86_64-linux-gnu.so`` became + ``.cpython-38-x86_64-linux-gnu.so`` in Python 3.8. + +* The header files have been reorganized to better separate the different kinds + of APIs: + + * ``Include/*.h`` should be the portable public stable C API. + * ``Include/cpython/*.h`` should be the unstable C API specific to CPython; + public API, with some private API prefixed by ``_Py`` or ``_PY``. + * ``Include/internal/*.h`` is the private internal C API very specific to + CPython. This API comes with no backward compatibility warranty and should + not be used outside CPython. It is only exposed for very specific needs + like debuggers and profiles which has to access to CPython internals + without calling functions. This API is now installed by ``make install``. + + (Contributed by Victor Stinner in :issue:`35134` and :issue:`35081`, + work initiated by Eric Snow in Python 3.7.) + +* Some macros have been converted to static inline functions: parameter types + and return type are well defined, they don't have issues specific to macros, + variables have a local scopes. Examples: + + * :c:func:`Py_INCREF`, :c:func:`Py_DECREF` + * :c:func:`Py_XINCREF`, :c:func:`Py_XDECREF` + * :c:func:`PyObject_INIT`, :c:func:`PyObject_INIT_VAR` + * Private functions: :c:func:`_PyObject_GC_TRACK`, + :c:func:`_PyObject_GC_UNTRACK`, :c:func:`_Py_Dealloc` + + (Contributed by Victor Stinner in :issue:`35059`.) + +* The :c:func:`PyByteArray_Init` and :c:func:`PyByteArray_Fini` functions have + been removed. They did nothing since Python 2.7.4 and Python 3.2.0, were + excluded from the limited API (stable ABI), and were not documented. + (Contributed by Victor Stinner in :issue:`35713`.) + +* The result of :c:func:`PyExceptionClass_Name` is now of type + ``const char *`` rather of ``char *``. + (Contributed by Serhiy Storchaka in :issue:`33818`.) + +* The duality of ``Modules/Setup.dist`` and ``Modules/Setup`` has been + removed. Previously, when updating the CPython source tree, one had + to manually copy ``Modules/Setup.dist`` (inside the source tree) to + ``Modules/Setup`` (inside the build tree) in order to reflect any changes + upstream. This was of a small benefit to packagers at the expense of + a frequent annoyance to developers following CPython development, as + forgetting to copy the file could produce build failures. + + Now the build system always reads from ``Modules/Setup`` inside the source + tree. People who want to customize that file are encouraged to maintain + their changes in a git fork of CPython or as patch files, as they would do + for any other change to the source tree. + + (Contributed by Antoine Pitrou in :issue:`32430`.) + +* Functions that convert Python number to C integer like + :c:func:`PyLong_AsLong` and argument parsing functions like + :c:func:`PyArg_ParseTuple` with integer converting format units like ``'i'`` + will now use the :meth:`~object.__index__` special method instead of + :meth:`~object.__int__`, if available. The deprecation warning will be + emitted for objects with the ``__int__()`` method but without the + ``__index__()`` method (like :class:`~decimal.Decimal` and + :class:`~fractions.Fraction`). :c:func:`PyNumber_Check` will now return + ``1`` for objects implementing ``__index__()``. + :c:func:`PyNumber_Long`, :c:func:`PyNumber_Float` and + :c:func:`PyFloat_AsDouble` also now use the ``__index__()`` method if + available. + (Contributed by Serhiy Storchaka in :issue:`36048` and :issue:`20092`.) + +* Heap-allocated type objects will now increase their reference count + in :c:func:`PyObject_Init` (and its parallel macro ``PyObject_INIT``) + instead of in :c:func:`PyType_GenericAlloc`. Types that modify instance + allocation or deallocation may need to be adjusted. + (Contributed by Eddie Elizondo in :issue:`35810`.) + +* The new function :c:func:`PyCode_NewWithPosOnlyArgs` allows to create + code objects like :c:func:`PyCode_New`, but with an extra *posonlyargcount* + parameter for indicating the number of positional-only arguments. + (Contributed by Pablo Galindo in :issue:`37221`.) + +* :c:func:`Py_SetPath` now sets :data:`sys.executable` to the program full + path (:c:func:`Py_GetProgramFullPath`) rather than to the program name + (:c:func:`Py_GetProgramName`). + (Contributed by Victor Stinner in :issue:`38234`.) + + +Deprecated +========== + +* The distutils ``bdist_wininst`` command is now deprecated, use + ``bdist_wheel`` (wheel packages) instead. + (Contributed by Victor Stinner in :issue:`37481`.) + +* Deprecated methods ``getchildren()`` and ``getiterator()`` in + the :mod:`~xml.etree.ElementTree` module now emit a + :exc:`DeprecationWarning` instead of :exc:`PendingDeprecationWarning`. + They will be removed in Python 3.9. + (Contributed by Serhiy Storchaka in :issue:`29209`.) + +* Passing an object that is not an instance of + :class:`concurrent.futures.ThreadPoolExecutor` to + :meth:`loop.set_default_executor() ` is + deprecated and will be prohibited in Python 3.9. + (Contributed by Elvis Pranskevichus in :issue:`34075`.) + +* The :meth:`__getitem__` methods of :class:`xml.dom.pulldom.DOMEventStream`, + :class:`wsgiref.util.FileWrapper` and :class:`fileinput.FileInput` have been + deprecated. + + Implementations of these methods have been ignoring their *index* parameter, + and returning the next item instead. + (Contributed by Berker Peksag in :issue:`9372`.) + +* The :class:`typing.NamedTuple` class has deprecated the ``_field_types`` + attribute in favor of the ``__annotations__`` attribute which has the same + information. (Contributed by Raymond Hettinger in :issue:`36320`.) + +* :mod:`ast` classes ``Num``, ``Str``, ``Bytes``, ``NameConstant`` and + ``Ellipsis`` are considered deprecated and will be removed in future Python + versions. :class:`~ast.Constant` should be used instead. + (Contributed by Serhiy Storchaka in :issue:`32892`.) + +* :class:`ast.NodeVisitor` methods ``visit_Num()``, ``visit_Str()``, + ``visit_Bytes()``, ``visit_NameConstant()`` and ``visit_Ellipsis()`` are + deprecated now and will not be called in future Python versions. + Add the :meth:`~ast.NodeVisitor.visit_Constant` method to handle all + constant nodes. + (Contributed by Serhiy Storchaka in :issue:`36917`.) + +* The :func:`asyncio.coroutine` :term:`decorator` is deprecated and will be + removed in version 3.10. Instead of ``@asyncio.coroutine``, use + :keyword:`async def` instead. + (Contributed by Andrew Svetlov in :issue:`36921`.) + +* In :mod:`asyncio`, the explicit passing of a *loop* argument has been + deprecated and will be removed in version 3.10 for the following: + :func:`asyncio.sleep`, :func:`asyncio.gather`, :func:`asyncio.shield`, + :func:`asyncio.wait_for`, :func:`asyncio.wait`, :func:`asyncio.as_completed`, + :class:`asyncio.Task`, :class:`asyncio.Lock`, :class:`asyncio.Event`, + :class:`asyncio.Condition`, :class:`asyncio.Semaphore`, + :class:`asyncio.BoundedSemaphore`, :class:`asyncio.Queue`, + :func:`asyncio.create_subprocess_exec`, and + :func:`asyncio.create_subprocess_shell`. + +* The explicit passing of coroutine objects to :func:`asyncio.wait` has been + deprecated and will be removed in version 3.11. + (Contributed by Yury Selivanov in :issue:`34790`.) + +* The following functions and methods are deprecated in the :mod:`gettext` + module: :func:`~gettext.lgettext`, :func:`~gettext.ldgettext`, + :func:`~gettext.lngettext` and :func:`~gettext.ldngettext`. + They return encoded bytes, and it's possible that you will get unexpected + Unicode-related exceptions if there are encoding problems with the + translated strings. It's much better to use alternatives which return + Unicode strings in Python 3. These functions have been broken for a long time. + + Function :func:`~gettext.bind_textdomain_codeset`, methods + :meth:`~gettext.NullTranslations.output_charset` and + :meth:`~gettext.NullTranslations.set_output_charset`, and the *codeset* + parameter of functions :func:`~gettext.translation` and + :func:`~gettext.install` are also deprecated, since they are only used for + for the ``l*gettext()`` functions. + (Contributed by Serhiy Storchaka in :issue:`33710`.) + +* The :meth:`~threading.Thread.isAlive()` method of :class:`threading.Thread` + has been deprecated. + (Contributed by Dong-hee Na in :issue:`35283`.) + +* Many builtin and extension functions that take integer arguments will + now emit a deprecation warning for :class:`~decimal.Decimal`\ s, + :class:`~fractions.Fraction`\ s and any other objects that can be converted + to integers only with a loss (e.g. that have the :meth:`~object.__int__` + method but do not have the :meth:`~object.__index__` method). In future + version they will be errors. + (Contributed by Serhiy Storchaka in :issue:`36048`.) + +* Deprecated passing the following arguments as keyword arguments: + + - *func* in :func:`functools.partialmethod`, :func:`weakref.finalize`, + :meth:`profile.Profile.runcall`, :meth:`cProfile.Profile.runcall`, + :meth:`bdb.Bdb.runcall`, :meth:`trace.Trace.runfunc` and + :func:`curses.wrapper`. + - *function* in :meth:`unittest.TestCase.addCleanup`. + - *fn* in the :meth:`~concurrent.futures.Executor.submit` method of + :class:`concurrent.futures.ThreadPoolExecutor` and + :class:`concurrent.futures.ProcessPoolExecutor`. + - *callback* in :meth:`contextlib.ExitStack.callback`, + :meth:`contextlib.AsyncExitStack.callback` and + :meth:`contextlib.AsyncExitStack.push_async_callback`. + - *c* and *typeid* in the :meth:`~multiprocessing.managers.Server.create` + method of :class:`multiprocessing.managers.Server` and + :class:`multiprocessing.managers.SharedMemoryServer`. + - *obj* in :func:`weakref.finalize`. + + In future releases of Python, they will be :ref:`positional-only + `. + (Contributed by Serhiy Storchaka in :issue:`36492`.) + + +API and Feature Removals +======================== + +The following features and APIs have been removed from Python 3.8: + +* Starting with Python 3.3, importing ABCs from :mod:`collections` was + deprecated, and importing should be done from :mod:`collections.abc`. Being + able to import from collections was marked for removal in 3.8, but has been + delayed to 3.9. (See :issue:`36952`.) + +* The :mod:`macpath` module, deprecated in Python 3.7, has been removed. + (Contributed by Victor Stinner in :issue:`35471`.) + +* The function :func:`platform.popen` has been removed, after having been + deprecated since Python 3.3: use :func:`os.popen` instead. + (Contributed by Victor Stinner in :issue:`35345`.) + +* The function :func:`time.clock` has been removed, after having been + deprecated since Python 3.3: use :func:`time.perf_counter` or + :func:`time.process_time` instead, depending + on your requirements, to have well-defined behavior. + (Contributed by Matthias Bussonnier in :issue:`36895`.) + +* The ``pyvenv`` script has been removed in favor of ``python3.8 -m venv`` + to help eliminate confusion as to what Python interpreter the ``pyvenv`` + script is tied to. (Contributed by Brett Cannon in :issue:`25427`.) + +* ``parse_qs``, ``parse_qsl``, and ``escape`` are removed from the :mod:`cgi` + module. They are deprecated in Python 3.2 or older. They should be imported + from the ``urllib.parse`` and ``html`` modules instead. + +* ``filemode`` function is removed from the :mod:`tarfile` module. + It is not documented and deprecated since Python 3.3. + +* The :class:`~xml.etree.ElementTree.XMLParser` constructor no longer accepts + the *html* argument. It never had an effect and was deprecated in Python 3.4. + All other parameters are now :ref:`keyword-only `. + (Contributed by Serhiy Storchaka in :issue:`29209`.) + +* Removed the ``doctype()`` method of :class:`~xml.etree.ElementTree.XMLParser`. + (Contributed by Serhiy Storchaka in :issue:`29209`.) + +* "unicode_internal" codec is removed. + (Contributed by Inada Naoki in :issue:`36297`.) + +* The ``Cache`` and ``Statement`` objects of the :mod:`sqlite3` module are not + exposed to the user. + (Contributed by Aviv Palivoda in :issue:`30262`.) + +* The ``bufsize`` keyword argument of :func:`fileinput.input` and + :func:`fileinput.FileInput` which was ignored and deprecated since Python 3.6 + has been removed. :issue:`36952` (Contributed by Matthias Bussonnier.) + +* The functions :func:`sys.set_coroutine_wrapper` and + :func:`sys.get_coroutine_wrapper` deprecated in Python 3.7 have been removed; + :issue:`36933` (Contributed by Matthias Bussonnier.) + + +Porting to Python 3.8 +===================== + +This section lists previously described changes and other bugfixes +that may require changes to your code. + + +Changes in Python behavior +-------------------------- + +* Yield expressions (both ``yield`` and ``yield from`` clauses) are now disallowed + in comprehensions and generator expressions (aside from the iterable expression + in the leftmost :keyword:`!for` clause). + (Contributed by Serhiy Storchaka in :issue:`10544`.) + +* The compiler now produces a :exc:`SyntaxWarning` when identity checks + (``is`` and ``is not``) are used with certain types of literals + (e.g. strings, numbers). These can often work by accident in CPython, + but are not guaranteed by the language spec. The warning advises users + to use equality tests (``==`` and ``!=``) instead. + (Contributed by Serhiy Storchaka in :issue:`34850`.) + +* The CPython interpreter can swallow exceptions in some circumstances. + In Python 3.8 this happens in fewer cases. In particular, exceptions + raised when getting the attribute from the type dictionary are no longer + ignored. (Contributed by Serhiy Storchaka in :issue:`35459`.) + +* Removed ``__str__`` implementations from builtin types :class:`bool`, + :class:`int`, :class:`float`, :class:`complex` and few classes from + the standard library. They now inherit ``__str__()`` from :class:`object`. + As result, defining the ``__repr__()`` method in the subclass of these + classes will affect their string representation. + (Contributed by Serhiy Storchaka in :issue:`36793`.) + +* On AIX, :attr:`sys.platform` doesn't contain the major version anymore. + It is always ``'aix'``, instead of ``'aix3'`` .. ``'aix7'``. Since + older Python versions include the version number, so it is recommended to + always use ``sys.platform.startswith('aix')``. + (Contributed by M. Felt in :issue:`36588`.) + +* :c:func:`PyEval_AcquireLock` and :c:func:`PyEval_AcquireThread` now + terminate the current thread if called while the interpreter is + finalizing, making them consistent with :c:func:`PyEval_RestoreThread`, + :c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`. If this + behavior is not desired, guard the call by checking :c:func:`_Py_IsFinalizing` + or :c:func:`sys.is_finalizing`. + (Contributed by Joannah Nanjekye in :issue:`36475`.) + + +Changes in the Python API +------------------------- + +* The :func:`os.getcwdb` function now uses the UTF-8 encoding on Windows, + rather than the ANSI code page: see :pep:`529` for the rationale. The + function is no longer deprecated on Windows. + (Contributed by Victor Stinner in :issue:`37412`.) + +* :class:`subprocess.Popen` can now use :func:`os.posix_spawn` in some cases + for better performance. On Windows Subsystem for Linux and QEMU User + Emulation, the :class:`Popen` constructor using :func:`os.posix_spawn` no longer raises an + exception on errors like "missing program". Instead the child process fails with a + non-zero :attr:`~Popen.returncode`. + (Contributed by Joannah Nanjekye and Victor Stinner in :issue:`35537`.) + +* The *preexec_fn* argument of * :class:`subprocess.Popen` is no longer + compatible with subinterpreters. The use of the parameter in a + subinterpreter now raises :exc:`RuntimeError`. + (Contributed by Eric Snow in :issue:`34651`, modified by Christian Heimes + in :issue:`37951`.) + +* The :meth:`imap.IMAP4.logout` method no longer silently ignores arbitrary + exceptions. + (Contributed by Victor Stinner in :issue:`36348`.) + +* The function :func:`platform.popen` has been removed, after having been deprecated since + Python 3.3: use :func:`os.popen` instead. + (Contributed by Victor Stinner in :issue:`35345`.) + +* The :func:`statistics.mode` function no longer raises an exception + when given multimodal data. Instead, it returns the first mode + encountered in the input data. (Contributed by Raymond Hettinger + in :issue:`35892`.) + +* The :meth:`~tkinter.ttk.Treeview.selection` method of the + :class:`tkinter.ttk.Treeview` class no longer takes arguments. Using it with + arguments for changing the selection was deprecated in Python 3.6. Use + specialized methods like :meth:`~tkinter.ttk.Treeview.selection_set` for + changing the selection. (Contributed by Serhiy Storchaka in :issue:`31508`.) + +* The :meth:`writexml`, :meth:`toxml` and :meth:`toprettyxml` methods of + :mod:`xml.dom.minidom`, and the :meth:`write` method of :mod:`xml.etree`, + now preserve the attribute order specified by the user. + (Contributed by Diego Rojas and Raymond Hettinger in :issue:`34160`.) + +* A :mod:`dbm.dumb` database opened with flags ``'r'`` is now read-only. + :func:`dbm.dumb.open` with flags ``'r'`` and ``'w'`` no longer creates + a database if it does not exist. + (Contributed by Serhiy Storchaka in :issue:`32749`.) + +* The ``doctype()`` method defined in a subclass of + :class:`~xml.etree.ElementTree.XMLParser` will no longer be called and will + emit a :exc:`RuntimeWarning` instead of a :exc:`DeprecationWarning`. + Define the :meth:`doctype() ` + method on a target for handling an XML doctype declaration. + (Contributed by Serhiy Storchaka in :issue:`29209`.) + +* A :exc:`RuntimeError` is now raised when the custom metaclass doesn't + provide the ``__classcell__`` entry in the namespace passed to + ``type.__new__``. A :exc:`DeprecationWarning` was emitted in Python + 3.6--3.7. (Contributed by Serhiy Storchaka in :issue:`23722`.) + +* The :class:`cProfile.Profile` class can now be used as a context + manager. (Contributed by Scott Sanderson in :issue:`29235`.) + +* :func:`shutil.copyfile`, :func:`shutil.copy`, :func:`shutil.copy2`, + :func:`shutil.copytree` and :func:`shutil.move` use platform-specific + "fast-copy" syscalls (see + :ref:`shutil-platform-dependent-efficient-copy-operations` section). + +* :func:`shutil.copyfile` default buffer size on Windows was changed from + 16 KiB to 1 MiB. + +* The ``PyGC_Head`` struct has changed completely. All code that touched the + struct member should be rewritten. (See :issue:`33597`.) + +* The :c:type:`PyInterpreterState` struct has been moved into the "internal" + header files (specifically Include/internal/pycore_pystate.h). An + opaque ``PyInterpreterState`` is still available as part of the public + API (and stable ABI). The docs indicate that none of the struct's + fields are public, so we hope no one has been using them. However, + if you do rely on one or more of those private fields and have no + alternative then please open a BPO issue. We'll work on helping + you adjust (possibly including adding accessor functions to the + public API). (See :issue:`35886`.) + +* The :meth:`mmap.flush() ` method now returns ``None`` on + success and raises an exception on error under all platforms. Previously, + its behavior was platform-dependent: a nonzero value was returned on success; + zero was returned on error under Windows. A zero value was returned on + success; an exception was raised on error under Unix. + (Contributed by Berker Peksag in :issue:`2122`.) + +* :mod:`xml.dom.minidom` and :mod:`xml.sax` modules no longer process + external entities by default. + (Contributed by Christian Heimes in :issue:`17239`.) + +* Deleting a key from a read-only :mod:`dbm` database (:mod:`dbm.dumb`, + :mod:`dbm.gnu` or :mod:`dbm.ndbm`) raises :attr:`error` (:exc:`dbm.dumb.error`, + :exc:`dbm.gnu.error` or :exc:`dbm.ndbm.error`) instead of :exc:`KeyError`. + (Contributed by Xiang Zhang in :issue:`33106`.) + +* :func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE` + environment variable and does not use :envvar:`HOME`, which is not normally + set for regular user accounts. + (Contributed by Anthony Sottile in :issue:`36264`.) + +* The exception :class:`asyncio.CancelledError` now inherits from + :class:`BaseException` rather than :class:`Exception`. + (Contributed by Yury Selivanov in :issue:`32528`.) + +* The function :func:`asyncio.wait_for` now correctly waits for cancellation + when using an instance of :class:`asyncio.Task`. Previously, upon reaching + *timeout*, it was cancelled and immediately returned. + (Contributed by Elvis Pranskevichus in :issue:`32751`.) + +* The function :func:`asyncio.BaseTransport.get_extra_info` now returns a safe + to use socket object when 'socket' is passed to the *name* parameter. + (Contributed by Yury Selivanov in :issue:`37027`.) + +* :class:`asyncio.BufferedProtocol` has graduated to the stable API. + +.. _bpo-36085-whatsnew: + +* DLL dependencies for extension modules and DLLs loaded with :mod:`ctypes` on + Windows are now resolved more securely. Only the system paths, the directory + containing the DLL or PYD file, and directories added with + :func:`~os.add_dll_directory` are searched for load-time dependencies. + Specifically, :envvar:`PATH` and the current working directory are no longer + used, and modifications to these will no longer have any effect on normal DLL + resolution. If your application relies on these mechanisms, you should check + for :func:`~os.add_dll_directory` and if it exists, use it to add your DLLs + directory while loading your library. Note that Windows 7 users will need to + ensure that Windows Update KB2533623 has been installed (this is also verified + by the installer). + (Contributed by Steve Dower in :issue:`36085`.) + +* The header files and functions related to pgen have been removed after its + replacement by a pure Python implementation. (Contributed by Pablo Galindo + in :issue:`36623`.) + +* :class:`types.CodeType` has a new parameter in the second position of the + constructor (*posonlyargcount*) to support positional-only arguments defined + in :pep:`570`. The first argument (*argcount*) now represents the total + number of positional arguments (including positional-only arguments). The new + ``replace()`` method of :class:`types.CodeType` can be used to make the code + future-proof. + + +Changes in the C API +-------------------- + +* The :c:type:`PyCompilerFlags` structure got a new *cf_feature_version* + field. It should be initialized to ``PY_MINOR_VERSION``. The field is ignored + by default, and is used if and only if ``PyCF_ONLY_AST`` flag is set in + *cf_flags*. + (Contributed by Guido van Rossum in :issue:`35766`.) + +* The :c:func:`PyEval_ReInitThreads` function has been removed from the C API. + It should not be called explicitly: use :c:func:`PyOS_AfterFork_Child` + instead. + (Contributed by Victor Stinner in :issue:`36728`.) + +* On Unix, C extensions are no longer linked to libpython except on Android + and Cygwin. When Python is embedded, ``libpython`` must not be loaded with + ``RTLD_LOCAL``, but ``RTLD_GLOBAL`` instead. Previously, using + ``RTLD_LOCAL``, it was already not possible to load C extensions which + were not linked to ``libpython``, like C extensions of the standard + library built by the ``*shared*`` section of ``Modules/Setup``. + (Contributed by Victor Stinner in :issue:`21536`.) + +* Use of ``#`` variants of formats in parsing or building value (e.g. + :c:func:`PyArg_ParseTuple`, :c:func:`Py_BuildValue`, :c:func:`PyObject_CallFunction`, + etc.) without ``PY_SSIZE_T_CLEAN`` defined raises ``DeprecationWarning`` now. + It will be removed in 3.10 or 4.0. Read :ref:`arg-parsing` for detail. + (Contributed by Inada Naoki in :issue:`36381`.) + +* Instances of heap-allocated types (such as those created with + :c:func:`PyType_FromSpec`) hold a reference to their type object. + Increasing the reference count of these type objects has been moved from + :c:func:`PyType_GenericAlloc` to the more low-level functions, + :c:func:`PyObject_Init` and :c:func:`PyObject_INIT`. + This makes types created through :c:func:`PyType_FromSpec` behave like + other classes in managed code. + + Statically allocated types are not affected. + + For the vast majority of cases, there should be no side effect. + However, types that manually increase the reference count after allocating + an instance (perhaps to work around the bug) may now become immortal. + To avoid this, these classes need to call Py_DECREF on the type object + during instance deallocation. + + To correctly port these types into 3.8, please apply the following + changes: + + * Remove :c:macro:`Py_INCREF` on the type object after allocating an + instance - if any. + This may happen after calling :c:func:`PyObject_New`, + :c:func:`PyObject_NewVar`, :c:func:`PyObject_GC_New`, + :c:func:`PyObject_GC_NewVar`, or any other custom allocator that uses + :c:func:`PyObject_Init` or :c:func:`PyObject_INIT`. + + Example: + + .. code-block:: c + + static foo_struct * + foo_new(PyObject *type) { + foo_struct *foo = PyObject_GC_New(foo_struct, (PyTypeObject *) type); + if (foo == NULL) + return NULL; + #if PY_VERSION_HEX < 0x03080000 + // Workaround for Python issue 35810; no longer necessary in Python 3.8 + PY_INCREF(type) + #endif + return foo; + } + + * Ensure that all custom ``tp_dealloc`` functions of heap-allocated types + decrease the type's reference count. + + Example: + + .. code-block:: c + + static void + foo_dealloc(foo_struct *instance) { + PyObject *type = Py_TYPE(instance); + PyObject_GC_Del(instance); + #if PY_VERSION_HEX >= 0x03080000 + // This was not needed before Python 3.8 (Python issue 35810) + Py_DECREF(type); + #endif + } + + (Contributed by Eddie Elizondo in :issue:`35810`.) + +* The :c:macro:`Py_DEPRECATED()` macro has been implemented for MSVC. + The macro now must be placed before the symbol name. + + Example: + + .. code-block:: c + + Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void); + + (Contributed by Zackery Spytz in :issue:`33407`.) + +* The interpreter does not pretend to support binary compatibility of + extension types across feature releases, anymore. A :c:type:`PyTypeObject` + exported by a third-party extension module is supposed to have all the + slots expected in the current Python version, including + :c:member:`~PyTypeObject.tp_finalize` (:const:`Py_TPFLAGS_HAVE_FINALIZE` + is not checked anymore before reading :c:member:`~PyTypeObject.tp_finalize`). + + (Contributed by Antoine Pitrou in :issue:`32388`.) + +* The :c:func:`PyCode_New` has a new parameter in the second position (*posonlyargcount*) + to support :pep:`570`, indicating the number of positional-only arguments. + +* The functions :c:func:`PyNode_AddChild` and :c:func:`PyParser_AddToken` now accept + two additional ``int`` arguments *end_lineno* and *end_col_offset*. + +* The :file:`libpython38.a` file to allow MinGW tools to link directly against + :file:`python38.dll` is no longer included in the regular Windows distribution. + If you require this file, it may be generated with the ``gendef`` and + ``dlltool`` tools, which are part of the MinGW binutils package: + + .. code-block:: shell + + gendef python38.dll > tmp.def + dlltool --dllname python38.dll --def tmp.def --output-lib libpython38.a + + The location of an installed :file:`pythonXY.dll` will depend on the + installation options and the version and language of Windows. See + :ref:`using-on-windows` for more information. The resulting library should be + placed in the same directory as :file:`pythonXY.lib`, which is generally the + :file:`libs` directory under your Python installation. + + (Contributed by Steve Dower in :issue:`37351`.) + + +CPython bytecode changes +------------------------ + +* The interpreter loop has been simplified by moving the logic of unrolling + the stack of blocks into the compiler. The compiler emits now explicit + instructions for adjusting the stack of values and calling the + cleaning-up code for :keyword:`break`, :keyword:`continue` and + :keyword:`return`. + + Removed opcodes :opcode:`BREAK_LOOP`, :opcode:`CONTINUE_LOOP`, + :opcode:`SETUP_LOOP` and :opcode:`SETUP_EXCEPT`. Added new opcodes + :opcode:`ROT_FOUR`, :opcode:`BEGIN_FINALLY`, :opcode:`CALL_FINALLY` and + :opcode:`POP_FINALLY`. Changed the behavior of :opcode:`END_FINALLY` + and :opcode:`WITH_CLEANUP_START`. + + (Contributed by Mark Shannon, Antoine Pitrou and Serhiy Storchaka in + :issue:`17611`.) + +* Added new opcode :opcode:`END_ASYNC_FOR` for handling exceptions raised + when awaiting a next item in an :keyword:`async for` loop. + (Contributed by Serhiy Storchaka in :issue:`33041`.) + +* The :opcode:`MAP_ADD` now expects the value as the first element in the + stack and the key as the second element. This change was made so the key + is always evaluated before the value in dictionary comprehensions, as + proposed by :pep:`572`. (Contributed by Jörn Heissler in :issue:`35224`.) + + +Demos and Tools +--------------- + +Added a benchmark script for timing various ways to access variables: +``Tools/scripts/var_access_benchmark.py``. +(Contributed by Raymond Hettinger in :issue:`35884`.) + +Here's a summary of performance improvements since Python 3.3: + +.. code-block:: none + + Python version 3.3 3.4 3.5 3.6 3.7 3.8 + -------------- --- --- --- --- --- --- + + Variable and attribute read access: + read_local 4.0 7.1 7.1 5.4 5.1 3.9 + read_nonlocal 5.3 7.1 8.1 5.8 5.4 4.4 + read_global 13.3 15.5 19.0 14.3 13.6 7.6 + read_builtin 20.0 21.1 21.6 18.5 19.0 7.5 + read_classvar_from_class 20.5 25.6 26.5 20.7 19.5 18.4 + read_classvar_from_instance 18.5 22.8 23.5 18.8 17.1 16.4 + read_instancevar 26.8 32.4 33.1 28.0 26.3 25.4 + read_instancevar_slots 23.7 27.8 31.3 20.8 20.8 20.2 + read_namedtuple 68.5 73.8 57.5 45.0 46.8 18.4 + read_boundmethod 29.8 37.6 37.9 29.6 26.9 27.7 + + Variable and attribute write access: + write_local 4.6 8.7 9.3 5.5 5.3 4.3 + write_nonlocal 7.3 10.5 11.1 5.6 5.5 4.7 + write_global 15.9 19.7 21.2 18.0 18.0 15.8 + write_classvar 81.9 92.9 96.0 104.6 102.1 39.2 + write_instancevar 36.4 44.6 45.8 40.0 38.9 35.5 + write_instancevar_slots 28.7 35.6 36.1 27.3 26.6 25.7 + + Data structure read access: + read_list 19.2 24.2 24.5 20.8 20.8 19.0 + read_deque 19.9 24.7 25.5 20.2 20.6 19.8 + read_dict 19.7 24.3 25.7 22.3 23.0 21.0 + read_strdict 17.9 22.6 24.3 19.5 21.2 18.9 + + Data structure write access: + write_list 21.2 27.1 28.5 22.5 21.6 20.0 + write_deque 23.8 28.7 30.1 22.7 21.8 23.5 + write_dict 25.9 31.4 33.3 29.3 29.2 24.7 + write_strdict 22.9 28.4 29.9 27.5 25.2 23.1 + + Stack (or queue) operations: + list_append_pop 144.2 93.4 112.7 75.4 74.2 50.8 + deque_append_pop 30.4 43.5 57.0 49.4 49.2 42.5 + deque_append_popleft 30.8 43.7 57.3 49.7 49.7 42.8 + + Timing loop: + loop_overhead 0.3 0.5 0.6 0.4 0.3 0.3 + + (Measured from the macOS 64-bit builds found at python.org) + +Notable changes in Python 3.8.1 +=============================== + +Due to significant security concerns, the *reuse_address* parameter of +:meth:`asyncio.loop.create_datagram_endpoint` is no longer supported. This is +because of the behavior of the socket option ``SO_REUSEADDR`` in UDP. For more +details, see the documentation for ``loop.create_datagram_endpoint()``. +(Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in +:issue:`37228`.) diff --git a/Doc/whatsnew/3.9.rst.bak b/Doc/whatsnew/3.9.rst.bak new file mode 100644 index 00000000000000..6e080c7033c7ee --- /dev/null +++ b/Doc/whatsnew/3.9.rst.bak @@ -0,0 +1,540 @@ +**************************** + What's New In Python 3.9 +**************************** + +:Release: |release| +:Date: |today| + +.. Rules for maintenance: + + * Anyone can add text to this document. Do not spend very much time + on the wording of your changes, because your text will probably + get rewritten to some degree. + + * The maintainer will go through Misc/NEWS periodically and add + changes; it's therefore more important to add your changes to + Misc/NEWS than to this file. + + * This is not a complete list of every single change; completeness + is the purpose of Misc/NEWS. Some changes I consider too small + or esoteric to include. If such a change is added to the text, + I'll just remove it. (This is another reason you shouldn't spend + too much time on writing your addition.) + + * If you want to draw your new text to the attention of the + maintainer, add 'XXX' to the beginning of the paragraph or + section. + + * It's OK to just add a fragmentary note about a change. For + example: "XXX Describe the transmogrify() function added to the + socket module." The maintainer will research the change and + write the necessary text. + + * You can comment out your additions if you like, but it's not + necessary (especially when a final release is some months away). + + * Credit the author of a patch or bugfix. Just the name is + sufficient; the e-mail address isn't necessary. + + * It's helpful to add the bug/patch number as a comment: + + XXX Describe the transmogrify() function added to the socket + module. + (Contributed by P.Y. Developer in :issue:`12345`.) + + This saves the maintainer the effort of going through the Mercurial log + when researching a change. + +This article explains the new features in Python 3.9, compared to 3.8. + +For full details, see the :ref:`changelog `. + +.. note:: + + Prerelease users should be aware that this document is currently in draft + form. It will be updated substantially as Python 3.9 moves towards release, + so it's worth checking back even after reading earlier versions. + + +Summary -- Release highlights +============================= + +.. This section singles out the most important changes in Python 3.9. + Brevity is key. + + +.. PEP-sized items next. + + + +New Features +============ + + + +Other Language Changes +====================== + +* :func:`__import__` now raises :exc:`ImportError` instead of + :exc:`ValueError`, which used to occur when a relative import went past + its top-level package. + (Contributed by Ngalim Siregar in :issue:`37444`.) + + +* Python now gets the absolute path of the script filename specified on + the command line (ex: ``python3 script.py``): the ``__file__`` attribute of + the :mod:`__main__` module and ``sys.path[0]`` become an + absolute path, rather than a relative path. These paths now remain valid + after the current directory is changed by :func:`os.chdir`. As a side effect, + a traceback also displays the absolute path for :mod:`__main__` module frames + in this case. + (Contributed by Victor Stinner in :issue:`20443`.) + +* In the :ref:`Python Development Mode ` and in debug build, the + *encoding* and *errors* arguments are now checked for string encoding and + decoding operations. Examples: :func:`open`, :meth:`str.encode` and + :meth:`bytes.decode`. + + By default, for best performance, the *errors* argument is only checked at + the first encoding/decoding error and the *encoding* argument is sometimes + ignored for empty strings. + (Contributed by Victor Stinner in :issue:`37388`.) + +* ``"".replace("", s, n)`` now returns ``s`` instead of an empty string for + all non-zero ``n``. It is now consistent with ``"".replace("", s)``. + There are similar changes for :class:`bytes` and :class:`bytearray` objects. + (Contributed by Serhiy Storchaka in :issue:`28029`.) + + +New Modules +=========== + +* None yet. + + +Improved Modules +================ + +ast +--- + +Added the *indent* option to :func:`~ast.dump` which allows it to produce a +multiline indented output. +(Contributed by Serhiy Storchaka in :issue:`37995`.) + +Added :func:`ast.unparse` as a function in the :mod:`ast` module that can +be used to unparse an :class:`ast.AST` object and produce a string with code +that would produce an equivalent :class:`ast.AST` object when parsed. +(Contributed by Pablo Galindo and Batuhan Taskaya in :issue:`38870`.) + +asyncio +------- + +Due to significant security concerns, the *reuse_address* parameter of +:meth:`asyncio.loop.create_datagram_endpoint` is no longer supported. This is +because of the behavior of the socket option ``SO_REUSEADDR`` in UDP. For more +details, see the documentation for ``loop.create_datagram_endpoint()``. +(Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in +:issue:`37228`.) + +Added a new :term:`coroutine` :meth:`~asyncio.loop.shutdown_default_executor` +that schedules a shutdown for the default executor that waits on the +:class:`~concurrent.futures.ThreadPoolExecutor` to finish closing. Also, +:func:`asyncio.run` has been updated to use the new :term:`coroutine`. +(Contributed by Kyle Stanley in :issue:`34037`.) + +Added :class:`asyncio.PidfdChildWatcher`, a Linux-specific child watcher +implementation that polls process file descriptors. (:issue:`38692`) + +concurrent.futures +------------------ + +Added a new *cancel_futures* parameter to +:meth:`concurrent.futures.Executor.shutdown` that cancels all pending futures +which have not started running, instead of waiting for them to complete before +shutting down the executor. +(Contributed by Kyle Stanley in :issue:`39349`.) + +curses +------ + +Add :func:`curses.get_escdelay`, :func:`curses.set_escdelay`, +:func:`curses.get_tabsize`, and :func:`curses.set_tabsize` functions. +(Contributed by Anthony Sottile in :issue:`38312`.) + +fcntl +----- + +Added constants :data:`~fcntl.F_OFD_GETLK`, :data:`~fcntl.F_OFD_SETLK` +and :data:`~fcntl.F_OFD_SETLKW`. +(Contributed by Dong-hee Na in :issue:`38602`.) + +ftplib +------- + +:class:`~ftplib.FTP` and :class:`~ftplib.FTP_TLS` now raise a :class:`ValueError` +if the given timeout for their constructor is zero to prevent the creation of +a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) + +functools +--------- + +Add the :class:`functools.TopologicalSorter` class to offer functionality to perform +topological sorting of graphs. (Contributed by Pablo Galindo, Tim Peters and Larry +Hastings in :issue:`17005`.) + +gc +-- + +When the garbage collector makes a collection in which some objects resurrect +(they are reachable from outside the isolated cycles after the finalizers have +been executed), do not block the collection of all objects that are still +unreachable. (Contributed by Pablo Galindo and Tim Peters in :issue:`38379`.) + +Added a new function :func:`gc.is_finalized` to check if an object has been +finalized by the garbage collector. (Contributed by Pablo Galindo in +:issue:`39322`.) + +imaplib +------- + +:class:`~imaplib.IMAP4` and :class:`~imaplib.IMAP4_SSL` now have +an optional *timeout* parameter for their constructors. +Also, the :meth:`~imaplib.IMAP4.open` method now has an optional *timeout* parameter +with this change. The overridden methods of :class:`~imaplib.IMAP4_SSL` and +:class:`~imaplib.IMAP4_stream` were applied to this change. +(Contributed by Dong-hee Na in :issue:`38615`.) + +math +---- + +Add :func:`math.nextafter`: return the next floating-point value after *x* +towards *y*. +(Contributed by Victor Stinner in :issue:`39288`.) + +Add :func:`math.ulp`: return the value of the least significant bit +of a float. +(Contributed by Victor Stinner in :issue:`39310`.) + +nntplib +------- + +:class:`~nntplib.NNTP` and :class:`~nntplib.NNTP_SSL` now raise a :class:`ValueError` +if the given timeout for their constructor is zero to prevent the creation of +a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) + +os +-- + +Added :data:`~os.CLD_KILLED` and :data:`~os.CLD_STOPPED` for :attr:`si_code`. +(Contributed by Dong-hee Na in :issue:`38493`.) + +Exposed the Linux-specific :func:`os.pidfd_open` (:issue:`38692`) and +:data:`os.P_PIDFD` (:issue:`38713`) for process management with file +descriptors. + +The :func:`os.unsetenv` function is now also available on Windows. +(Contributed by Victor Stinner in :issue:`39413`.) + +The :func:`os.putenv` and :func:`os.unsetenv` functions are now always +available. +(Contributed by Victor Stinner in :issue:`39395`.) + +poplib +------ + +:class:`~poplib.POP3` and :class:`~poplib.POP3_SSL` now raise a :class:`ValueError` +if the given timeout for their constructor is zero to prevent the creation of +a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) + +threading +--------- + +In a subinterpreter, spawning a daemon thread now raises a :exc:`RuntimeError`. Daemon +threads were never supported in subinterpreters. Previously, the subinterpreter +finalization crashed with a Python fatal error if a daemon thread was still +running. +(Contributed by Victor Stinner in :issue:`37266`.) + +venv +---- + +The activation scripts provided by :mod:`venv` now all specify their prompt +customization consistently by always using the value specified by +``__VENV_PROMPT__``. Previously some scripts unconditionally used +``__VENV_PROMPT__``, others only if it happened to be set (which was the default +case), and one used ``__VENV_NAME__`` instead. +(Contributed by Brett Cannon in :issue:`37663`.) + +pathlib +------- + +Added :meth:`pathlib.Path.readlink()` which acts similarly to +:func:`os.readlink`. +(Contributed by Girts Folkmanis in :issue:`30618`) + +pprint +------ + +:mod:`pprint` can now pretty-print :class:`types.SimpleNamespace`. +(Contributed by Carl Bordum Hansen in :issue:`37376`.) + +importlib +--------- + +To improve consistency with import statements, :func:`importlib.util.resolve_name` +now raises :exc:`ImportError` instead of :exc:`ValueError` for invalid relative +import attempts. +(Contributed by Ngalim Siregar in :issue:`37444`.) + +smtplib +------- + +:class:`~smtplib.SMTP` and :class:`~smtplib.SMTP_SSL` now raise a :class:`ValueError` +if the given timeout for their constructor is zero to prevent the creation of +a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) + +:class:`~smtplib.LMTP` constructor now has an optional *timeout* parameter. +(Contributed by Dong-hee Na in :issue:`39329`.) + +signal +------ + +Exposed the Linux-specific :func:`signal.pidfd_send_signal` for sending to +signals to a process using a file descriptor instead of a pid. (:issue:`38712`) + + +Optimizations +============= + + +Build and C API Changes +======================= + +* Provide :c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall` + as regular functions for the limited API. Previously, there were defined as + macros, but these macros didn't work with the limited API which cannot access + ``PyThreadState.recursion_depth`` field. Remove ``_Py_CheckRecursionLimit`` + from the stable ABI. + (Contributed by Victor Stinner in :issue:`38644`.) + +* Add a new public :c:func:`PyObject_CallNoArgs` function to the C API, which + calls a callable Python object without any arguments. It is the most efficient + way to call a callable Python object without any argument. + (Contributed by Victor Stinner in :issue:`37194`.) + +* The global variable :c:data:`PyStructSequence_UnnamedField` is now a constant + and refers to a constant string. + (Contributed by Serhiy Storchaka in :issue:`38650`.) + +* Exclude ``PyFPE_START_PROTECT()`` and ``PyFPE_END_PROTECT()`` macros of + ``pyfpe.h`` from ``Py_LIMITED_API`` (stable API). + (Contributed by Victor Stinner in :issue:`38835`.) + +* Remove ``PyMethod_ClearFreeList()`` and ``PyCFunction_ClearFreeList()`` + functions: the free lists of bound method objects have been removed. + (Contributed by Inada Naoki and Victor Stinner in :issue:`37340`.) + +* Remove ``PyUnicode_ClearFreeList()`` function: the Unicode free list has been + removed in Python 3.3. + (Contributed by Victor Stinner in :issue:`38896`.) + +* The ``tp_print`` slot of :ref:`PyTypeObject ` has been removed. + It was used for printing objects to files in Python 2.7 and before. Since + Python 3.0, it has been ignored and unused. + (Contributed by Jeroen Demeyer in :issue:`36974`.) + +* On non-Windows platforms, the :c:func:`setenv` and :c:func:`unsetenv` + functions are now required to build Python. + (Contributed by Victor Stinner in :issue:`39395`.) + +* The ``COUNT_ALLOCS`` special build macro has been removed. + (Contributed by Victor Stinner in :issue:`39489`.) + + +Deprecated +========== + +* Currently :func:`math.factorial` accepts :class:`float` instances with + non-negative integer values (like ``5.0``). It raises a :exc:`ValueError` + for non-integral and negative floats. It is now deprecated. In future + Python versions it will raise a :exc:`TypeError` for all floats. + (Contributed by Serhiy Storchaka in :issue:`37315`.) + +* The :mod:`parser` module is deprecated and will be removed in future versions + of Python. For the majority of use cases, users can leverage the Abstract Syntax + Tree (AST) generation and compilation stage, using the :mod:`ast` module. + +* The :mod:`random` module currently accepts any hashable type as a + possible seed value. Unfortunately, some of those types are not + guaranteed to have a deterministic hash value. After Python 3.9, + the module will restrict its seeds to :const:`None`, :class:`int`, + :class:`float`, :class:`str`, :class:`bytes`, and :class:`bytearray`. + +* Opening the :class:`~gzip.GzipFile` file for writing without specifying + the *mode* argument is deprecated. In future Python versions it will always + be opened for reading by default. Specify the *mode* argument for opening + it for writing and silencing a warning. + (Contributed by Serhiy Storchaka in :issue:`28286`.) + +* Deprecated the ``split()`` method of :class:`_tkinter.TkappType` in + favour of the ``splitlist()`` method which has more consistent and + predicable behavior. + (Contributed by Serhiy Storchaka in :issue:`38371`.) + +* The explicit passing of coroutine objects to :func:`asyncio.wait` has been + deprecated and will be removed in version 3.11. + (Contributed by Yury Selivanov and Kyle Stanley in :issue:`34790`.) + +* binhex4 and hexbin4 standards are now deprecated. The :`binhex` module + and the following :mod:`binascii` functions are now deprecated: + + * :func:`~binascii.b2a_hqx`, :func:`~binascii.a2b_hqx` + * :func:`~binascii.rlecode_hqx`, :func:`~binascii.rledecode_hqx` + + (Contributed by Victor Stinner in :issue:`39353`.) + + +Removed +======= + +* The erroneous version at :data:`unittest.mock.__version__` has been removed. + +* :class:`nntplib.NNTP`: ``xpath()`` and ``xgtitle()`` methods have been removed. + These methods are deprecated since Python 3.3. Generally, these extensions + are not supported or not enabled by NNTP server administrators. + For ``xgtitle()``, please use :meth:`nntplib.NNTP.descriptions` or + :meth:`nntplib.NNTP.description` instead. + (Contributed by Dong-hee Na in :issue:`39366`.) + +* :class:`array.array`: ``tostring()`` and ``fromstring()`` methods have been + removed. They were aliases to ``tobytes()`` and ``frombytes()``, deprecated + since Python 3.2. + (Contributed by Victor Stinner in :issue:`38916`.) + +* The abstract base classes in :mod:`collections.abc` no longer are + exposed in the regular :mod:`collections` module. This will help + create a clearer distinction between the concrete classes and the abstract + base classes. + +* The undocumented ``sys.callstats()`` function has been removed. Since Python + 3.7, it was deprecated and always returned :const:`None`. It required a special + build option ``CALL_PROFILE`` which was already removed in Python 3.7. + (Contributed by Victor Stinner in :issue:`37414`.) + +* The ``sys.getcheckinterval()`` and ``sys.setcheckinterval()`` functions have + been removed. They were deprecated since Python 3.2. Use + :func:`sys.getswitchinterval` and :func:`sys.setswitchinterval` instead. + (Contributed by Victor Stinner in :issue:`37392`.) + +* The C function ``PyImport_Cleanup()`` has been removed. It was documented as: + "Empty the module table. For internal use only." + (Contributed by Victor Stinner in :issue:`36710`.) + +* ``_dummy_thread`` and ``dummy_threading`` modules have been removed. These + modules were deprecated since Python 3.7 which requires threading support. + (Contributed by Victor Stinner in :issue:`37312`.) + +* ``aifc.openfp()`` alias to ``aifc.open()``, ``sunau.openfp()`` alias to + ``sunau.open()``, and ``wave.openfp()`` alias to :func:`wave.open()` have been + removed. They were deprecated since Python 3.7. + (Contributed by Victor Stinner in :issue:`37320`.) + +* The :meth:`~threading.Thread.isAlive()` method of :class:`threading.Thread` + has been removed. It was deprecated since Python 3.8. + Use :meth:`~threading.Thread.is_alive()` instead. + (Contributed by Dong-hee Na in :issue:`37804`.) + +* Methods ``getchildren()`` and ``getiterator()`` in the + :mod:`~xml.etree.ElementTree` module have been removed. They were + deprecated in Python 3.2. Use functions :func:`list` and :func:`iter` + instead. The ``xml.etree.cElementTree`` module has been removed. + (Contributed by Serhiy Storchaka in :issue:`36543`.) + +* The old :mod:`plistlib` API has been removed, it was deprecated since Python + 3.4. Use the :func:`~plistlib.load`, :func:`~plistlib.loads`, :func:`~plistlib.dump`, and + :func:`~plistlib.dumps` functions. Additionally, the *use_builtin_types* parameter was + removed, standard :class:`bytes` objects are always used instead. + (Contributed by Jon Janzen in :issue:`36409`.) + +* The C function ``PyThreadState_DeleteCurrent()`` has been removed. It was not documented. + (Contributed by Joannah Nanjekye in :issue:`37878`.) + +* The C function ``PyGen_NeedsFinalizing`` has been removed. It was not + documented, tested, or used anywhere within CPython after the implementation + of :pep:`442`. Patch by Joannah Nanjekye. + (Contributed by Joannah Nanjekye in :issue:`15088`) + +* ``base64.encodestring()`` and ``base64.decodestring()``, aliases deprecated + since Python 3.1, have been removed: use :func:`base64.encodebytes` and + :func:`base64.decodebytes` instead. + (Contributed by Victor Stinner in :issue:`39351`.) + +* ``fractions.gcd()`` function has been removed, it was deprecated since Python + 3.5 (:issue:`22486`): use :func:`math.gcd` instead. + (Contributed by Victor Stinner in :issue:`39350`.) + +* The *buffering* parameter of :class:`bz2.BZ2File` has been removed. Since + Python 3.0, it was ignored and using it emitted a :exc:`DeprecationWarning`. + Pass an open file object to control how the file is opened. + (Contributed by Victor Stinner in :issue:`39357`.) + +* The *encoding* parameter of :func:`json.loads` has been removed. + As of Python 3.1, it was deprecated and ignored; using it has emitted a + :exc:`DeprecationWarning` since Python 3.8. + (Contributed by Inada Naoki in :issue:`39377`) + +* ``with (await asyncio.lock):`` and ``with (yield from asyncio.lock):`` statements are + not longer supported, use ``async with lock`` instead. The same is correct for + ``asyncio.Condition`` and ``asyncio.Semaphore``. + (Contributed by Andrew Svetlov in :issue:`34793`.) + +* The :func:`sys.getcounts` function, the ``-X showalloccount`` command line + option and the ``show_alloc_count`` field of the C structure + :c:type:`PyConfig` have been removed. They required a special Python build by + defining ``COUNT_ALLOCS`` macro. + (Contributed by Victor Stinner in :issue:`39489`.) + + +Porting to Python 3.9 +===================== + +This section lists previously described changes and other bugfixes +that may require changes to your code. + + +Changes in the Python API +------------------------- + +* :func:`open`, :func:`io.open`, :func:`codecs.open` and + :class:`fileinput.FileInput` no longer accept ``'U'`` ("universal newline") + in the file mode. This flag was deprecated since Python 3.3. In Python 3, the + "universal newline" is used by default when a file is open in text mode. The + :ref:`newline parameter ` of :func:`open` controls + how universal newlines works. + (Contributed by Victor Stinner in :issue:`37330`.) + +* :func:`__import__` and :func:`importlib.util.resolve_name` now raise + :exc:`ImportError` where it previously raised :exc:`ValueError`. Callers + catching the specific exception type and supporting both Python 3.9 and + earlier versions will need to catch both using ``except (ImportError, ValueError):``. + +* The :mod:`venv` activation scripts no longer special-case when + ``__VENV_PROMPT__`` is set to ``""``. + +* The :meth:`select.epoll.unregister` method no longer ignores the + :data:`~errno.EBADF` error. + (Contributed by Victor Stinner in :issue:`39239`.) + +* The *compresslevel* parameter of :class:`bz2.BZ2File` became keyword-only, + since the *buffering* parameter has been removed. + (Contributed by Victor Stinner in :issue:`39357`.) + + +CPython bytecode changes +------------------------ + +* The :opcode:`LOAD_ASSERTION_ERROR` opcode was added for handling the + :keyword:`assert` statement. Previously, the assert statement would not work + correctly if the :exc:`AssertionError` exception was being shadowed. + (Contributed by Zackery Spytz in :issue:`34880`.) diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 39f6a0b5fbd644..8870f4d2d2219c 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12779,7 +12779,7 @@ unicode_cutprefix_impl(PyObject* self, PyObject* prefix) } if (match) { return PyUnicode_Substring(self, PyUnicode_GET_LENGTH(prefix), - PyUnicode_GET_LENGTH(self)); + PyUnicode_GET_LENGTH(self)); } return unicode_result_unchanged(self); } @@ -12806,7 +12806,7 @@ unicode_cutsuffix_impl(PyObject* self, PyObject* suffix) } if (match) { return PyUnicode_Substring(self, 0, PyUnicode_GET_LENGTH(self) - - PyUnicode_GET_LENGTH(suffix)); + - PyUnicode_GET_LENGTH(suffix)); } return unicode_result_unchanged(self); } From a7a1bc84dd452d68e1f2d780a571d5f44e41f8d2 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 13:52:47 -0400 Subject: [PATCH 03/35] Revert "pep 7: lining up argumenets" This reverts commit 3adb9fadeba51d43f17e7d1cdae16c6589ba2656. --- CppProperties.json | 21 - Doc/c-api/call.rst.bak | 411 --- Doc/c-api/structures.rst.bak | 401 --- Doc/c-api/type.rst.bak | 209 -- Doc/c-api/typeobj.rst.bak | 2565 ----------------- Doc/library/fractions.rst.bak | 178 -- Doc/library/os.rst.bak | 4513 ------------------------------ Doc/library/pty.rst.bak | 114 - Doc/library/stdtypes.rst.bak | 4885 --------------------------------- Doc/library/sys.rst.bak | 1652 ----------- Doc/library/typing.rst.bak | 1374 ---------- Doc/tutorial/errors.rst.bak | 474 ---- Doc/whatsnew/3.8.rst.bak | 2216 --------------- Doc/whatsnew/3.9.rst.bak | 540 ---- Objects/unicodeobject.c | 4 +- 15 files changed, 2 insertions(+), 19555 deletions(-) delete mode 100644 CppProperties.json delete mode 100644 Doc/c-api/call.rst.bak delete mode 100644 Doc/c-api/structures.rst.bak delete mode 100644 Doc/c-api/type.rst.bak delete mode 100644 Doc/c-api/typeobj.rst.bak delete mode 100644 Doc/library/fractions.rst.bak delete mode 100644 Doc/library/os.rst.bak delete mode 100644 Doc/library/pty.rst.bak delete mode 100644 Doc/library/stdtypes.rst.bak delete mode 100644 Doc/library/sys.rst.bak delete mode 100644 Doc/library/typing.rst.bak delete mode 100644 Doc/tutorial/errors.rst.bak delete mode 100644 Doc/whatsnew/3.8.rst.bak delete mode 100644 Doc/whatsnew/3.9.rst.bak diff --git a/CppProperties.json b/CppProperties.json deleted file mode 100644 index 659bf4ea9068f8..00000000000000 --- a/CppProperties.json +++ /dev/null @@ -1,21 +0,0 @@ -{ - "configurations": [ - { - "inheritEnvironments": [ - "msvc_x86" - ], - "name": "x86-Debug", - "includePath": [ - "${env.INCLUDE}", - "${workspaceRoot}\\**" - ], - "defines": [ - "WIN32", - "_DEBUG", - "UNICODE", - "_UNICODE" - ], - "intelliSenseMode": "windows-msvc-x86" - } - ] -} \ No newline at end of file diff --git a/Doc/c-api/call.rst.bak b/Doc/c-api/call.rst.bak deleted file mode 100644 index 0833531b1d5ee1..00000000000000 --- a/Doc/c-api/call.rst.bak +++ /dev/null @@ -1,411 +0,0 @@ -.. highlight:: c - -.. _call: - -Call Protocol -============= - -CPython supports two different calling protocols: -*tp_call* and vectorcall. - -The *tp_call* Protocol ----------------------- - -Instances of classes that set :c:member:`~PyTypeObject.tp_call` are callable. -The signature of the slot is:: - - PyObject *tp_call(PyObject *callable, PyObject *args, PyObject *kwargs); - -A call is made using a tuple for the positional arguments -and a dict for the keyword arguments, similarly to -``callable(*args, **kwargs)`` in Python code. -*args* must be non-NULL (use an empty tuple if there are no arguments) -but *kwargs* may be *NULL* if there are no keyword arguments. - -This convention is not only used by *tp_call*: -:c:member:`~PyTypeObject.tp_new` and :c:member:`~PyTypeObject.tp_init` -also pass arguments this way. - -To call an object, use :c:func:`PyObject_Call` or other -:ref:`call API `. - - -.. _vectorcall: - -The Vectorcall Protocol ------------------------ - -.. versionadded:: 3.8 - -The vectorcall protocol was introduced in :pep:`590` as an additional protocol -for making calls more efficient. - -.. warning:: - - The vectorcall API is provisional and expected to become public in - Python 3.9, with a different names and, possibly, changed semantics. - If you use the it, plan for updating your code for Python 3.9. - -As rule of thumb, CPython will prefer the vectorcall for internal calls -if the callable supports it. However, this is not a hard rule. -Additionally, some third-party extensions use *tp_call* directly -(rather than using :c:func:`PyObject_Call`). -Therefore, a class supporting vectorcall must also implement -:c:member:`~PyTypeObject.tp_call`. -Moreover, the callable must behave the same -regardless of which protocol is used. -The recommended way to achieve this is by setting -:c:member:`~PyTypeObject.tp_call` to :c:func:`PyVectorcall_Call`. -This bears repeating: - -.. warning:: - - A class supporting vectorcall **must** also implement - :c:member:`~PyTypeObject.tp_call` with the same semantics. - -A class should not implement vectorcall if that would be slower -than *tp_call*. For example, if the callee needs to convert -the arguments to an args tuple and kwargs dict anyway, then there is no point -in implementing vectorcall. - -Classes can implement the vectorcall protocol by enabling the -:const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag and setting -:c:member:`~PyTypeObject.tp_vectorcall_offset` to the offset inside the -object structure where a *vectorcallfunc* appears. -This is a pointer to a function with the following signature: - -.. c:type:: PyObject *(*vectorcallfunc)(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) - -- *callable* is the object being called. -- *args* is a C array consisting of the positional arguments followed by the - values of the keyword arguments. - This can be *NULL* if there are no arguments. -- *nargsf* is the number of positional arguments plus possibly the - :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` flag. - To get the actual number of positional arguments from *nargsf*, - use :c:func:`PyVectorcall_NARGS`. -- *kwnames* is a tuple containing the names of the keyword arguments; - in other words, the keys of the kwargs dict. - These names must be strings (instances of ``str`` or a subclass) - and they must be unique. - If there are no keyword arguments, then *kwnames* can instead be *NULL*. - -.. c:var:: PY_VECTORCALL_ARGUMENTS_OFFSET - - If this flag is set in a vectorcall *nargsf* argument, the callee is allowed - to temporarily change ``args[-1]``. In other words, *args* points to - argument 1 (not 0) in the allocated vector. - The callee must restore the value of ``args[-1]`` before returning. - - For :c:func:`_PyObject_VectorcallMethod`, this flag means instead that - ``args[0]`` may be changed. - - Whenever they can do so cheaply (without additional allocation), callers - are encouraged to use :const:`PY_VECTORCALL_ARGUMENTS_OFFSET`. - Doing so will allow callables such as bound methods to make their onward - calls (which include a prepended *self* argument) very efficiently. - -To call an object that implements vectorcall, use a :ref:`call API ` -function as with any other callable. -:c:func:`_PyObject_Vectorcall` will usually be most efficient. - - -Recursion Control -................. - -When using *tp_call*, callees do not need to worry about -:ref:`recursion `: CPython uses -:c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall` -for calls made using *tp_call*. - -For efficiency, this is not the case for calls done using vectorcall: -the callee should use *Py_EnterRecursiveCall* and *Py_LeaveRecursiveCall* -if needed. - - -Vectorcall Support API -...................... - -.. c:function:: Py_ssize_t PyVectorcall_NARGS(size_t nargsf) - - Given a vectorcall *nargsf* argument, return the actual number of - arguments. - Currently equivalent to:: - - (Py_ssize_t)(nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET) - - However, the function ``PyVectorcall_NARGS`` should be used to allow - for future extensions. - - .. versionadded:: 3.8 - -.. c:function:: vectorcallfunc _PyVectorcall_Function(PyObject *op) - - If *op* does not support the vectorcall protocol (either because the type - does not or because the specific instance does not), return *NULL*. - Otherwise, return the vectorcall function pointer stored in *op*. - This function never raises an exception. - - This is mostly useful to check whether or not *op* supports vectorcall, - which can be done by checking ``_PyVectorcall_Function(op) != NULL``. - - .. versionadded:: 3.8 - -.. c:function:: PyObject* PyVectorcall_Call(PyObject *callable, PyObject *tuple, PyObject *dict) - - Call *callable*'s :c:type:`vectorcallfunc` with positional and keyword - arguments given in a tuple and dict, respectively. - - This is a specialized function, intended to be put in the - :c:member:`~PyTypeObject.tp_call` slot or be used in an implementation of ``tp_call``. - It does not check the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag - and it does not fall back to ``tp_call``. - - .. versionadded:: 3.8 - - -.. _capi-call: - -Object Calling API ------------------- - -Various functions are available for calling a Python object. -Each converts its arguments to a convention supported by the called object – -either *tp_call* or vectorcall. -In order to do as litle conversion as possible, pick one that best fits -the format of data you have available. - -The following table summarizes the available functions; -please see individual documentation for details. - -+------------------------------------------+------------------+--------------------+---------------+ -| Function | callable | args | kwargs | -+==========================================+==================+====================+===============+ -| :c:func:`PyObject_Call` | ``PyObject *`` | tuple | dict/``NULL`` | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallNoArgs` | ``PyObject *`` | --- | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_CallOneArg` | ``PyObject *`` | 1 object | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallObject` | ``PyObject *`` | tuple/``NULL`` | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallFunction` | ``PyObject *`` | format | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallMethod` | obj + ``char*`` | format | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallFunctionObjArgs` | ``PyObject *`` | variadic | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`PyObject_CallMethodObjArgs` | obj + name | variadic | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_CallMethodNoArgs` | obj + name | --- | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_CallMethodOneArg` | obj + name | 1 object | --- | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_Vectorcall` | ``PyObject *`` | vectorcall | vectorcall | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_FastCallDict` | ``PyObject *`` | vectorcall | dict/``NULL`` | -+------------------------------------------+------------------+--------------------+---------------+ -| :c:func:`_PyObject_VectorcallMethod` | arg + name | vectorcall | vectorcall | -+------------------------------------------+------------------+--------------------+---------------+ - - -.. c:function:: PyObject* PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs) - - Call a callable Python object *callable*, with arguments given by the - tuple *args*, and named arguments given by the dictionary *kwargs*. - - *args* must not be *NULL*; use an empty tuple if no arguments are needed. - If no named arguments are needed, *kwargs* can be *NULL*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - This is the equivalent of the Python expression: - ``callable(*args, **kwargs)``. - - -.. c:function:: PyObject* PyObject_CallNoArgs(PyObject *callable) - - Call a callable Python object *callable* without any arguments. It is the - most efficient way to call a callable Python object without any argument. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. versionadded:: 3.9 - - -.. c:function:: PyObject* _PyObject_CallOneArg(PyObject *callable, PyObject *arg) - - Call a callable Python object *callable* with exactly 1 positional argument - *arg* and no keyword arguments. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. versionadded:: 3.9 - - -.. c:function:: PyObject* PyObject_CallObject(PyObject *callable, PyObject *args) - - Call a callable Python object *callable*, with arguments given by the - tuple *args*. If no arguments are needed, then *args* can be *NULL*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - This is the equivalent of the Python expression: ``callable(*args)``. - - -.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...) - - Call a callable Python object *callable*, with a variable number of C arguments. - The C arguments are described using a :c:func:`Py_BuildValue` style format - string. The format can be *NULL*, indicating that no arguments are provided. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - This is the equivalent of the Python expression: ``callable(*args)``. - - Note that if you only pass :c:type:`PyObject \*` args, - :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. - - .. versionchanged:: 3.4 - The type of *format* was changed from ``char *``. - - -.. c:function:: PyObject* PyObject_CallMethod(PyObject *obj, const char *name, const char *format, ...) - - Call the method named *name* of object *obj* with a variable number of C - arguments. The C arguments are described by a :c:func:`Py_BuildValue` format - string that should produce a tuple. - - The format can be *NULL*, indicating that no arguments are provided. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - This is the equivalent of the Python expression: - ``obj.name(arg1, arg2, ...)``. - - Note that if you only pass :c:type:`PyObject \*` args, - :c:func:`PyObject_CallMethodObjArgs` is a faster alternative. - - .. versionchanged:: 3.4 - The types of *name* and *format* were changed from ``char *``. - - -.. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL) - - Call a callable Python object *callable*, with a variable number of - :c:type:`PyObject \*` arguments. The arguments are provided as a variable number - of parameters followed by *NULL*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - This is the equivalent of the Python expression: - ``callable(arg1, arg2, ...)``. - - -.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *obj, PyObject *name, ..., NULL) - - Call a method of the Python object *obj*, where the name of the method is given as a - Python string object in *name*. It is called with a variable number of - :c:type:`PyObject \*` arguments. The arguments are provided as a variable number - of parameters followed by *NULL*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - -.. c:function:: PyObject* _PyObject_CallMethodNoArgs(PyObject *obj, PyObject *name) - - Call a method of the Python object *obj* without arguments, - where the name of the method is given as a Python string object in *name*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. versionadded:: 3.9 - - -.. c:function:: PyObject* _PyObject_CallMethodOneArg(PyObject *obj, PyObject *name, PyObject *arg) - - Call a method of the Python object *obj* with a single positional argument - *arg*, where the name of the method is given as a Python string object in - *name*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. versionadded:: 3.9 - - -.. c:function:: PyObject* _PyObject_Vectorcall(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwnames) - - Call a callable Python object *callable*. - The arguments are the same as for :c:type:`vectorcallfunc`. - If *callable* supports vectorcall_, this directly calls - the vectorcall function stored in *callable*. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. note:: - - This function is provisional and expected to become public in Python 3.9, - with a different name and, possibly, changed semantics. - If you use the function, plan for updating your code for Python 3.9. - - .. versionadded:: 3.8 - -.. c:function:: PyObject* _PyObject_FastCallDict(PyObject *callable, PyObject *const *args, size_t nargsf, PyObject *kwdict) - - Call *callable* with positional arguments passed exactly as in the vectorcall_ protocol, - but with keyword arguments passed as a dictionary *kwdict*. - The *args* array contains only the positional arguments. - - Regardless of which protocol is used internally, - a conversion of arguments needs to be done. - Therefore, this function should only be used if the caller - already has a dictionary ready to use for the keyword arguments, - but not a tuple for the positional arguments. - - .. note:: - - This function is provisional and expected to become public in Python 3.9, - with a different name and, possibly, changed semantics. - If you use the function, plan for updating your code for Python 3.9. - - .. versionadded:: 3.8 - -.. c:function:: PyObject* _PyObject_VectorcallMethod(PyObject *name, PyObject *const *args, size_t nargsf, PyObject *kwnames) - - Call a method using the vectorcall calling convention. The name of the method - is given as a Python string *name*. The object whose method is called is - *args[0]*, and the *args* array starting at *args[1]* represents the arguments - of the call. There must be at least one positional argument. - *nargsf* is the number of positional arguments including *args[0]*, - plus :const:`PY_VECTORCALL_ARGUMENTS_OFFSET` if the value of ``args[0]`` may - temporarily be changed. Keyword arguments can be passed just like in - :c:func:`_PyObject_Vectorcall`. - - If the object has the :const:`Py_TPFLAGS_METHOD_DESCRIPTOR` feature, - this will call the unbound method object with the full - *args* vector as arguments. - - Return the result of the call on success, or raise an exception and return - *NULL* on failure. - - .. versionadded:: 3.9 - - -Call Support API ----------------- - -.. c:function:: int PyCallable_Check(PyObject *o) - - Determine if the object *o* is callable. Return ``1`` if the object is callable - and ``0`` otherwise. This function always succeeds. diff --git a/Doc/c-api/structures.rst.bak b/Doc/c-api/structures.rst.bak deleted file mode 100644 index 0c661389021eff..00000000000000 --- a/Doc/c-api/structures.rst.bak +++ /dev/null @@ -1,401 +0,0 @@ -.. highlight:: c - -.. _common-structs: - -Common Object Structures -======================== - -There are a large number of structures which are used in the definition of -object types for Python. This section describes these structures and how they -are used. - - -Base object types and macros ----------------------------- - -All Python objects ultimately share a small number of fields at the beginning -of the object's representation in memory. These are represented by the -:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn, -by the expansions of some macros also used, whether directly or indirectly, in -the definition of all other Python objects. - - -.. c:type:: PyObject - - All object types are extensions of this type. This is a type which - contains the information Python needs to treat a pointer to an object as an - object. In a normal "release" build, it contains only the object's - reference count and a pointer to the corresponding type object. - Nothing is actually declared to be a :c:type:`PyObject`, but every pointer - to a Python object can be cast to a :c:type:`PyObject*`. Access to the - members must be done by using the macros :c:macro:`Py_REFCNT` and - :c:macro:`Py_TYPE`. - - -.. c:type:: PyVarObject - - This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size` - field. This is only used for objects that have some notion of *length*. - This type does not often appear in the Python/C API. - Access to the members must be done by using the macros - :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`. - - -.. c:macro:: PyObject_HEAD - - This is a macro used when declaring new types which represent objects - without a varying length. The PyObject_HEAD macro expands to:: - - PyObject ob_base; - - See documentation of :c:type:`PyObject` above. - - -.. c:macro:: PyObject_VAR_HEAD - - This is a macro used when declaring new types which represent objects - with a length that varies from instance to instance. - The PyObject_VAR_HEAD macro expands to:: - - PyVarObject ob_base; - - See documentation of :c:type:`PyVarObject` above. - - -.. c:macro:: Py_TYPE(o) - - This macro is used to access the :attr:`ob_type` member of a Python object. - It expands to:: - - (((PyObject*)(o))->ob_type) - - -.. c:macro:: Py_REFCNT(o) - - This macro is used to access the :attr:`ob_refcnt` member of a Python - object. - It expands to:: - - (((PyObject*)(o))->ob_refcnt) - - -.. c:macro:: Py_SIZE(o) - - This macro is used to access the :attr:`ob_size` member of a Python object. - It expands to:: - - (((PyVarObject*)(o))->ob_size) - - -.. c:macro:: PyObject_HEAD_INIT(type) - - This is a macro which expands to initialization values for a new - :c:type:`PyObject` type. This macro expands to:: - - _PyObject_EXTRA_INIT - 1, type, - - -.. c:macro:: PyVarObject_HEAD_INIT(type, size) - - This is a macro which expands to initialization values for a new - :c:type:`PyVarObject` type, including the :attr:`ob_size` field. - This macro expands to:: - - _PyObject_EXTRA_INIT - 1, type, size, - - -Implementing functions and methods ----------------------------------- - -.. c:type:: PyCFunction - - Type of the functions used to implement most Python callables in C. - Functions of this type take two :c:type:`PyObject\*` parameters and return - one such value. If the return value is ``NULL``, an exception shall have - been set. If not ``NULL``, the return value is interpreted as the return - value of the function as exposed in Python. The function must return a new - reference. - - -.. c:type:: PyCFunctionWithKeywords - - Type of the functions used to implement Python callables in C - with signature :const:`METH_VARARGS | METH_KEYWORDS`. - - -.. c:type:: _PyCFunctionFast - - Type of the functions used to implement Python callables in C - with signature :const:`METH_FASTCALL`. - - -.. c:type:: _PyCFunctionFastWithKeywords - - Type of the functions used to implement Python callables in C - with signature :const:`METH_FASTCALL | METH_KEYWORDS`. - - -.. c:type:: PyMethodDef - - Structure used to describe a method of an extension type. This structure has - four fields: - - +------------------+---------------+-------------------------------+ - | Field | C Type | Meaning | - +==================+===============+===============================+ - | :attr:`ml_name` | const char \* | name of the method | - +------------------+---------------+-------------------------------+ - | :attr:`ml_meth` | PyCFunction | pointer to the C | - | | | implementation | - +------------------+---------------+-------------------------------+ - | :attr:`ml_flags` | int | flag bits indicating how the | - | | | call should be constructed | - +------------------+---------------+-------------------------------+ - | :attr:`ml_doc` | const char \* | points to the contents of the | - | | | docstring | - +------------------+---------------+-------------------------------+ - -The :attr:`ml_meth` is a C function pointer. The functions may be of different -types, but they always return :c:type:`PyObject\*`. If the function is not of -the :c:type:`PyCFunction`, the compiler will require a cast in the method table. -Even though :c:type:`PyCFunction` defines the first parameter as -:c:type:`PyObject\*`, it is common that the method implementation uses the -specific C type of the *self* object. - -The :attr:`ml_flags` field is a bitfield which can include the following flags. -The individual flags indicate either a calling convention or a binding -convention. - -There are four basic calling conventions for positional arguments -and two of them can be combined with :const:`METH_KEYWORDS` to support -also keyword arguments. So there are a total of 6 calling conventions: - -.. data:: METH_VARARGS - - This is the typical calling convention, where the methods have the type - :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values. - The first one is the *self* object for methods; for module functions, it is - the module object. The second parameter (often called *args*) is a tuple - object representing all arguments. This parameter is typically processed - using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. - - -.. data:: METH_VARARGS | METH_KEYWORDS - - Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. - The function expects three parameters: *self*, *args*, *kwargs* where - *kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` - if there are no keyword arguments. The parameters are typically processed - using :c:func:`PyArg_ParseTupleAndKeywords`. - - -.. data:: METH_FASTCALL - - Fast calling convention supporting only positional arguments. - The methods have the type :c:type:`_PyCFunctionFast`. - The first parameter is *self*, the second parameter is a C array - of :c:type:`PyObject\*` values indicating the arguments and the third - parameter is the number of arguments (the length of the array). - - This is not part of the :ref:`limited API `. - - .. versionadded:: 3.7 - - -.. data:: METH_FASTCALL | METH_KEYWORDS - - Extension of :const:`METH_FASTCALL` supporting also keyword arguments, - with methods of type :c:type:`_PyCFunctionFastWithKeywords`. - Keyword arguments are passed the same way as in the - :ref:`vectorcall protocol `: - there is an additional fourth :c:type:`PyObject\*` parameter - which is a tuple representing the names of the keyword arguments - (which are guaranteed to be strings) - or possibly ``NULL`` if there are no keywords. The values of the keyword - arguments are stored in the *args* array, after the positional arguments. - - This is not part of the :ref:`limited API `. - - .. versionadded:: 3.7 - - -.. data:: METH_NOARGS - - Methods without parameters don't need to check whether arguments are given if - they are listed with the :const:`METH_NOARGS` flag. They need to be of type - :c:type:`PyCFunction`. The first parameter is typically named *self* and will - hold a reference to the module or object instance. In all cases the second - parameter will be ``NULL``. - - -.. data:: METH_O - - Methods with a single object argument can be listed with the :const:`METH_O` - flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. - They have the type :c:type:`PyCFunction`, with the *self* parameter, and a - :c:type:`PyObject\*` parameter representing the single argument. - - -These two constants are not used to indicate the calling convention but the -binding when use with methods of classes. These may not be used for functions -defined for modules. At most one of these flags may be set for any given -method. - - -.. data:: METH_CLASS - - .. index:: builtin: classmethod - - The method will be passed the type object as the first parameter rather - than an instance of the type. This is used to create *class methods*, - similar to what is created when using the :func:`classmethod` built-in - function. - - -.. data:: METH_STATIC - - .. index:: builtin: staticmethod - - The method will be passed ``NULL`` as the first parameter rather than an - instance of the type. This is used to create *static methods*, similar to - what is created when using the :func:`staticmethod` built-in function. - -One other constant controls whether a method is loaded in place of another -definition with the same method name. - - -.. data:: METH_COEXIST - - The method will be loaded in place of existing definitions. Without - *METH_COEXIST*, the default is to skip repeated definitions. Since slot - wrappers are loaded before the method table, the existence of a - *sq_contains* slot, for example, would generate a wrapped method named - :meth:`__contains__` and preclude the loading of a corresponding - PyCFunction with the same name. With the flag defined, the PyCFunction - will be loaded in place of the wrapper object and will co-exist with the - slot. This is helpful because calls to PyCFunctions are optimized more - than wrapper object calls. - - -Accessing attributes of extension types ---------------------------------------- - -.. c:type:: PyMemberDef - - Structure which describes an attribute of a type which corresponds to a C - struct member. Its fields are: - - +------------------+---------------+-------------------------------+ - | Field | C Type | Meaning | - +==================+===============+===============================+ - | :attr:`name` | const char \* | name of the member | - +------------------+---------------+-------------------------------+ - | :attr:`!type` | int | the type of the member in the | - | | | C struct | - +------------------+---------------+-------------------------------+ - | :attr:`offset` | Py_ssize_t | the offset in bytes that the | - | | | member is located on the | - | | | type's object struct | - +------------------+---------------+-------------------------------+ - | :attr:`flags` | int | flag bits indicating if the | - | | | field should be read-only or | - | | | writable | - +------------------+---------------+-------------------------------+ - | :attr:`doc` | const char \* | points to the contents of the | - | | | docstring | - +------------------+---------------+-------------------------------+ - - :attr:`!type` can be one of many ``T_`` macros corresponding to various C - types. When the member is accessed in Python, it will be converted to the - equivalent Python type. - - =============== ================== - Macro name C type - =============== ================== - T_SHORT short - T_INT int - T_LONG long - T_FLOAT float - T_DOUBLE double - T_STRING const char \* - T_OBJECT PyObject \* - T_OBJECT_EX PyObject \* - T_CHAR char - T_BYTE char - T_UBYTE unsigned char - T_UINT unsigned int - T_USHORT unsigned short - T_ULONG unsigned long - T_BOOL char - T_LONGLONG long long - T_ULONGLONG unsigned long long - T_PYSSIZET Py_ssize_t - =============== ================== - - :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that - :c:macro:`T_OBJECT` returns ``None`` if the member is ``NULL`` and - :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use - :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` - handles use of the :keyword:`del` statement on that attribute more correctly - than :c:macro:`T_OBJECT`. - - :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for - read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies - :c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8. - Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` - members can be deleted. (They are set to ``NULL``). - - .. _pymemberdef-offsets: - - Heap allocated types (created using :c:func:`PyType_FromSpec` or similar), - ``PyMemberDef`` may contain definitions for the special members - ``__dictoffset__`` and ``__weaklistoffset__``, corresponding to - :c:member:`~PyTypeObject.tp_dictoffset` and - :c:member:`~PyTypeObject.tp_weaklistoffset` in type objects. - These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example:: - - static PyMemberDef spam_type_members[] = { - {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY}, - {NULL} /* Sentinel */ - }; - -.. c:type:: PyGetSetDef - - Structure to define property-like access for a type. See also description of - the :c:member:`PyTypeObject.tp_getset` slot. - - +-------------+------------------+-----------------------------------+ - | Field | C Type | Meaning | - +=============+==================+===================================+ - | name | const char \* | attribute name | - +-------------+------------------+-----------------------------------+ - | get | getter | C Function to get the attribute | - +-------------+------------------+-----------------------------------+ - | set | setter | optional C function to set or | - | | | delete the attribute, if omitted | - | | | the attribute is readonly | - +-------------+------------------+-----------------------------------+ - | doc | const char \* | optional docstring | - +-------------+------------------+-----------------------------------+ - | closure | void \* | optional function pointer, | - | | | providing additional data for | - | | | getter and setter | - +-------------+------------------+-----------------------------------+ - - The ``get`` function takes one :c:type:`PyObject\*` parameter (the - instance) and a function pointer (the associated ``closure``):: - - typedef PyObject *(*getter)(PyObject *, void *); - - It should return a new reference on success or ``NULL`` with a set exception - on failure. - - ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and - the value to be set) and a function pointer (the associated ``closure``):: - - typedef int (*setter)(PyObject *, PyObject *, void *); - - In case the attribute should be deleted the second parameter is ``NULL``. - Should return ``0`` on success or ``-1`` with a set exception on failure. diff --git a/Doc/c-api/type.rst.bak b/Doc/c-api/type.rst.bak deleted file mode 100644 index 41956b7dca5032..00000000000000 --- a/Doc/c-api/type.rst.bak +++ /dev/null @@ -1,209 +0,0 @@ -.. highlight:: c - -.. _typeobjects: - -Type Objects ------------- - -.. index:: object: type - - -.. c:type:: PyTypeObject - - The C structure of the objects used to describe built-in types. - - -.. c:var:: PyObject* PyType_Type - - This is the type object for type objects; it is the same object as - :class:`type` in the Python layer. - - -.. c:function:: int PyType_Check(PyObject *o) - - Return true if the object *o* is a type object, including instances of types - derived from the standard type object. Return false in all other cases. - - -.. c:function:: int PyType_CheckExact(PyObject *o) - - Return true if the object *o* is a type object, but not a subtype of the - standard type object. Return false in all other cases. - - -.. c:function:: unsigned int PyType_ClearCache() - - Clear the internal lookup cache. Return the current version tag. - -.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type) - - Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily - meant for use with `Py_LIMITED_API`; the individual flag bits are - guaranteed to be stable across Python releases, but access to - :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API. - - .. versionadded:: 3.2 - - .. versionchanged:: 3.4 - The return type is now ``unsigned long`` rather than ``long``. - - -.. c:function:: void PyType_Modified(PyTypeObject *type) - - Invalidate the internal lookup cache for the type and all of its - subtypes. This function must be called after any manual - modification of the attributes or base classes of the type. - - -.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature) - - Return true if the type object *o* sets the feature *feature*. Type features - are denoted by single bit flags. - - -.. c:function:: int PyType_IS_GC(PyTypeObject *o) - - Return true if the type object includes support for the cycle detector; this - tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. - - -.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) - - Return true if *a* is a subtype of *b*. - - This function only checks for actual subtypes, which means that - :meth:`~class.__subclasscheck__` is not called on *b*. Call - :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass` - would do. - - -.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object. Use - Python's default memory allocation mechanism to allocate a new instance and - initialize all its contents to ``NULL``. - -.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) - - Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object. Create a - new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot. - -.. c:function:: int PyType_Ready(PyTypeObject *type) - - Finalize a type object. This should be called on all type objects to finish - their initialization. This function is responsible for adding inherited slots - from a type's base class. Return ``0`` on success, or return ``-1`` and sets an - exception on error. - -.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot) - - Return the function pointer stored in the given slot. If the - result is ``NULL``, this indicates that either the slot is ``NULL``, - or that the function was called with invalid parameters. - Callers will typically cast the result pointer into the appropriate - function type. - - See :c:member:`PyType_Slot.slot` for possible values of the *slot* argument. - - An exception is raised if *type* is not a heap type. - - .. versionadded:: 3.4 - - -Creating Heap-Allocated Types -............................. - -The following functions and structs are used to create -:ref:`heap types `. - -.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases) - - Creates and returns a heap type object from the *spec* - (:const:`Py_TPFLAGS_HEAPTYPE`). - - If *bases* is a tuple, the created heap type contains all types contained - in it as base types. - - If *bases* is ``NULL``, the *Py_tp_base* slot is used instead. - If that also is ``NULL``, the new type derives from :class:`object`. - - This function calls :c:func:`PyType_Ready` on the new type. - - .. versionadded:: 3.3 - -.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec) - - Equivalent to ``PyType_FromSpecWithBases(spec, NULL)``. - -.. c:type:: PyType_Spec - - Structure defining a type's behavior. - - .. c:member:: const char* PyType_Spec.name - - Name of the type, used to set :c:member:`PyTypeObject.tp_name`. - - .. c:member:: int PyType_Spec.basicsize - .. c:member:: int PyType_Spec.itemsize - - Size of the instance in bytes, used to set - :c:member:`PyTypeObject.tp_basicsize` and - :c:member:`PyTypeObject.tp_itemsize`. - - .. c:member:: int PyType_Spec.flags - - Type flags, used to set :c:member:`PyTypeObject.tp_flags`. - - If the ``Py_TPFLAGS_HEAPTYPE`` flag is not set, - :c:func:`PyType_FromSpecWithBases` sets it automatically. - - .. c:member:: PyType_Slot *PyType_Spec.slots - - Array of :c:type:`PyType_Slot` structures. - Terminated by the special slot value ``{0, NULL}``. - -.. c:type:: PyType_Slot - - Structure defining optional functionality of a type, containing a slot ID - and a value pointer. - - .. c:member:: int PyType_Slot.slot - - A slot ID. - - Slot IDs are named like the field names of the structures - :c:type:`PyTypeObject`, :c:type:`PyNumberMethods`, - :c:type:`PySequenceMethods`, :c:type:`PyMappingMethods` and - :c:type:`PyAsyncMethods` with an added ``Py_`` prefix. - For example, use: - - * ``Py_tp_dealloc`` to set :c:member:`PyTypeObject.tp_dealloc` - * ``Py_nb_add`` to set :c:member:`PyNumberMethods.nb_add` - * ``Py_sq_length`` to set :c:member:`PySequenceMethods.sq_length` - - The following fields cannot be set using :c:type:`PyType_Spec` and :c:type:`PyType_Slot`: - - * :c:member:`~PyTypeObject.tp_dict` - * :c:member:`~PyTypeObject.tp_mro` - * :c:member:`~PyTypeObject.tp_cache` - * :c:member:`~PyTypeObject.tp_subclasses` - * :c:member:`~PyTypeObject.tp_weaklist` - * :c:member:`~PyTypeObject.tp_vectorcall` - * :c:member:`~PyTypeObject.tp_weaklistoffset` - (see :ref:`PyMemberDef `) - * :c:member:`~PyTypeObject.tp_dictoffset` - (see :ref:`PyMemberDef `) - * :c:member:`~PyTypeObject.tp_vectorcall_offset` - * :c:member:`~PyBufferProcs.bf_getbuffer` - * :c:member:`~PyBufferProcs.bf_releasebuffer` - - Setting :c:data:`Py_tp_bases` may be problematic on some platforms. - To avoid issues, use the *bases* argument of - :py:func:`PyType_FromSpecWithBases` instead. - - .. c:member:: void *PyType_Slot.pfunc - - The desired value of the slot. In most cases, this is a pointer - to a function. - - May not be ``NULL``. diff --git a/Doc/c-api/typeobj.rst.bak b/Doc/c-api/typeobj.rst.bak deleted file mode 100644 index a8a779ef6165a8..00000000000000 --- a/Doc/c-api/typeobj.rst.bak +++ /dev/null @@ -1,2565 +0,0 @@ -.. highlight:: c - -.. _type-structs: - -Type Objects -============ - -Perhaps one of the most important structures of the Python object system is the -structure that defines a new type: the :c:type:`PyTypeObject` structure. Type -objects can be handled using any of the :c:func:`PyObject_\*` or -:c:func:`PyType_\*` functions, but do not offer much that's interesting to most -Python applications. These objects are fundamental to how objects behave, so -they are very important to the interpreter itself and to any extension module -that implements new types. - -Type objects are fairly large compared to most of the standard types. The reason -for the size is that each type object stores a large number of values, mostly C -function pointers, each of which implements a small part of the type's -functionality. The fields of the type object are examined in detail in this -section. The fields will be described in the order in which they occur in the -structure. - -In addition to the following quick reference, the :ref:`typedef-examples` -section provides at-a-glance insight into the meaning and use of -:c:type:`PyTypeObject`. - - -Quick Reference ---------------- - -.. _tp-slots-table: - -"tp slots" -^^^^^^^^^^ - -.. table:: - :widths: 18,18,18,1,1,1,1 - - +------------------------------------------------+-----------------------------------+-------------------+---------------+ - | PyTypeObject Slot [#slots]_ | :ref:`Type ` | special | Info [#cols]_ | - | | | methods/attrs +---+---+---+---+ - | | | | O | T | D | I | - +================================================+===================================+===================+===+===+===+===+ - | :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_vectorcall_offset` | Py_ssize_t | | | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | - | | | __getattr__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | __setattr__, | | | | G | - | | | __delattr__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | :ref:`sub-slots` | | | | % | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | __repr__ | X | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | :ref:`sub-slots` | | | | % | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | :ref:`sub-slots` | | | | % | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | :ref:`sub-slots` | | | | % | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | __hash__ | X | | | G | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | __call__ | | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | __str__ | X | | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | __getattribute__, | X | X | | G | - | | | __getattr__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | __setattr__, | X | X | | G | - | | | __delattr__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | | % | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_flags` | unsigned long | | X | X | | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_doc` | const char * | __doc__ | X | X | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | | X | | G | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | | X | | G | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | __lt__, | X | | | G | - | | | __le__, | | | | | - | | | __eq__, | | | | | - | | | __ne__, | | | | | - | | | __gt__, | | | | | - | | | __ge__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | __next__ | | | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | | X | X | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | | X | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | | X | X | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | __base__ | | | X | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | __dict__ | | | ? | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | __get__ | | | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | - | | | __delete__ | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | | X | | ? | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | __new__ | X | X | ? | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | | X | X | ? | ? | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | | X | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | __bases__ | | | ~ | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | __mro__ | | | ~ | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | __subclasses__ | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | __del__ | | | | X | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - | :c:member:`~PyTypeObject.tp_vectorcall` | :c:type:`vectorcallfunc` | | | | | | - +------------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ - -.. [#slots] - A slot name in parentheses indicates it is (effectively) deprecated. - Names in angle brackets should be treated as read-only. - Names in square brackets are for internal use only. - "" (as a prefix) means the field is required (must be non-``NULL``). -.. [#cols] Columns: - - **"O"**: set on :c:type:`PyBaseObject_Type` - - **"T"**: set on :c:type:`PyType_Type` - - **"D"**: default (if slot is set to ``NULL``) - - .. code-block:: none - - X - PyType_Ready sets this value if it is NULL - ~ - PyType_Ready always sets this value (it should be NULL) - ? - PyType_Ready may set this value depending on other slots - - Also see the inheritance column ("I"). - - **"I"**: inheritance - - .. code-block:: none - - X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value - % - the slots of the sub-struct are inherited individually - G - inherited, but only in combination with other slots; see the slot's description - ? - it's complicated; see the slot's description - - Note that some slots are effectively inherited through the normal - attribute lookup chain. - -.. _sub-slots: - -sub-slots -^^^^^^^^^ - -.. table:: - :widths: 26,17,12 - - +---------------------------------------------------------+-----------------------------------+--------------+ - | Slot | :ref:`Type ` | special | - | | | methods | - +=========================================================+===================================+==============+ - | :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyAsyncMethods.am_anext` | :c:type:`unaryfunc` | __anext__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_add` | :c:type:`binaryfunc` | __add__ | - | | | __radd__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ | - | | | __rsub__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __sub__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ | - | | | __rmul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __mul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ | - | | | __rmod__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __mod__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ | - | | | __rdivmod__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ | - | | | __rpow__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __pow__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ | - | | | __rlshift__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __lshift__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ | - | | | __rrshift__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __rshift__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ | - | | | __rand__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __and__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ | - | | | __rxor__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __xor__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ | - | | | __ror__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __or__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_reserved` | void * | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __truediv__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_index` | :c:type:`unaryfunc` | __index__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | - | | | __rmatmul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, | - | | | __delitem__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ | - | | | __delitem__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ | - +---------------------------------------------------------+-----------------------------------+--------------+ - | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | | - +---------------------------------------------------------+-----------------------------------+--------------+ - | :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | | - +---------------------------------------------------------+-----------------------------------+--------------+ - -.. _slot-typedefs-table: - -slot typedefs -^^^^^^^^^^^^^ - -+-----------------------------+-----------------------------+----------------------+ -| typedef | Parameter Types | Return Type | -+=============================+=============================+======================+ -| :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyTypeObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`destructor` | void * | void | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`freefunc` | void * | void | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`traverseproc` | .. line-block:: | int | -| | | | -| | void * | | -| | :c:type:`visitproc` | | -| | void * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`initproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`setattrfunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | const char * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getattrofunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`setattrofunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`descrsetfunc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | int | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`getbufferproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`Py_buffer` * | | -| | int | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`releasebufferproc` | .. line-block:: | void | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`Py_buffer` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`inquiry` | void * | int | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`ssizeobjargproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | Py_ssize_t | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`objobjproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ -| :c:type:`objobjargproc` | .. line-block:: | int | -| | | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -| | :c:type:`PyObject` * | | -+-----------------------------+-----------------------------+----------------------+ - -See :ref:`slot-typedefs` below for more detail. - - -PyTypeObject Definition ------------------------ - -The structure definition for :c:type:`PyTypeObject` can be found in -:file:`Include/object.h`. For convenience of reference, this repeats the -definition found there: - -.. XXX Drop this? - -.. literalinclude:: ../includes/typestruct.h - - -PyObject Slots --------------- - -The type object structure extends the :c:type:`PyVarObject` structure. The -:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, -usually called from a class statement). Note that :c:data:`PyType_Type` (the -metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e. -type objects) *must* have the :attr:`ob_size` field. - - -.. c:member:: PyObject* PyObject._ob_next - PyObject* PyObject._ob_prev - - These fields are only present when the macro ``Py_TRACE_REFS`` is defined. - Their initialization to ``NULL`` is taken care of by the ``PyObject_HEAD_INIT`` - macro. For statically allocated objects, these fields always remain ``NULL``. - For dynamically allocated objects, these two fields are used to link the object - into a doubly-linked list of *all* live objects on the heap. This could be used - for various debugging purposes; currently the only use is to print the objects - that are still alive at the end of a run when the environment variable - :envvar:`PYTHONDUMPREFS` is set. - - **Inheritance:** - - These fields are not inherited by subtypes. - - -.. c:member:: Py_ssize_t PyObject.ob_refcnt - - This is the type object's reference count, initialized to ``1`` by the - ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, - the type's instances (objects whose :attr:`ob_type` points back to the type) do - *not* count as references. But for dynamically allocated type objects, the - instances *do* count as references. - - **Inheritance:** - - This field is not inherited by subtypes. - - -.. c:member:: PyTypeObject* PyObject.ob_type - - This is the type's type, in other words its metatype. It is initialized by the - argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be - ``&PyType_Type``. However, for dynamically loadable extension modules that must - be usable on Windows (at least), the compiler complains that this is not a valid - initializer. Therefore, the convention is to pass ``NULL`` to the - ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the - start of the module's initialization function, before doing anything else. This - is typically done like this:: - - Foo_Type.ob_type = &PyType_Type; - - This should be done before any instances of the type are created. - :c:func:`PyType_Ready` checks if :attr:`ob_type` is ``NULL``, and if so, - initializes it to the :attr:`ob_type` field of the base class. - :c:func:`PyType_Ready` will not change this field if it is non-zero. - - **Inheritance:** - - This field is inherited by subtypes. - - -PyVarObject Slots ------------------ - -.. c:member:: Py_ssize_t PyVarObject.ob_size - - For statically allocated type objects, this should be initialized to zero. For - dynamically allocated type objects, this field has a special internal meaning. - - **Inheritance:** - - This field is not inherited by subtypes. - - -PyTypeObject Slots ------------------- - -Each slot has a section describing inheritance. If :c:func:`PyType_Ready` -may set a value when the field is set to ``NULL`` then there will also be -a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type` -and :c:type:`PyType_Type` effectively act as defaults.) - -.. c:member:: const char* PyTypeObject.tp_name - - Pointer to a NUL-terminated string containing the name of the type. For types - that are accessible as module globals, the string should be the full module - name, followed by a dot, followed by the type name; for built-in types, it - should be just the type name. If the module is a submodule of a package, the - full package name is part of the full module name. For example, a type named - :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P` - should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``. - - For dynamically allocated type objects, this should just be the type name, and - the module name explicitly stored in the type dict as the value for key - ``'__module__'``. - - For statically allocated type objects, the tp_name field should contain a dot. - Everything before the last dot is made accessible as the :attr:`__module__` - attribute, and everything after the last dot is made accessible as the - :attr:`~definition.__name__` attribute. - - If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the - :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined - (unless explicitly set in the dictionary, as explained above). This means your - type will be impossible to pickle. Additionally, it will not be listed in - module documentations created with pydoc. - - This field must not be ``NULL``. It is the only required field - in :c:func:`PyTypeObject` (other than potentially - :c:member:`~PyTypeObject.tp_itemsize`). - - **Inheritance:** - - This field is not inherited by subtypes. - - -.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize - Py_ssize_t PyTypeObject.tp_itemsize - - These fields allow calculating the size in bytes of instances of the type. - - There are two kinds of types: types with fixed-length instances have a zero - :c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero - :c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all - instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`. - - For a type with variable-length instances, the instances must have an - :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N - times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of - N is typically stored in the instance's :attr:`ob_size` field. There are - exceptions: for example, ints use a negative :attr:`ob_size` to indicate a - negative number, and N is ``abs(ob_size)`` there. Also, the presence of an - :attr:`ob_size` field in the instance layout doesn't mean that the instance - structure is variable-length (for example, the structure for the list type has - fixed-length instances, yet those instances have a meaningful :attr:`ob_size` - field). - - The basic size includes the fields in the instance declared by the macro - :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to - declare the instance struct) and this in turn includes the :attr:`_ob_prev` and - :attr:`_ob_next` fields if they are present. This means that the only correct - way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the - ``sizeof`` operator on the struct used to declare the instance layout. - The basic size does not include the GC header size. - - A note about alignment: if the variable items require a particular alignment, - this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example: - suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is - ``sizeof(double)``. It is the programmer's responsibility that - :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the - alignment requirement for ``double``). - - For any type with variable-length instances, this field must not be ``NULL``. - - **Inheritance:** - - These fields are inherited separately by subtypes. If the base type has a - non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set - :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this - depends on the implementation of the base type). - - -.. c:member:: destructor PyTypeObject.tp_dealloc - - A pointer to the instance destructor function. This function must be defined - unless the type guarantees that its instances will never be deallocated (as is - the case for the singletons ``None`` and ``Ellipsis``). The function signature is:: - - void tp_dealloc(PyObject *self); - - The destructor function is called by the :c:func:`Py_DECREF` and - :c:func:`Py_XDECREF` macros when the new reference count is zero. At this point, - the instance is still in existence, but there are no references to it. The - destructor function should free all references which the instance owns, free all - memory buffers owned by the instance (using the freeing function corresponding - to the allocation function used to allocate the buffer), and call the type's - :c:member:`~PyTypeObject.tp_free` function. If the type is not subtypable - (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is - permissible to call the object deallocator directly instead of via - :c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the - instance; this is normally :c:func:`PyObject_Del` if the instance was allocated - using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or - :c:func:`PyObject_GC_Del` if the instance was allocated using - :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. - - Finally, if the type is heap allocated (:const:`Py_TPFLAGS_HEAPTYPE`), the - deallocator should decrement the reference count for its type object after - calling the type deallocator. In order to avoid dangling pointers, the - recommended way to achieve this is: - - .. code-block:: c - - static void foo_dealloc(foo_object *self) { - PyTypeObject *tp = Py_TYPE(self); - // free references and buffers here - tp->tp_free(self); - Py_DECREF(tp); - } - - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: Py_ssize_t PyTypeObject.tp_vectorcall_offset - - An optional offset to a per-instance function that implements calling - the object using the :ref:`vectorcall protocol `, - a more efficient alternative - of the simpler :c:member:`~PyTypeObject.tp_call`. - - This field is only used if the flag :const:`_Py_TPFLAGS_HAVE_VECTORCALL` - is set. If so, this must be a positive integer containing the offset in the - instance of a :c:type:`vectorcallfunc` pointer. - - The *vectorcallfunc* pointer may be ``NULL``, in which case the instance behaves - as if :const:`_Py_TPFLAGS_HAVE_VECTORCALL` was not set: calling the instance - falls back to :c:member:`~PyTypeObject.tp_call`. - - Any class that sets ``_Py_TPFLAGS_HAVE_VECTORCALL`` must also set - :c:member:`~PyTypeObject.tp_call` and make sure its behaviour is consistent - with the *vectorcallfunc* function. - This can be done by setting *tp_call* to :c:func:`PyVectorcall_Call`. - - .. warning:: - - It is not recommended for :ref:`heap types ` to implement - the vectorcall protocol. - When a user sets :attr:`__call__` in Python code, only *tp_call* is updated, - likely making it inconsistent with the vectorcall function. - - .. note:: - - The semantics of the ``tp_vectorcall_offset`` slot are provisional and - expected to be finalized in Python 3.9. - If you use vectorcall, plan for updating your code for Python 3.9. - - .. versionchanged:: 3.8 - - Before version 3.8, this slot was named ``tp_print``. - In Python 2.x, it was used for printing to a file. - In Python 3.0 to 3.7, it was unused. - - **Inheritance:** - - This field is always inherited. - However, the :const:`_Py_TPFLAGS_HAVE_VECTORCALL` flag is not - always inherited. If it's not, then the subclass won't use - :ref:`vectorcall `, except when - :c:func:`PyVectorcall_Call` is explicitly called. - This is in particular the case for `heap types`_ - (including subclasses defined in Python). - - -.. c:member:: getattrfunc PyTypeObject.tp_getattr - - An optional pointer to the get-attribute-string function. - - This field is deprecated. When it is defined, it should point to a function - that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string - instead of a Python string object to give the attribute name. - - **Inheritance:** - - Group: :attr:`tp_getattr`, :attr:`tp_getattro` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype - inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when - the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``. - - -.. c:member:: setattrfunc PyTypeObject.tp_setattr - - An optional pointer to the function for setting and deleting attributes. - - This field is deprecated. When it is defined, it should point to a function - that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string - instead of a Python string object to give the attribute name. - - **Inheritance:** - - Group: :attr:`tp_setattr`, :attr:`tp_setattro` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype - inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when - the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``. - - -.. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async - - Pointer to an additional structure that contains fields relevant only to - objects which implement :term:`awaitable` and :term:`asynchronous iterator` - protocols at the C-level. See :ref:`async-structs` for details. - - .. versionadded:: 3.5 - Formerly known as ``tp_compare`` and ``tp_reserved``. - - **Inheritance:** - - The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, - but the contained fields are inherited individually. - - -.. c:member:: reprfunc PyTypeObject.tp_repr - - .. index:: builtin: repr - - An optional pointer to a function that implements the built-in function - :func:`repr`. - - The signature is the same as for :c:func:`PyObject_Repr`:: - - PyObject *tp_repr(PyObject *self); - - The function must return a string or a Unicode object. Ideally, - this function should return a string that, when passed to - :func:`eval`, given a suitable environment, returns an object with the - same value. If this is not feasible, it should return a string starting with - ``'<'`` and ending with ``'>'`` from which both the type and the value of the - object can be deduced. - - **Inheritance:** - - This field is inherited by subtypes. - - **Default:** - - When this field is not set, a string of the form ``<%s object at %p>`` is - returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's - memory address. - - -.. c:member:: PyNumberMethods* PyTypeObject.tp_as_number - - Pointer to an additional structure that contains fields relevant only to - objects which implement the number protocol. These fields are documented in - :ref:`number-structs`. - - **Inheritance:** - - The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are - inherited individually. - - -.. c:member:: PySequenceMethods* PyTypeObject.tp_as_sequence - - Pointer to an additional structure that contains fields relevant only to - objects which implement the sequence protocol. These fields are documented - in :ref:`sequence-structs`. - - **Inheritance:** - - The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields - are inherited individually. - - -.. c:member:: PyMappingMethods* PyTypeObject.tp_as_mapping - - Pointer to an additional structure that contains fields relevant only to - objects which implement the mapping protocol. These fields are documented in - :ref:`mapping-structs`. - - **Inheritance:** - - The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields - are inherited individually. - - -.. c:member:: hashfunc PyTypeObject.tp_hash - - .. index:: builtin: hash - - An optional pointer to a function that implements the built-in function - :func:`hash`. - - The signature is the same as for :c:func:`PyObject_Hash`:: - - Py_hash_t tp_hash(PyObject *); - - The value ``-1`` should not be returned as a - normal return value; when an error occurs during the computation of the hash - value, the function should set an exception and return ``-1``. - - When this field is not set (*and* :attr:`tp_richcompare` is not set), - an attempt to take the hash of the object raises :exc:`TypeError`. - This is the same as setting it to :c:func:`PyObject_HashNotImplemented`. - - This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to - block inheritance of the hash method from a parent type. This is interpreted - as the equivalent of ``__hash__ = None`` at the Python level, causing - ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note - that the converse is also true - setting ``__hash__ = None`` on a class at - the Python level will result in the ``tp_hash`` slot being set to - :c:func:`PyObject_HashNotImplemented`. - - **Inheritance:** - - Group: :attr:`tp_hash`, :attr:`tp_richcompare` - - This field is inherited by subtypes together with - :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of - :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's - :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both ``NULL``. - - -.. c:member:: ternaryfunc PyTypeObject.tp_call - - An optional pointer to a function that implements calling the object. This - should be ``NULL`` if the object is not callable. The signature is the same as - for :c:func:`PyObject_Call`:: - - PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs); - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: reprfunc PyTypeObject.tp_str - - An optional pointer to a function that implements the built-in operation - :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the - constructor for that type. This constructor calls :c:func:`PyObject_Str` to do - the actual work, and :c:func:`PyObject_Str` will call this handler.) - - The signature is the same as for :c:func:`PyObject_Str`:: - - PyObject *tp_str(PyObject *self); - - The function must return a string or a Unicode object. It should be a "friendly" string - representation of the object, as this is the representation that will be used, - among other things, by the :func:`print` function. - - **Inheritance:** - - This field is inherited by subtypes. - - **Default:** - - When this field is not set, :c:func:`PyObject_Repr` is called to return a string - representation. - - -.. c:member:: getattrofunc PyTypeObject.tp_getattro - - An optional pointer to the get-attribute function. - - The signature is the same as for :c:func:`PyObject_GetAttr`:: - - PyObject *tp_getattro(PyObject *self, PyObject *attr); - - It is usually convenient to set this field to :c:func:`PyObject_GenericGetAttr`, - which implements the normal way of looking for object attributes. - - **Inheritance:** - - Group: :attr:`tp_getattr`, :attr:`tp_getattro` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype - inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when - the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both ``NULL``. - - **Default:** - - :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`. - - -.. c:member:: setattrofunc PyTypeObject.tp_setattro - - An optional pointer to the function for setting and deleting attributes. - - The signature is the same as for :c:func:`PyObject_SetAttr`:: - - int tp_setattro(PyObject *self, PyObject *attr, PyObject *value); - - In addition, setting *value* to ``NULL`` to delete an attribute must be - supported. It is usually convenient to set this field to - :c:func:`PyObject_GenericSetAttr`, which implements the normal - way of setting object attributes. - - **Inheritance:** - - Group: :attr:`tp_setattr`, :attr:`tp_setattro` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype - inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when - the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both ``NULL``. - - **Default:** - - :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`. - - -.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer - - Pointer to an additional structure that contains fields relevant only to objects - which implement the buffer interface. These fields are documented in - :ref:`buffer-structs`. - - **Inheritance:** - - The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, - but the contained fields are inherited individually. - - -.. c:member:: unsigned long PyTypeObject.tp_flags - - This field is a bit mask of various flags. Some flags indicate variant - semantics for certain situations; others are used to indicate that certain - fields in the type object (or in the extension structures referenced via - :c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and - :c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if - such a flag bit is clear, the type fields it guards must not be accessed and - must be considered to have a zero or ``NULL`` value instead. - - **Inheritance:** - - Inheritance of this field is complicated. Most flag bits are inherited - individually, i.e. if the base type has a flag bit set, the subtype inherits - this flag bit. The flag bits that pertain to extension structures are strictly - inherited if the extension structure is inherited, i.e. the base type's value of - the flag bit is copied into the subtype together with a pointer to the extension - structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with - the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the - :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the - :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have - ``NULL`` values. - - .. XXX are most flag bits *really* inherited individually? - - **Default:** - - :c:type:`PyBaseObject_Type` uses - ``Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE``. - - **Bit Masks:** - - The following bit masks are currently defined; these can be ORed together using - the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro - :c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and - checks whether ``tp->tp_flags & f`` is non-zero. - - .. data:: Py_TPFLAGS_HEAPTYPE - - This bit is set when the type object itself is allocated on the heap, for - example, types created dynamically using :c:func:`PyType_FromSpec`. In this - case, the :attr:`ob_type` field of its instances is considered a reference to - the type, and the type object is INCREF'ed when a new instance is created, and - DECREF'ed when an instance is destroyed (this does not apply to instances of - subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or - DECREF'ed). - - **Inheritance:** - - ??? - - - .. data:: Py_TPFLAGS_BASETYPE - - This bit is set when the type can be used as the base type of another type. If - this bit is clear, the type cannot be subtyped (similar to a "final" class in - Java). - - **Inheritance:** - - ??? - - - .. data:: Py_TPFLAGS_READY - - This bit is set when the type object has been fully initialized by - :c:func:`PyType_Ready`. - - **Inheritance:** - - ??? - - - .. data:: Py_TPFLAGS_READYING - - This bit is set while :c:func:`PyType_Ready` is in the process of initializing - the type object. - - **Inheritance:** - - ??? - - - .. data:: Py_TPFLAGS_HAVE_GC - - This bit is set when the object supports garbage collection. If this bit - is set, instances must be created using :c:func:`PyObject_GC_New` and - destroyed using :c:func:`PyObject_GC_Del`. More information in section - :ref:`supporting-cycle-detection`. This bit also implies that the - GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in - the type object. - - **Inheritance:** - - Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` - - The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited - together with the :attr:`tp_traverse` and :attr:`tp_clear` - fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is - clear in the subtype and the :attr:`tp_traverse` and - :attr:`tp_clear` fields in the subtype exist and have ``NULL`` - values. - - - .. data:: Py_TPFLAGS_DEFAULT - - This is a bitmask of all the bits that pertain to the existence of certain - fields in the type object and its extension structures. Currently, it includes - the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, - :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. - - **Inheritance:** - - ??? - - - .. data:: Py_TPFLAGS_METHOD_DESCRIPTOR - - This bit indicates that objects behave like unbound methods. - - If this flag is set for ``type(meth)``, then: - - - ``meth.__get__(obj, cls)(*args, **kwds)`` (with ``obj`` not None) - must be equivalent to ``meth(obj, *args, **kwds)``. - - - ``meth.__get__(None, cls)(*args, **kwds)`` - must be equivalent to ``meth(*args, **kwds)``. - - This flag enables an optimization for typical method calls like - ``obj.meth()``: it avoids creating a temporary "bound method" object for - ``obj.meth``. - - .. versionadded:: 3.8 - - **Inheritance:** - - This flag is never inherited by heap types. - For extension types, it is inherited whenever - :c:member:`~PyTypeObject.tp_descr_get` is inherited. - - - .. XXX Document more flags here? - - - .. data:: Py_TPFLAGS_LONG_SUBCLASS - .. data:: Py_TPFLAGS_LIST_SUBCLASS - .. data:: Py_TPFLAGS_TUPLE_SUBCLASS - .. data:: Py_TPFLAGS_BYTES_SUBCLASS - .. data:: Py_TPFLAGS_UNICODE_SUBCLASS - .. data:: Py_TPFLAGS_DICT_SUBCLASS - .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS - .. data:: Py_TPFLAGS_TYPE_SUBCLASS - - These flags are used by functions such as - :c:func:`PyLong_Check` to quickly determine if a type is a subclass - of a built-in type; such specific checks are faster than a generic - check, like :c:func:`PyObject_IsInstance`. Custom types that inherit - from built-ins should have their :c:member:`~PyTypeObject.tp_flags` - set appropriately, or the code that interacts with such types - will behave differently depending on what kind of check is used. - - - .. data:: Py_TPFLAGS_HAVE_FINALIZE - - This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the - type structure. - - .. versionadded:: 3.4 - - .. deprecated:: 3.8 - This flag isn't necessary anymore, as the interpreter assumes the - :c:member:`~PyTypeObject.tp_finalize` slot is always present in the - type structure. - - - .. data:: _Py_TPFLAGS_HAVE_VECTORCALL - - This bit is set when the class implements - the :ref:`vectorcall protocol `. - See :c:member:`~PyTypeObject.tp_vectorcall_offset` for details. - - **Inheritance:** - - This bit is inherited for *static* subtypes if - :c:member:`~PyTypeObject.tp_call` is also inherited. - `Heap types`_ do not inherit ``_Py_TPFLAGS_HAVE_VECTORCALL``. - - .. note:: - - This flag is provisional and expected to become public in Python 3.9, - with a different name and, possibly, changed semantics. - If you use vectorcall, plan for updating your code for Python 3.9. - - .. versionadded:: 3.8 - - -.. c:member:: const char* PyTypeObject.tp_doc - - An optional pointer to a NUL-terminated C string giving the docstring for this - type object. This is exposed as the :attr:`__doc__` attribute on the type and - instances of the type. - - **Inheritance:** - - This field is *not* inherited by subtypes. - - -.. c:member:: traverseproc PyTypeObject.tp_traverse - - An optional pointer to a traversal function for the garbage collector. This is - only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: - - int tp_traverse(PyObject *self, visitproc visit, void *arg); - - More information about Python's garbage collection scheme can be found - in section :ref:`supporting-cycle-detection`. - - The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect - reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function - simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python - objects. For example, this is function :c:func:`local_traverse` from the - :mod:`_thread` extension module:: - - static int - local_traverse(localobject *self, visitproc visit, void *arg) - { - Py_VISIT(self->args); - Py_VISIT(self->kw); - Py_VISIT(self->dict); - return 0; - } - - Note that :c:func:`Py_VISIT` is called only on those members that can participate - in reference cycles. Although there is also a ``self->key`` member, it can only - be ``NULL`` or a Python string and therefore cannot be part of a reference cycle. - - On the other hand, even if you know a member can never be part of a cycle, as a - debugging aid you may want to visit it anyway just so the :mod:`gc` module's - :func:`~gc.get_referents` function will include it. - - Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to - :c:func:`local_traverse` to have these specific names; don't name them just - anything. - - **Inheritance:** - - Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the - :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and - :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in - the subtype. - - -.. c:member:: inquiry PyTypeObject.tp_clear - - An optional pointer to a clear function for the garbage collector. This is only - used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: - - int tp_clear(PyObject *); - - The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic - garbage detected by the garbage collector. Taken together, all :c:member:`~PyTypeObject.tp_clear` - functions in the system must combine to break all reference cycles. This is - subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, - the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` function, because it's - possible to prove that no reference cycle can be composed entirely of tuples. - Therefore the :c:member:`~PyTypeObject.tp_clear` functions of other types must be sufficient to - break any cycle containing a tuple. This isn't immediately obvious, and there's - rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`. - - Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to - those of its members that may be Python objects, and set its pointers to those - members to ``NULL``, as in the following example:: - - static int - local_clear(localobject *self) - { - Py_CLEAR(self->key); - Py_CLEAR(self->args); - Py_CLEAR(self->kw); - Py_CLEAR(self->dict); - return 0; - } - - The :c:func:`Py_CLEAR` macro should be used, because clearing references is - delicate: the reference to the contained object must not be decremented until - after the pointer to the contained object is set to ``NULL``. This is because - decrementing the reference count may cause the contained object to become trash, - triggering a chain of reclamation activity that may include invoking arbitrary - Python code (due to finalizers, or weakref callbacks, associated with the - contained object). If it's possible for such code to reference *self* again, - it's important that the pointer to the contained object be ``NULL`` at that time, - so that *self* knows the contained object can no longer be used. The - :c:func:`Py_CLEAR` macro performs the operations in a safe order. - - Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles, - it's not necessary to clear contained objects like Python strings or Python - integers, which can't participate in reference cycles. On the other hand, it may - be convenient to clear all contained Python objects, and write the type's - :c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:`~PyTypeObject.tp_clear`. - - More information about Python's garbage collection scheme can be found in - section :ref:`supporting-cycle-detection`. - - **Inheritance:** - - Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the - :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and - :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in - the subtype. - - -.. c:member:: richcmpfunc PyTypeObject.tp_richcompare - - An optional pointer to the rich comparison function, whose signature is:: - - PyObject *tp_richcompare(PyObject *self, PyObject *other, int op); - - The first parameter is guaranteed to be an instance of the type - that is defined by :c:type:`PyTypeObject`. - - The function should return the result of the comparison (usually ``Py_True`` - or ``Py_False``). If the comparison is undefined, it must return - ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and - set an exception condition. - - The following constants are defined to be used as the third argument for - :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: - - +----------------+------------+ - | Constant | Comparison | - +================+============+ - | :const:`Py_LT` | ``<`` | - +----------------+------------+ - | :const:`Py_LE` | ``<=`` | - +----------------+------------+ - | :const:`Py_EQ` | ``==`` | - +----------------+------------+ - | :const:`Py_NE` | ``!=`` | - +----------------+------------+ - | :const:`Py_GT` | ``>`` | - +----------------+------------+ - | :const:`Py_GE` | ``>=`` | - +----------------+------------+ - - The following macro is defined to ease writing rich comparison functions: - - .. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) - - Return ``Py_True`` or ``Py_False`` from the function, depending on the - result of a comparison. - VAL_A and VAL_B must be orderable by C comparison operators (for example, - they may be C ints or floats). The third argument specifies the requested - operation, as for :c:func:`PyObject_RichCompare`. - - The return value's reference count is properly incremented. - - On error, sets an exception and returns ``NULL`` from the function. - - .. versionadded:: 3.7 - - **Inheritance:** - - Group: :attr:`tp_hash`, :attr:`tp_richcompare` - - This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`: - a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when - the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both - ``NULL``. - - **Default:** - - :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare` - implementation, which may be inherited. However, if only - :attr:`tp_hash` is defined, not even the inherited function is used - and instances of the type will not be able to participate in any - comparisons. - - -.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset - - If the instances of this type are weakly referenceable, this field is greater - than zero and contains the offset in the instance structure of the weak - reference list head (ignoring the GC header, if present); this offset is used by - :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The - instance structure needs to include a field of type :c:type:`PyObject\*` which is - initialized to ``NULL``. - - Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for - weak references to the type object itself. - - **Inheritance:** - - This field is inherited by subtypes, but see the rules listed below. A subtype - may override this offset; this means that the subtype uses a different weak - reference list head than the base type. Since the list head is always found via - :c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem. - - When a type defined by a class statement has no :attr:`~object.__slots__` declaration, - and none of its base types are weakly referenceable, the type is made weakly - referenceable by adding a weak reference list head slot to the instance layout - and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset. - - When a type's :attr:`__slots__` declaration contains a slot named - :attr:`__weakref__`, that slot becomes the weak reference list head for - instances of the type, and the slot's offset is stored in the type's - :c:member:`~PyTypeObject.tp_weaklistoffset`. - - When a type's :attr:`__slots__` declaration does not contain a slot named - :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its - base type. - - -.. c:member:: getiterfunc PyTypeObject.tp_iter - - An optional pointer to a function that returns an iterator for the object. Its - presence normally signals that the instances of this type are iterable (although - sequences may be iterable without this function). - - This function has the same signature as :c:func:`PyObject_GetIter`:: - - PyObject *tp_iter(PyObject *self); - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: iternextfunc PyTypeObject.tp_iternext - - An optional pointer to a function that returns the next item in an iterator. - The signature is:: - - PyObject *tp_iternext(PyObject *self); - - When the iterator is exhausted, it must return ``NULL``; a :exc:`StopIteration` - exception may or may not be set. When another error occurs, it must return - ``NULL`` too. Its presence signals that the instances of this type are - iterators. - - Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that - function should return the iterator instance itself (not a new iterator - instance). - - This function has the same signature as :c:func:`PyIter_Next`. - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods - - An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMethodDef` - structures, declaring regular methods of this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor. - - **Inheritance:** - - This field is not inherited by subtypes (methods are inherited through a - different mechanism). - - -.. c:member:: struct PyMemberDef* PyTypeObject.tp_members - - An optional pointer to a static ``NULL``-terminated array of :c:type:`PyMemberDef` - structures, declaring regular data members (fields or slots) of instances of - this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor. - - **Inheritance:** - - This field is not inherited by subtypes (members are inherited through a - different mechanism). - - -.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset - - An optional pointer to a static ``NULL``-terminated array of :c:type:`PyGetSetDef` - structures, declaring computed attributes of instances of this type. - - For each entry in the array, an entry is added to the type's dictionary (see - :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor. - - **Inheritance:** - - This field is not inherited by subtypes (computed attributes are inherited - through a different mechanism). - - -.. c:member:: PyTypeObject* PyTypeObject.tp_base - - An optional pointer to a base type from which type properties are inherited. At - this level, only single inheritance is supported; multiple inheritance require - dynamically creating a type object by calling the metatype. - - .. note:: - - .. from Modules/xxmodule.c - - Slot initialization is subject to the rules of initializing globals. - C99 requires the initializers to be "address constants". Function - designators like :c:func:`PyType_GenericNew`, with implicit conversion - to a pointer, are valid C99 address constants. - - However, the unary '&' operator applied to a non-static variable - like :c:func:`PyBaseObject_Type` is not required to produce an address - constant. Compilers may support this (gcc does), MSVC does not. - Both compilers are strictly standard conforming in this particular - behavior. - - Consequently, :c:member:`~PyTypeObject.tp_base` should be set in - the extension module's init function. - - **Inheritance:** - - This field is not inherited by subtypes (obviously). - - **Default:** - - This field defaults to ``&PyBaseObject_Type`` (which to Python - programmers is known as the type :class:`object`). - - -.. c:member:: PyObject* PyTypeObject.tp_dict - - The type's dictionary is stored here by :c:func:`PyType_Ready`. - - This field should normally be initialized to ``NULL`` before PyType_Ready is - called; it may also be initialized to a dictionary containing initial attributes - for the type. Once :c:func:`PyType_Ready` has initialized the type, extra - attributes for the type may be added to this dictionary only if they don't - correspond to overloaded operations (like :meth:`__add__`). - - **Inheritance:** - - This field is not inherited by subtypes (though the attributes defined in here - are inherited through a different mechanism). - - **Default:** - - If this field is ``NULL``, :c:func:`PyType_Ready` will assign a new - dictionary to it. - - .. warning:: - - It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify - :c:member:`~PyTypeObject.tp_dict` with the dictionary C-API. - - -.. c:member:: descrgetfunc PyTypeObject.tp_descr_get - - An optional pointer to a "descriptor get" function. - - The function signature is:: - - PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); - - .. XXX explain more? - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: descrsetfunc PyTypeObject.tp_descr_set - - An optional pointer to a function for setting and deleting - a descriptor's value. - - The function signature is:: - - int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); - - The *value* argument is set to ``NULL`` to delete the value. - - .. XXX explain more? - - **Inheritance:** - - This field is inherited by subtypes. - - -.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset - - If the instances of this type have a dictionary containing instance variables, - this field is non-zero and contains the offset in the instances of the type of - the instance variable dictionary; this offset is used by - :c:func:`PyObject_GenericGetAttr`. - - Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is the dictionary for - attributes of the type object itself. - - If the value of this field is greater than zero, it specifies the offset from - the start of the instance structure. If the value is less than zero, it - specifies the offset from the *end* of the instance structure. A negative - offset is more expensive to use, and should only be used when the instance - structure contains a variable-length part. This is used for example to add an - instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note - that the :c:member:`~PyTypeObject.tp_basicsize` field should account for the dictionary added to - the end in that case, even though the dictionary is not included in the basic - object layout. On a system with a pointer size of 4 bytes, - :c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is - at the very end of the structure. - - The real dictionary offset in an instance can be computed from a negative - :c:member:`~PyTypeObject.tp_dictoffset` as follows:: - - dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset - if dictoffset is not aligned on sizeof(void*): - round up to sizeof(void*) - - where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are - taken from the type object, and :attr:`ob_size` is taken from the instance. The - absolute value is taken because ints use the sign of :attr:`ob_size` to - store the sign of the number. (There's never a need to do this calculation - yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.) - - **Inheritance:** - - This field is inherited by subtypes, but see the rules listed below. A subtype - may override this offset; this means that the subtype instances store the - dictionary at a difference offset than the base type. Since the dictionary is - always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem. - - When a type defined by a class statement has no :attr:`~object.__slots__` declaration, - and none of its base types has an instance variable dictionary, a dictionary - slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to - that slot's offset. - - When a type defined by a class statement has a :attr:`__slots__` declaration, - the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type. - - (Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does - not have the expected effect, it just causes confusion. Maybe this should be - added as a feature just like :attr:`__weakref__` though.) - - **Default:** - - This slot has no default. For static types, if the field is - ``NULL`` then no :attr:`__dict__` gets created for instances. - - -.. c:member:: initproc PyTypeObject.tp_init - - An optional pointer to an instance initialization function. - - This function corresponds to the :meth:`__init__` method of classes. Like - :meth:`__init__`, it is possible to create an instance without calling - :meth:`__init__`, and it is possible to reinitialize an instance by calling its - :meth:`__init__` method again. - - The function signature is:: - - int tp_init(PyObject *self, PyObject *args, PyObject *kwds); - - The self argument is the instance to be initialized; the *args* and *kwds* - arguments represent positional and keyword arguments of the call to - :meth:`__init__`. - - The :c:member:`~PyTypeObject.tp_init` function, if not ``NULL``, is called when an instance is - created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function - has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an - instance of some other type that is not a subtype of the original type, no - :c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a - subtype of the original type, the subtype's :c:member:`~PyTypeObject.tp_init` is called. - - Returns ``0`` on success, ``-1`` and sets an exception on error. - - **Inheritance:** - - This field is inherited by subtypes. - - **Default:** - - For static types this field does not have a default. - - -.. c:member:: allocfunc PyTypeObject.tp_alloc - - An optional pointer to an instance allocation function. - - The function signature is:: - - PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems); - - **Inheritance:** - - This field is inherited by static subtypes, but not by dynamic - subtypes (subtypes created by a class statement). - - **Default:** - - For dynamic subtypes, this field is always set to - :c:func:`PyType_GenericAlloc`, to force a standard heap - allocation strategy. - - For static subtypes, :c:type:`PyBaseObject_Type` uses - :c:func:`PyType_GenericAlloc`. That is the recommended value - for all statically defined types. - - -.. c:member:: newfunc PyTypeObject.tp_new - - An optional pointer to an instance creation function. - - The function signature is:: - - PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds); - - The *subtype* argument is the type of the object being created; the *args* and - *kwds* arguments represent positional and keyword arguments of the call to the - type. Note that *subtype* doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new` - function is called; it may be a subtype of that type (but not an unrelated - type). - - The :c:member:`~PyTypeObject.tp_new` function should call ``subtype->tp_alloc(subtype, nitems)`` - to allocate space for the object, and then do only as much further - initialization as is absolutely necessary. Initialization that can safely be - ignored or repeated should be placed in the :c:member:`~PyTypeObject.tp_init` handler. A good - rule of thumb is that for immutable types, all initialization should take place - in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be - deferred to :c:member:`~PyTypeObject.tp_init`. - - **Inheritance:** - - This field is inherited by subtypes, except it is not inherited by static types - whose :c:member:`~PyTypeObject.tp_base` is ``NULL`` or ``&PyBaseObject_Type``. - - **Default:** - - For static types this field has no default. This means if the - slot is defined as ``NULL``, the type cannot be called to create new - instances; presumably there is some other way to create - instances, like a factory function. - - -.. c:member:: freefunc PyTypeObject.tp_free - - An optional pointer to an instance deallocation function. Its signature is:: - - void tp_free(void *self); - - An initializer that is compatible with this signature is :c:func:`PyObject_Free`. - - **Inheritance:** - - This field is inherited by static subtypes, but not by dynamic - subtypes (subtypes created by a class statement) - - **Default:** - - In dynamic subtypes, this field is set to a deallocator suitable to - match :c:func:`PyType_GenericAlloc` and the value of the - :const:`Py_TPFLAGS_HAVE_GC` flag bit. - - For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del. - - -.. c:member:: inquiry PyTypeObject.tp_is_gc - - An optional pointer to a function called by the garbage collector. - - The garbage collector needs to know whether a particular object is collectible - or not. Normally, it is sufficient to look at the object's type's - :c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But - some types have a mixture of statically and dynamically allocated instances, and - the statically allocated instances are not collectible. Such types should - define this function; it should return ``1`` for a collectible instance, and - ``0`` for a non-collectible instance. The signature is:: - - int tp_is_gc(PyObject *self); - - (The only example of this are types themselves. The metatype, - :c:data:`PyType_Type`, defines this function to distinguish between statically - and dynamically allocated types.) - - **Inheritance:** - - This field is inherited by subtypes. - - **Default:** - - This slot has no default. If this field is ``NULL``, - :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. - - -.. c:member:: PyObject* PyTypeObject.tp_bases - - Tuple of base types. - - This is set for types created by a class statement. It should be ``NULL`` for - statically defined types. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: PyObject* PyTypeObject.tp_mro - - Tuple containing the expanded set of base types, starting with the type itself - and ending with :class:`object`, in Method Resolution Order. - - - **Inheritance:** - - This field is not inherited; it is calculated fresh by - :c:func:`PyType_Ready`. - - -.. c:member:: PyObject* PyTypeObject.tp_cache - - Unused. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: PyObject* PyTypeObject.tp_subclasses - - List of weak references to subclasses. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: PyObject* PyTypeObject.tp_weaklist - - Weak reference list head, for weak references to this type object. Not - inherited. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: destructor PyTypeObject.tp_del - - This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead. - - -.. c:member:: unsigned int PyTypeObject.tp_version_tag - - Used to index into the method cache. Internal use only. - - **Inheritance:** - - This field is not inherited. - - -.. c:member:: destructor PyTypeObject.tp_finalize - - An optional pointer to an instance finalization function. Its signature is:: - - void tp_finalize(PyObject *self); - - If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when - finalizing an instance. It is called either from the garbage - collector (if the instance is part of an isolated reference cycle) or - just before the object is deallocated. Either way, it is guaranteed - to be called before attempting to break reference cycles, ensuring - that it finds the object in a sane state. - - :c:member:`~PyTypeObject.tp_finalize` should not mutate the current exception status; - therefore, a recommended way to write a non-trivial finalizer is:: - - static void - local_finalize(PyObject *self) - { - PyObject *error_type, *error_value, *error_traceback; - - /* Save the current exception, if any. */ - PyErr_Fetch(&error_type, &error_value, &error_traceback); - - /* ... */ - - /* Restore the saved exception. */ - PyErr_Restore(error_type, error_value, error_traceback); - } - - For this field to be taken into account (even through inheritance), - you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. - - **Inheritance:** - - This field is inherited by subtypes. - - .. versionadded:: 3.4 - - .. seealso:: "Safe object finalization" (:pep:`442`) - - -.. c:member:: vectorcallfunc PyTypeObject.tp_vectorcall - - Vectorcall function to use for calls of this type object. - In other words, it is used to implement - :ref:`vectorcall ` for ``type.__call__``. - If ``tp_vectorcall`` is ``NULL``, the default call implementation - using :attr:`__new__` and :attr:`__init__` is used. - - **Inheritance:** - - This field is never inherited. - - .. versionadded:: 3.9 (the field exists since 3.8 but it's only used since 3.9) - - -Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from -any Python thread, not just the thread which created the object (if the object -becomes part of a refcount cycle, that cycle might be collected by a garbage -collection on any thread). This is not a problem for Python API calls, since -the thread on which tp_dealloc is called will own the Global Interpreter Lock -(GIL). However, if the object being destroyed in turn destroys objects from some -other C or C++ library, care should be taken to ensure that destroying those -objects on the thread which called tp_dealloc will not violate any assumptions -of the library. - - -.. _heap-types: - -Heap Types ----------- - -Traditionally, types defined in C code are *static*, that is, -a static :c:type:`PyTypeObject` structure is defined directly in code -and initialized using :c:func:`PyType_Ready`. - -This results in types that are limited relative to types defined in Python: - -* Static types are limited to one base, i.e. they cannot use multiple - inheritance. -* Static type objects (but not necessarily their instances) are immutable. - It is not possible to add or modify the type object's attributes from Python. -* Static type objects are shared across - :ref:`sub-interpreters `, so they should not - include any subinterpreter-specific state. - -Also, since :c:type:`PyTypeObject` is not part of the :ref:`stable ABI `, -any extension modules using static types must be compiled for a specific -Python minor version. - -An alternative to static types is *heap-allocated types*, or *heap types* -for short, which correspond closely to classes created by Python's -``class`` statement. - -This is done by filling a :c:type:`PyType_Spec` structure and calling -:c:func:`PyType_FromSpecWithBases`. - - -.. _number-structs: - -Number Object Structures -======================== - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. c:type:: PyNumberMethods - - This structure holds pointers to the functions which an object uses to - implement the number protocol. Each function is used by the function of - similar name documented in the :ref:`number` section. - - .. XXX Drop the definition? - - Here is the structure definition:: - - typedef struct { - binaryfunc nb_add; - binaryfunc nb_subtract; - binaryfunc nb_multiply; - binaryfunc nb_remainder; - binaryfunc nb_divmod; - ternaryfunc nb_power; - unaryfunc nb_negative; - unaryfunc nb_positive; - unaryfunc nb_absolute; - inquiry nb_bool; - unaryfunc nb_invert; - binaryfunc nb_lshift; - binaryfunc nb_rshift; - binaryfunc nb_and; - binaryfunc nb_xor; - binaryfunc nb_or; - unaryfunc nb_int; - void *nb_reserved; - unaryfunc nb_float; - - binaryfunc nb_inplace_add; - binaryfunc nb_inplace_subtract; - binaryfunc nb_inplace_multiply; - binaryfunc nb_inplace_remainder; - ternaryfunc nb_inplace_power; - binaryfunc nb_inplace_lshift; - binaryfunc nb_inplace_rshift; - binaryfunc nb_inplace_and; - binaryfunc nb_inplace_xor; - binaryfunc nb_inplace_or; - - binaryfunc nb_floor_divide; - binaryfunc nb_true_divide; - binaryfunc nb_inplace_floor_divide; - binaryfunc nb_inplace_true_divide; - - unaryfunc nb_index; - - binaryfunc nb_matrix_multiply; - binaryfunc nb_inplace_matrix_multiply; - } PyNumberMethods; - - .. note:: - - Binary and ternary functions must check the type of all their operands, - and implement the necessary conversions (at least one of the operands is - an instance of the defined type). If the operation is not defined for the - given operands, binary and ternary functions must return - ``Py_NotImplemented``, if another error occurred they must return ``NULL`` - and set an exception. - - .. note:: - - The :c:data:`nb_reserved` field should always be ``NULL``. It - was previously called :c:data:`nb_long`, and was renamed in - Python 3.0.1. - -.. c:member:: binaryfunc PyNumberMethods.nb_add -.. c:member:: binaryfunc PyNumberMethods.nb_subtract -.. c:member:: binaryfunc PyNumberMethods.nb_multiply -.. c:member:: binaryfunc PyNumberMethods.nb_remainder -.. c:member:: binaryfunc PyNumberMethods.nb_divmod -.. c:member:: ternaryfunc PyNumberMethods.nb_power -.. c:member:: unaryfunc PyNumberMethods.nb_negative -.. c:member:: unaryfunc PyNumberMethods.nb_positive -.. c:member:: unaryfunc PyNumberMethods.nb_absolute -.. c:member:: inquiry PyNumberMethods.nb_bool -.. c:member:: unaryfunc PyNumberMethods.nb_invert -.. c:member:: binaryfunc PyNumberMethods.nb_lshift -.. c:member:: binaryfunc PyNumberMethods.nb_rshift -.. c:member:: binaryfunc PyNumberMethods.nb_and -.. c:member:: binaryfunc PyNumberMethods.nb_xor -.. c:member:: binaryfunc PyNumberMethods.nb_or -.. c:member:: unaryfunc PyNumberMethods.nb_int -.. c:member:: void *PyNumberMethods.nb_reserved -.. c:member:: unaryfunc PyNumberMethods.nb_float -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_add -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder -.. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_and -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_or -.. c:member:: binaryfunc PyNumberMethods.nb_floor_divide -.. c:member:: binaryfunc PyNumberMethods.nb_true_divide -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide -.. c:member:: unaryfunc PyNumberMethods.nb_index -.. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply -.. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply - - -.. _mapping-structs: - -Mapping Object Structures -========================= - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. c:type:: PyMappingMethods - - This structure holds pointers to the functions which an object uses to - implement the mapping protocol. It has three members: - -.. c:member:: lenfunc PyMappingMethods.mp_length - - This function is used by :c:func:`PyMapping_Size` and - :c:func:`PyObject_Size`, and has the same signature. This slot may be set to - ``NULL`` if the object has no defined length. - -.. c:member:: binaryfunc PyMappingMethods.mp_subscript - - This function is used by :c:func:`PyObject_GetItem` and - :c:func:`PySequence_GetSlice`, and has the same signature as - :c:func:`!PyObject_GetItem`. This slot must be filled for the - :c:func:`PyMapping_Check` function to return ``1``, it can be ``NULL`` - otherwise. - -.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript - - This function is used by :c:func:`PyObject_SetItem`, - :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and - :c:func:`PyObject_DelSlice`. It has the same signature as - :c:func:`!PyObject_SetItem`, but *v* can also be set to ``NULL`` to delete - an item. If this slot is ``NULL``, the object does not support item - assignment and deletion. - - -.. _sequence-structs: - -Sequence Object Structures -========================== - -.. sectionauthor:: Amaury Forgeot d'Arc - - -.. c:type:: PySequenceMethods - - This structure holds pointers to the functions which an object uses to - implement the sequence protocol. - -.. c:member:: lenfunc PySequenceMethods.sq_length - - This function is used by :c:func:`PySequence_Size` and - :c:func:`PyObject_Size`, and has the same signature. It is also used for - handling negative indices via the :c:member:`~PySequenceMethods.sq_item` - and the :c:member:`~PySequenceMethods.sq_ass_item` slots. - -.. c:member:: binaryfunc PySequenceMethods.sq_concat - - This function is used by :c:func:`PySequence_Concat` and has the same - signature. It is also used by the ``+`` operator, after trying the numeric - addition via the :c:member:`~PyNumberMethods.nb_add` slot. - -.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat - - This function is used by :c:func:`PySequence_Repeat` and has the same - signature. It is also used by the ``*`` operator, after trying numeric - multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot. - -.. c:member:: ssizeargfunc PySequenceMethods.sq_item - - This function is used by :c:func:`PySequence_GetItem` and has the same - signature. It is also used by :c:func:`PyObject_GetItem`, after trying - the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. - This slot must be filled for the :c:func:`PySequence_Check` - function to return ``1``, it can be ``NULL`` otherwise. - - Negative indexes are handled as follows: if the :attr:`sq_length` slot is - filled, it is called and the sequence length is used to compute a positive - index which is passed to :attr:`sq_item`. If :attr:`sq_length` is ``NULL``, - the index is passed as is to the function. - -.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item - - This function is used by :c:func:`PySequence_SetItem` and has the same - signature. It is also used by :c:func:`PyObject_SetItem` and - :c:func:`PyObject_DelItem`, after trying the item assignment and deletion - via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot. - This slot may be left to ``NULL`` if the object does not support - item assignment and deletion. - -.. c:member:: objobjproc PySequenceMethods.sq_contains - - This function may be used by :c:func:`PySequence_Contains` and has the same - signature. This slot may be left to ``NULL``, in this case - :c:func:`!PySequence_Contains` simply traverses the sequence until it - finds a match. - -.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat - - This function is used by :c:func:`PySequence_InPlaceConcat` and has the same - signature. It should modify its first operand, and return it. This slot - may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceConcat` - will fall back to :c:func:`PySequence_Concat`. It is also used by the - augmented assignment ``+=``, after trying numeric in-place addition - via the :c:member:`~PyNumberMethods.nb_inplace_add` slot. - -.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat - - This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same - signature. It should modify its first operand, and return it. This slot - may be left to ``NULL``, in this case :c:func:`!PySequence_InPlaceRepeat` - will fall back to :c:func:`PySequence_Repeat`. It is also used by the - augmented assignment ``*=``, after trying numeric in-place multiplication - via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot. - - -.. _buffer-structs: - -Buffer Object Structures -======================== - -.. sectionauthor:: Greg J. Stein -.. sectionauthor:: Benjamin Peterson -.. sectionauthor:: Stefan Krah - -.. c:type:: PyBufferProcs - - This structure holds pointers to the functions required by the - :ref:`Buffer protocol `. The protocol defines how - an exporter object can expose its internal data to consumer objects. - -.. c:member:: getbufferproc PyBufferProcs.bf_getbuffer - - The signature of this function is:: - - int (PyObject *exporter, Py_buffer *view, int flags); - - Handle a request to *exporter* to fill in *view* as specified by *flags*. - Except for point (3), an implementation of this function MUST take these - steps: - - (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, - set :c:data:`view->obj` to ``NULL`` and return ``-1``. - - (2) Fill in the requested fields. - - (3) Increment an internal counter for the number of exports. - - (4) Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`. - - (5) Return ``0``. - - If *exporter* is part of a chain or tree of buffer providers, two main - schemes can be used: - - * Re-export: Each member of the tree acts as the exporting object and - sets :c:data:`view->obj` to a new reference to itself. - - * Redirect: The buffer request is redirected to the root object of the - tree. Here, :c:data:`view->obj` will be a new reference to the root - object. - - The individual fields of *view* are described in section - :ref:`Buffer structure `, the rules how an exporter - must react to specific requests are in section - :ref:`Buffer request types `. - - All memory pointed to in the :c:type:`Py_buffer` structure belongs to - the exporter and must remain valid until there are no consumers left. - :c:member:`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, - :c:member:`~Py_buffer.strides`, :c:member:`~Py_buffer.suboffsets` - and :c:member:`~Py_buffer.internal` - are read-only for the consumer. - - :c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple - bytes buffer while dealing correctly with all request types. - - :c:func:`PyObject_GetBuffer` is the interface for the consumer that - wraps this function. - -.. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer - - The signature of this function is:: - - void (PyObject *exporter, Py_buffer *view); - - Handle a request to release the resources of the buffer. If no resources - need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be - ``NULL``. Otherwise, a standard implementation of this function will take - these optional steps: - - (1) Decrement an internal counter for the number of exports. - - (2) If the counter is ``0``, free all memory associated with *view*. - - The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep - track of buffer-specific resources. This field is guaranteed to remain - constant, while a consumer MAY pass a copy of the original buffer as the - *view* argument. - - - This function MUST NOT decrement :c:data:`view->obj`, since that is - done automatically in :c:func:`PyBuffer_Release` (this scheme is - useful for breaking reference cycles). - - - :c:func:`PyBuffer_Release` is the interface for the consumer that - wraps this function. - - -.. _async-structs: - - -Async Object Structures -======================= - -.. sectionauthor:: Yury Selivanov - -.. versionadded:: 3.5 - -.. c:type:: PyAsyncMethods - - This structure holds pointers to the functions required to implement - :term:`awaitable` and :term:`asynchronous iterator` objects. - - Here is the structure definition:: - - typedef struct { - unaryfunc am_await; - unaryfunc am_aiter; - unaryfunc am_anext; - } PyAsyncMethods; - -.. c:member:: unaryfunc PyAsyncMethods.am_await - - The signature of this function is:: - - PyObject *am_await(PyObject *self); - - The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must - return ``1`` for it. - - This slot may be set to ``NULL`` if an object is not an :term:`awaitable`. - -.. c:member:: unaryfunc PyAsyncMethods.am_aiter - - The signature of this function is:: - - PyObject *am_aiter(PyObject *self); - - Must return an :term:`awaitable` object. See :meth:`__anext__` for details. - - This slot may be set to ``NULL`` if an object does not implement - asynchronous iteration protocol. - -.. c:member:: unaryfunc PyAsyncMethods.am_anext - - The signature of this function is:: - - PyObject *am_anext(PyObject *self); - - Must return an :term:`awaitable` object. See :meth:`__anext__` for details. - This slot may be set to ``NULL``. - - -.. _slot-typedefs: - -Slot Type typedefs -================== - -.. c:type:: PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems) - - The purpose of this function is to separate memory allocation from memory - initialization. It should return a pointer to a block of memory of adequate - length for the instance, suitably aligned, and initialized to zeros, but with - :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If - the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field - should be initialized to *nitems* and the length of the allocated memory block - should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of - ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block - should be :c:member:`~PyTypeObject.tp_basicsize`. - - This function should not do any other instance initialization, not even to - allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`. - -.. c:type:: void (*destructor)(PyObject *) - -.. c:type:: void (*freefunc)(void *) - - See :c:member:`~PyTypeObject.tp_free`. - -.. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *) - - See :c:member:`~PyTypeObject.tp_new`. - -.. c:type:: int (*initproc)(PyObject *, PyObject *, PyObject *) - - See :c:member:`~PyTypeObject.tp_init`. - -.. c:type:: PyObject *(*reprfunc)(PyObject *) - - See :c:member:`~PyTypeObject.tp_repr`. - -.. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr) - - Return the value of the named attribute for the object. - -.. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value) - - Set the value of the named attribute for the object. - The value argument is set to ``NULL`` to delete the attribute. - -.. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr) - - Return the value of the named attribute for the object. - - See :c:member:`~PyTypeObject.tp_getattro`. - -.. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) - - Set the value of the named attribute for the object. - The value argument is set to ``NULL`` to delete the attribute. - - See :c:member:`~PyTypeObject.tp_setattro`. - -.. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *) - - See :c:member:`~PyTypeObject.tp_descrget`. - -.. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *) - - See :c:member:`~PyTypeObject.tp_descrset`. - -.. c:type:: Py_hash_t (*hashfunc)(PyObject *) - - See :c:member:`~PyTypeObject.tp_hash`. - -.. c:type:: PyObject *(*richcmpfunc)(PyObject *, PyObject *, int) - - See :c:member:`~PyTypeObject.tp_richcompare`. - -.. c:type:: PyObject *(*getiterfunc)(PyObject *) - - See :c:member:`~PyTypeObject.tp_iter`. - -.. c:type:: PyObject *(*iternextfunc)(PyObject *) - - See :c:member:`~PyTypeObject.tp_iternext`. - -.. c:type:: Py_ssize_t (*lenfunc)(PyObject *) - -.. c:type:: int (*getbufferproc)(PyObject *, Py_buffer *, int) - -.. c:type:: void (*releasebufferproc)(PyObject *, Py_buffer *) - -.. c:type:: PyObject *(*unaryfunc)(PyObject *) - -.. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *) - -.. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *) - -.. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t) - -.. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t) - -.. c:type:: int (*objobjproc)(PyObject *, PyObject *) - -.. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) - - -.. _typedef-examples: - -Examples -======== - -The following are simple examples of Python type definitions. They -include common usage you may encounter. Some demonstrate tricky corner -cases. For more examples, practical info, and a tutorial, see -:ref:`defining-new-types` and :ref:`new-types-topics`. - -A basic static type:: - - typedef struct { - PyObject_HEAD - const char *data; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", - .tp_new = myobj_new, - .tp_dealloc = (destructor)myobj_dealloc, - .tp_repr = (reprfunc)myobj_repr, - }; - -You may also find older code (especially in the CPython code base) -with a more verbose initializer:: - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - "mymod.MyObject", /* tp_name */ - sizeof(MyObject), /* tp_basicsize */ - 0, /* tp_itemsize */ - (destructor)myobj_dealloc, /* tp_dealloc */ - 0, /* tp_vectorcall_offset */ - 0, /* tp_getattr */ - 0, /* tp_setattr */ - 0, /* tp_as_async */ - (reprfunc)myobj_repr, /* tp_repr */ - 0, /* tp_as_number */ - 0, /* tp_as_sequence */ - 0, /* tp_as_mapping */ - 0, /* tp_hash */ - 0, /* tp_call */ - 0, /* tp_str */ - 0, /* tp_getattro */ - 0, /* tp_setattro */ - 0, /* tp_as_buffer */ - 0, /* tp_flags */ - "My objects", /* tp_doc */ - 0, /* tp_traverse */ - 0, /* tp_clear */ - 0, /* tp_richcompare */ - 0, /* tp_weaklistoffset */ - 0, /* tp_iter */ - 0, /* tp_iternext */ - 0, /* tp_methods */ - 0, /* tp_members */ - 0, /* tp_getset */ - 0, /* tp_base */ - 0, /* tp_dict */ - 0, /* tp_descr_get */ - 0, /* tp_descr_set */ - 0, /* tp_dictoffset */ - 0, /* tp_init */ - 0, /* tp_alloc */ - myobj_new, /* tp_new */ - }; - -A type that supports weakrefs, instance dicts, and hashing:: - - typedef struct { - PyObject_HEAD - const char *data; - PyObject *inst_dict; - PyObject *weakreflist; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject), - .tp_doc = "My objects", - .tp_weaklistoffset = offsetof(MyObject, weakreflist), - .tp_dictoffset = offsetof(MyObject, inst_dict), - .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, - .tp_new = myobj_new, - .tp_traverse = (traverseproc)myobj_traverse, - .tp_clear = (inquiry)myobj_clear, - .tp_alloc = PyType_GenericNew, - .tp_dealloc = (destructor)myobj_dealloc, - .tp_repr = (reprfunc)myobj_repr, - .tp_hash = (hashfunc)myobj_hash, - .tp_richcompare = PyBaseObject_Type.tp_richcompare, - }; - -A str subclass that cannot be subclassed and cannot be called -to create instances (e.g. uses a separate factory func):: - - typedef struct { - PyUnicodeObject raw; - char *extra; - } MyStr; - - static PyTypeObject MyStr_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyStr", - .tp_basicsize = sizeof(MyStr), - .tp_base = NULL, // set to &PyUnicode_Type in module init - .tp_doc = "my custom str", - .tp_flags = Py_TPFLAGS_DEFAULT, - .tp_new = NULL, - .tp_repr = (reprfunc)myobj_repr, - }; - -The simplest static type (with fixed-length instances):: - - typedef struct { - PyObject_HEAD - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - }; - -The simplest static type (with variable-length instances):: - - typedef struct { - PyObject_VAR_HEAD - const char *data[1]; - } MyObject; - - static PyTypeObject MyObject_Type = { - PyVarObject_HEAD_INIT(NULL, 0) - .tp_name = "mymod.MyObject", - .tp_basicsize = sizeof(MyObject) - sizeof(char *), - .tp_itemsize = sizeof(char *), - }; diff --git a/Doc/library/fractions.rst.bak b/Doc/library/fractions.rst.bak deleted file mode 100644 index d3a42762e3ff8d..00000000000000 --- a/Doc/library/fractions.rst.bak +++ /dev/null @@ -1,178 +0,0 @@ -:mod:`fractions` --- Rational numbers -===================================== - -.. module:: fractions - :synopsis: Rational numbers. - -.. moduleauthor:: Jeffrey Yasskin -.. sectionauthor:: Jeffrey Yasskin - -**Source code:** :source:`Lib/fractions.py` - --------------- - -The :mod:`fractions` module provides support for rational number arithmetic. - - -A Fraction instance can be constructed from a pair of integers, from -another rational number, or from a string. - -.. class:: Fraction(numerator=0, denominator=1) - Fraction(other_fraction) - Fraction(float) - Fraction(decimal) - Fraction(string) - - The first version requires that *numerator* and *denominator* are instances - of :class:`numbers.Rational` and returns a new :class:`Fraction` instance - with value ``numerator/denominator``. If *denominator* is :const:`0`, it - raises a :exc:`ZeroDivisionError`. The second version requires that - *other_fraction* is an instance of :class:`numbers.Rational` and returns a - :class:`Fraction` instance with the same value. The next two versions accept - either a :class:`float` or a :class:`decimal.Decimal` instance, and return a - :class:`Fraction` instance with exactly the same value. Note that due to the - usual issues with binary floating-point (see :ref:`tut-fp-issues`), the - argument to ``Fraction(1.1)`` is not exactly equal to 11/10, and so - ``Fraction(1.1)`` does *not* return ``Fraction(11, 10)`` as one might expect. - (But see the documentation for the :meth:`limit_denominator` method below.) - The last version of the constructor expects a string or unicode instance. - The usual form for this instance is:: - - [sign] numerator ['/' denominator] - - where the optional ``sign`` may be either '+' or '-' and - ``numerator`` and ``denominator`` (if present) are strings of - decimal digits. In addition, any string that represents a finite - value and is accepted by the :class:`float` constructor is also - accepted by the :class:`Fraction` constructor. In either form the - input string may also have leading and/or trailing whitespace. - Here are some examples:: - - >>> from fractions import Fraction - >>> Fraction(16, -10) - Fraction(-8, 5) - >>> Fraction(123) - Fraction(123, 1) - >>> Fraction() - Fraction(0, 1) - >>> Fraction('3/7') - Fraction(3, 7) - >>> Fraction(' -3/7 ') - Fraction(-3, 7) - >>> Fraction('1.414213 \t\n') - Fraction(1414213, 1000000) - >>> Fraction('-.125') - Fraction(-1, 8) - >>> Fraction('7e-6') - Fraction(7, 1000000) - >>> Fraction(2.25) - Fraction(9, 4) - >>> Fraction(1.1) - Fraction(2476979795053773, 2251799813685248) - >>> from decimal import Decimal - >>> Fraction(Decimal('1.1')) - Fraction(11, 10) - - - The :class:`Fraction` class inherits from the abstract base class - :class:`numbers.Rational`, and implements all of the methods and - operations from that class. :class:`Fraction` instances are hashable, - and should be treated as immutable. In addition, - :class:`Fraction` has the following properties and methods: - - .. versionchanged:: 3.2 - The :class:`Fraction` constructor now accepts :class:`float` and - :class:`decimal.Decimal` instances. - - - .. attribute:: numerator - - Numerator of the Fraction in lowest term. - - .. attribute:: denominator - - Denominator of the Fraction in lowest term. - - - .. method:: as_integer_ratio() - - Return a tuple of two integers, whose ratio is equal - to the Fraction and with a positive denominator. - - .. versionadded:: 3.8 - - .. method:: from_float(flt) - - This class method constructs a :class:`Fraction` representing the exact - value of *flt*, which must be a :class:`float`. Beware that - ``Fraction.from_float(0.3)`` is not the same value as ``Fraction(3, 10)``. - - .. note:: - - From Python 3.2 onwards, you can also construct a - :class:`Fraction` instance directly from a :class:`float`. - - - .. method:: from_decimal(dec) - - This class method constructs a :class:`Fraction` representing the exact - value of *dec*, which must be a :class:`decimal.Decimal` instance. - - .. note:: - - From Python 3.2 onwards, you can also construct a - :class:`Fraction` instance directly from a :class:`decimal.Decimal` - instance. - - - .. method:: limit_denominator(max_denominator=1000000) - - Finds and returns the closest :class:`Fraction` to ``self`` that has - denominator at most max_denominator. This method is useful for finding - rational approximations to a given floating-point number: - - >>> from fractions import Fraction - >>> Fraction('3.1415926535897932').limit_denominator(1000) - Fraction(355, 113) - - or for recovering a rational number that's represented as a float: - - >>> from math import pi, cos - >>> Fraction(cos(pi/3)) - Fraction(4503599627370497, 9007199254740992) - >>> Fraction(cos(pi/3)).limit_denominator() - Fraction(1, 2) - >>> Fraction(1.1).limit_denominator() - Fraction(11, 10) - - - .. method:: __floor__() - - Returns the greatest :class:`int` ``<= self``. This method can - also be accessed through the :func:`math.floor` function: - - >>> from math import floor - >>> floor(Fraction(355, 113)) - 3 - - - .. method:: __ceil__() - - Returns the least :class:`int` ``>= self``. This method can - also be accessed through the :func:`math.ceil` function. - - - .. method:: __round__() - __round__(ndigits) - - The first version returns the nearest :class:`int` to ``self``, - rounding half to even. The second version rounds ``self`` to the - nearest multiple of ``Fraction(1, 10**ndigits)`` (logically, if - ``ndigits`` is negative), again rounding half toward even. This - method can also be accessed through the :func:`round` function. - - -.. seealso:: - - Module :mod:`numbers` - The abstract base classes making up the numeric tower. diff --git a/Doc/library/os.rst.bak b/Doc/library/os.rst.bak deleted file mode 100644 index f59423c6f2d4ee..00000000000000 --- a/Doc/library/os.rst.bak +++ /dev/null @@ -1,4513 +0,0 @@ -:mod:`os` --- Miscellaneous operating system interfaces -======================================================= - -.. module:: os - :synopsis: Miscellaneous operating system interfaces. - -**Source code:** :source:`Lib/os.py` - --------------- - -This module provides a portable way of using operating system dependent -functionality. If you just want to read or write a file see :func:`open`, if -you want to manipulate paths, see the :mod:`os.path` module, and if you want to -read all the lines in all the files on the command line see the :mod:`fileinput` -module. For creating temporary files and directories see the :mod:`tempfile` -module, and for high-level file and directory handling see the :mod:`shutil` -module. - -Notes on the availability of these functions: - -* The design of all built-in operating system dependent modules of Python is - such that as long as the same functionality is available, it uses the same - interface; for example, the function ``os.stat(path)`` returns stat - information about *path* in the same format (which happens to have originated - with the POSIX interface). - -* Extensions peculiar to a particular operating system are also available - through the :mod:`os` module, but using them is of course a threat to - portability. - -* All functions accepting path or file names accept both bytes and string - objects, and result in an object of the same type, if a path or file name is - returned. - -* On VxWorks, os.fork, os.execv and os.spawn*p* are not supported. - -.. note:: - - All functions in this module raise :exc:`OSError` (or subclasses thereof) in - the case of invalid or inaccessible file names and paths, or other arguments - that have the correct type, but are not accepted by the operating system. - -.. exception:: error - - An alias for the built-in :exc:`OSError` exception. - - -.. data:: name - - The name of the operating system dependent module imported. The following - names have currently been registered: ``'posix'``, ``'nt'``, - ``'java'``. - - .. seealso:: - :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives - system-dependent version information. - - The :mod:`platform` module provides detailed checks for the - system's identity. - - -.. _os-filenames: -.. _filesystem-encoding: - -File Names, Command Line Arguments, and Environment Variables -------------------------------------------------------------- - -In Python, file names, command line arguments, and environment variables are -represented using the string type. On some systems, decoding these strings to -and from bytes is necessary before passing them to the operating system. Python -uses the file system encoding to perform this conversion (see -:func:`sys.getfilesystemencoding`). - -.. versionchanged:: 3.1 - On some systems, conversion using the file system encoding may fail. In this - case, Python uses the :ref:`surrogateescape encoding error handler - `, which means that undecodable bytes are replaced by a - Unicode character U+DCxx on decoding, and these are again translated to the - original byte on encoding. - - -The file system encoding must guarantee to successfully decode all bytes -below 128. If the file system encoding fails to provide this guarantee, API -functions may raise UnicodeErrors. - - -.. _os-procinfo: - -Process Parameters ------------------- - -These functions and data items provide information and operate on the current -process and user. - - -.. function:: ctermid() - - Return the filename corresponding to the controlling terminal of the process. - - .. availability:: Unix. - - -.. data:: environ - - A :term:`mapping` object representing the string environment. For example, - ``environ['HOME']`` is the pathname of your home directory (on some platforms), - and is equivalent to ``getenv("HOME")`` in C. - - This mapping is captured the first time the :mod:`os` module is imported, - typically during Python startup as part of processing :file:`site.py`. Changes - to the environment made after this time are not reflected in ``os.environ``, - except for changes made by modifying ``os.environ`` directly. - - This mapping may be used to modify the environment as well as query the - environment. :func:`putenv` will be called automatically when the mapping - is modified. - - On Unix, keys and values use :func:`sys.getfilesystemencoding` and - ``'surrogateescape'`` error handler. Use :data:`environb` if you would like - to use a different encoding. - - .. note:: - - Calling :func:`putenv` directly does not change ``os.environ``, so it's better - to modify ``os.environ``. - - .. note:: - - On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may - cause memory leaks. Refer to the system documentation for - :c:func:`putenv`. - - You can delete items in this mapping to unset environment variables. - :func:`unsetenv` will be called automatically when an item is deleted from - ``os.environ``, and when one of the :meth:`pop` or :meth:`clear` methods is - called. - - -.. data:: environb - - Bytes version of :data:`environ`: a :term:`mapping` object representing the - environment as byte strings. :data:`environ` and :data:`environb` are - synchronized (modify :data:`environb` updates :data:`environ`, and vice - versa). - - :data:`environb` is only available if :data:`supports_bytes_environ` is - ``True``. - - .. versionadded:: 3.2 - - -.. function:: chdir(path) - fchdir(fd) - getcwd() - :noindex: - - These functions are described in :ref:`os-file-dir`. - - -.. function:: fsencode(filename) - - Encode :term:`path-like ` *filename* to the filesystem - encoding with ``'surrogateescape'`` error handler, or ``'strict'`` on - Windows; return :class:`bytes` unchanged. - - :func:`fsdecode` is the reverse function. - - .. versionadded:: 3.2 - - .. versionchanged:: 3.6 - Support added to accept objects implementing the :class:`os.PathLike` - interface. - - -.. function:: fsdecode(filename) - - Decode the :term:`path-like ` *filename* from the - filesystem encoding with ``'surrogateescape'`` error handler, or ``'strict'`` - on Windows; return :class:`str` unchanged. - - :func:`fsencode` is the reverse function. - - .. versionadded:: 3.2 - - .. versionchanged:: 3.6 - Support added to accept objects implementing the :class:`os.PathLike` - interface. - - -.. function:: fspath(path) - - Return the file system representation of the path. - - If :class:`str` or :class:`bytes` is passed in, it is returned unchanged. - Otherwise :meth:`~os.PathLike.__fspath__` is called and its value is - returned as long as it is a :class:`str` or :class:`bytes` object. - In all other cases, :exc:`TypeError` is raised. - - .. versionadded:: 3.6 - - -.. class:: PathLike - - An :term:`abstract base class` for objects representing a file system path, - e.g. :class:`pathlib.PurePath`. - - .. versionadded:: 3.6 - - .. abstractmethod:: __fspath__() - - Return the file system path representation of the object. - - The method should only return a :class:`str` or :class:`bytes` object, - with the preference being for :class:`str`. - - -.. function:: getenv(key, default=None) - - Return the value of the environment variable *key* if it exists, or - *default* if it doesn't. *key*, *default* and the result are str. - - On Unix, keys and values are decoded with :func:`sys.getfilesystemencoding` - and ``'surrogateescape'`` error handler. Use :func:`os.getenvb` if you - would like to use a different encoding. - - .. availability:: most flavors of Unix, Windows. - - -.. function:: getenvb(key, default=None) - - Return the value of the environment variable *key* if it exists, or - *default* if it doesn't. *key*, *default* and the result are bytes. - - :func:`getenvb` is only available if :data:`supports_bytes_environ` - is ``True``. - - .. availability:: most flavors of Unix. - - .. versionadded:: 3.2 - - -.. function:: get_exec_path(env=None) - - Returns the list of directories that will be searched for a named - executable, similar to a shell, when launching a process. - *env*, when specified, should be an environment variable dictionary - to lookup the PATH in. - By default, when *env* is ``None``, :data:`environ` is used. - - .. versionadded:: 3.2 - - -.. function:: getegid() - - Return the effective group id of the current process. This corresponds to the - "set id" bit on the file being executed in the current process. - - .. availability:: Unix. - - -.. function:: geteuid() - - .. index:: single: user; effective id - - Return the current process's effective user id. - - .. availability:: Unix. - - -.. function:: getgid() - - .. index:: single: process; group - - Return the real group id of the current process. - - .. availability:: Unix. - - -.. function:: getgrouplist(user, group) - - Return list of group ids that *user* belongs to. If *group* is not in the - list, it is included; typically, *group* is specified as the group ID - field from the password record for *user*. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: getgroups() - - Return list of supplemental group ids associated with the current process. - - .. availability:: Unix. - - .. note:: - - On Mac OS X, :func:`getgroups` behavior differs somewhat from - other Unix platforms. If the Python interpreter was built with a - deployment target of :const:`10.5` or earlier, :func:`getgroups` returns - the list of effective group ids associated with the current user process; - this list is limited to a system-defined number of entries, typically 16, - and may be modified by calls to :func:`setgroups` if suitably privileged. - If built with a deployment target greater than :const:`10.5`, - :func:`getgroups` returns the current group access list for the user - associated with the effective user id of the process; the group access - list may change over the lifetime of the process, it is not affected by - calls to :func:`setgroups`, and its length is not limited to 16. The - deployment target value, :const:`MACOSX_DEPLOYMENT_TARGET`, can be - obtained with :func:`sysconfig.get_config_var`. - - -.. function:: getlogin() - - Return the name of the user logged in on the controlling terminal of the - process. For most purposes, it is more useful to use - :func:`getpass.getuser` since the latter checks the environment variables - :envvar:`LOGNAME` or :envvar:`USERNAME` to find out who the user is, and - falls back to ``pwd.getpwuid(os.getuid())[0]`` to get the login name of the - current real user id. - - .. availability:: Unix, Windows. - - -.. function:: getpgid(pid) - - Return the process group id of the process with process id *pid*. If *pid* is 0, - the process group id of the current process is returned. - - .. availability:: Unix. - -.. function:: getpgrp() - - .. index:: single: process; group - - Return the id of the current process group. - - .. availability:: Unix. - - -.. function:: getpid() - - .. index:: single: process; id - - Return the current process id. - - -.. function:: getppid() - - .. index:: single: process; id of parent - - Return the parent's process id. When the parent process has exited, on Unix - the id returned is the one of the init process (1), on Windows it is still - the same id, which may be already reused by another process. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.2 - Added support for Windows. - - -.. function:: getpriority(which, who) - - .. index:: single: process; scheduling priority - - Get program scheduling priority. The value *which* is one of - :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* - is interpreted relative to *which* (a process identifier for - :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a - user ID for :const:`PRIO_USER`). A zero value for *who* denotes - (respectively) the calling process, the process group of the calling process, - or the real user ID of the calling process. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. data:: PRIO_PROCESS - PRIO_PGRP - PRIO_USER - - Parameters for the :func:`getpriority` and :func:`setpriority` functions. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: getresuid() - - Return a tuple (ruid, euid, suid) denoting the current process's - real, effective, and saved user ids. - - .. availability:: Unix. - - .. versionadded:: 3.2 - - -.. function:: getresgid() - - Return a tuple (rgid, egid, sgid) denoting the current process's - real, effective, and saved group ids. - - .. availability:: Unix. - - .. versionadded:: 3.2 - - -.. function:: getuid() - - .. index:: single: user; id - - Return the current process's real user id. - - .. availability:: Unix. - - -.. function:: initgroups(username, gid) - - Call the system initgroups() to initialize the group access list with all of - the groups of which the specified username is a member, plus the specified - group id. - - .. availability:: Unix. - - .. versionadded:: 3.2 - - -.. function:: putenv(key, value) - - .. index:: single: environment variables; setting - - Set the environment variable named *key* to the string *value*. Such - changes to the environment affect subprocesses started with :func:`os.system`, - :func:`popen` or :func:`fork` and :func:`execv`. - - Assignments to items in ``os.environ`` are automatically translated into - corresponding calls to :func:`putenv`; however, calls to :func:`putenv` - don't update ``os.environ``, so it is actually preferable to assign to items - of ``os.environ``. - - .. note:: - - On some platforms, including FreeBSD and Mac OS X, setting ``environ`` may - cause memory leaks. Refer to the system documentation for :c:func:`putenv`. - - .. versionchanged:: 3.9 - The function is now always available. - - -.. function:: setegid(egid) - - Set the current process's effective group id. - - .. availability:: Unix. - - -.. function:: seteuid(euid) - - Set the current process's effective user id. - - .. availability:: Unix. - - -.. function:: setgid(gid) - - Set the current process' group id. - - .. availability:: Unix. - - -.. function:: setgroups(groups) - - Set the list of supplemental group ids associated with the current process to - *groups*. *groups* must be a sequence, and each element must be an integer - identifying a group. This operation is typically available only to the superuser. - - .. availability:: Unix. - - .. note:: On Mac OS X, the length of *groups* may not exceed the - system-defined maximum number of effective group ids, typically 16. - See the documentation for :func:`getgroups` for cases where it may not - return the same group list set by calling setgroups(). - -.. function:: setpgrp() - - Call the system call :c:func:`setpgrp` or ``setpgrp(0, 0)`` depending on - which version is implemented (if any). See the Unix manual for the semantics. - - .. availability:: Unix. - - -.. function:: setpgid(pid, pgrp) - - Call the system call :c:func:`setpgid` to set the process group id of the - process with id *pid* to the process group with id *pgrp*. See the Unix manual - for the semantics. - - .. availability:: Unix. - - -.. function:: setpriority(which, who, priority) - - .. index:: single: process; scheduling priority - - Set program scheduling priority. The value *which* is one of - :const:`PRIO_PROCESS`, :const:`PRIO_PGRP`, or :const:`PRIO_USER`, and *who* - is interpreted relative to *which* (a process identifier for - :const:`PRIO_PROCESS`, process group identifier for :const:`PRIO_PGRP`, and a - user ID for :const:`PRIO_USER`). A zero value for *who* denotes - (respectively) the calling process, the process group of the calling process, - or the real user ID of the calling process. - *priority* is a value in the range -20 to 19. The default priority is 0; - lower priorities cause more favorable scheduling. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: setregid(rgid, egid) - - Set the current process's real and effective group ids. - - .. availability:: Unix. - - -.. function:: setresgid(rgid, egid, sgid) - - Set the current process's real, effective, and saved group ids. - - .. availability:: Unix. - - .. versionadded:: 3.2 - - -.. function:: setresuid(ruid, euid, suid) - - Set the current process's real, effective, and saved user ids. - - .. availability:: Unix. - - .. versionadded:: 3.2 - - -.. function:: setreuid(ruid, euid) - - Set the current process's real and effective user ids. - - .. availability:: Unix. - - -.. function:: getsid(pid) - - Call the system call :c:func:`getsid`. See the Unix manual for the semantics. - - .. availability:: Unix. - - -.. function:: setsid() - - Call the system call :c:func:`setsid`. See the Unix manual for the semantics. - - .. availability:: Unix. - - -.. function:: setuid(uid) - - .. index:: single: user; id, setting - - Set the current process's user id. - - .. availability:: Unix. - - -.. placed in this section since it relates to errno.... a little weak -.. function:: strerror(code) - - Return the error message corresponding to the error code in *code*. - On platforms where :c:func:`strerror` returns ``NULL`` when given an unknown - error number, :exc:`ValueError` is raised. - - -.. data:: supports_bytes_environ - - ``True`` if the native OS type of the environment is bytes (eg. ``False`` on - Windows). - - .. versionadded:: 3.2 - - -.. function:: umask(mask) - - Set the current numeric umask and return the previous umask. - - -.. function:: uname() - - .. index:: - single: gethostname() (in module socket) - single: gethostbyaddr() (in module socket) - - Returns information identifying the current operating system. - The return value is an object with five attributes: - - * :attr:`sysname` - operating system name - * :attr:`nodename` - name of machine on network (implementation-defined) - * :attr:`release` - operating system release - * :attr:`version` - operating system version - * :attr:`machine` - hardware identifier - - For backwards compatibility, this object is also iterable, behaving - like a five-tuple containing :attr:`sysname`, :attr:`nodename`, - :attr:`release`, :attr:`version`, and :attr:`machine` - in that order. - - Some systems truncate :attr:`nodename` to 8 characters or to the - leading component; a better way to get the hostname is - :func:`socket.gethostname` or even - ``socket.gethostbyaddr(socket.gethostname())``. - - .. availability:: recent flavors of Unix. - - .. versionchanged:: 3.3 - Return type changed from a tuple to a tuple-like object - with named attributes. - - -.. function:: unsetenv(key) - - .. index:: single: environment variables; deleting - - Unset (delete) the environment variable named *key*. Such changes to the - environment affect subprocesses started with :func:`os.system`, :func:`popen` or - :func:`fork` and :func:`execv`. - - Deletion of items in ``os.environ`` is automatically translated into a - corresponding call to :func:`unsetenv`; however, calls to :func:`unsetenv` - don't update ``os.environ``, so it is actually preferable to delete items of - ``os.environ``. - - .. versionchanged:: 3.9 - The function is now always available and is also available on Windows. - - -.. _os-newstreams: - -File Object Creation --------------------- - -These functions create new :term:`file objects `. (See also -:func:`~os.open` for opening file descriptors.) - - -.. function:: fdopen(fd, *args, **kwargs) - - Return an open file object connected to the file descriptor *fd*. This is an - alias of the :func:`open` built-in function and accepts the same arguments. - The only difference is that the first argument of :func:`fdopen` must always - be an integer. - - -.. _os-fd-ops: - -File Descriptor Operations --------------------------- - -These functions operate on I/O streams referenced using file descriptors. - -File descriptors are small integers corresponding to a file that has been opened -by the current process. For example, standard input is usually file descriptor -0, standard output is 1, and standard error is 2. Further files opened by a -process will then be assigned 3, 4, 5, and so forth. The name "file descriptor" -is slightly deceptive; on Unix platforms, sockets and pipes are also referenced -by file descriptors. - -The :meth:`~io.IOBase.fileno` method can be used to obtain the file descriptor -associated with a :term:`file object` when required. Note that using the file -descriptor directly will bypass the file object methods, ignoring aspects such -as internal buffering of data. - - -.. function:: close(fd) - - Close file descriptor *fd*. - - .. note:: - - This function is intended for low-level I/O and must be applied to a file - descriptor as returned by :func:`os.open` or :func:`pipe`. To close a "file - object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, use its :meth:`~io.IOBase.close` method. - - -.. function:: closerange(fd_low, fd_high) - - Close all file descriptors from *fd_low* (inclusive) to *fd_high* (exclusive), - ignoring errors. Equivalent to (but much faster than):: - - for fd in range(fd_low, fd_high): - try: - os.close(fd) - except OSError: - pass - - -.. function:: copy_file_range(src, dst, count, offset_src=None, offset_dst=None) - - Copy *count* bytes from file descriptor *src*, starting from offset - *offset_src*, to file descriptor *dst*, starting from offset *offset_dst*. - If *offset_src* is None, then *src* is read from the current position; - respectively for *offset_dst*. The files pointed by *src* and *dst* - must reside in the same filesystem, otherwise an :exc:`OSError` is - raised with :attr:`~OSError.errno` set to :data:`errno.EXDEV`. - - This copy is done without the additional cost of transferring data - from the kernel to user space and then back into the kernel. Additionally, - some filesystems could implement extra optimizations. The copy is done as if - both files are opened as binary. - - The return value is the amount of bytes copied. This could be less than the - amount requested. - - .. availability:: Linux kernel >= 4.5 or glibc >= 2.27. - - .. versionadded:: 3.8 - - -.. function:: device_encoding(fd) - - Return a string describing the encoding of the device associated with *fd* - if it is connected to a terminal; else return :const:`None`. - - -.. function:: dup(fd) - - Return a duplicate of file descriptor *fd*. The new file descriptor is - :ref:`non-inheritable `. - - On Windows, when duplicating a standard stream (0: stdin, 1: stdout, - 2: stderr), the new file descriptor is :ref:`inheritable - `. - - .. versionchanged:: 3.4 - The new file descriptor is now non-inheritable. - - -.. function:: dup2(fd, fd2, inheritable=True) - - Duplicate file descriptor *fd* to *fd2*, closing the latter first if - necessary. Return *fd2*. The new file descriptor is :ref:`inheritable - ` by default or non-inheritable if *inheritable* - is ``False``. - - .. versionchanged:: 3.4 - Add the optional *inheritable* parameter. - - .. versionchanged:: 3.7 - Return *fd2* on success. Previously, ``None`` was always returned. - - -.. function:: fchmod(fd, mode) - - Change the mode of the file given by *fd* to the numeric *mode*. See the - docs for :func:`chmod` for possible values of *mode*. As of Python 3.3, this - is equivalent to ``os.chmod(fd, mode)``. - - .. availability:: Unix. - - -.. function:: fchown(fd, uid, gid) - - Change the owner and group id of the file given by *fd* to the numeric *uid* - and *gid*. To leave one of the ids unchanged, set it to -1. See - :func:`chown`. As of Python 3.3, this is equivalent to ``os.chown(fd, uid, - gid)``. - - .. availability:: Unix. - - -.. function:: fdatasync(fd) - - Force write of file with filedescriptor *fd* to disk. Does not force update of - metadata. - - .. availability:: Unix. - - .. note:: - This function is not available on MacOS. - - -.. function:: fpathconf(fd, name) - - Return system configuration information relevant to an open file. *name* - specifies the configuration value to retrieve; it may be a string which is the - name of a defined system value; these names are specified in a number of - standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define - additional names as well. The names known to the host operating system are - given in the ``pathconf_names`` dictionary. For configuration variables not - included in that mapping, passing an integer for *name* is also accepted. - - If *name* is a string and is not known, :exc:`ValueError` is raised. If a - specific value for *name* is not supported by the host system, even if it is - included in ``pathconf_names``, an :exc:`OSError` is raised with - :const:`errno.EINVAL` for the error number. - - As of Python 3.3, this is equivalent to ``os.pathconf(fd, name)``. - - .. availability:: Unix. - - -.. function:: fstat(fd) - - Get the status of the file descriptor *fd*. Return a :class:`stat_result` - object. - - As of Python 3.3, this is equivalent to ``os.stat(fd)``. - - .. seealso:: - - The :func:`.stat` function. - - -.. function:: fstatvfs(fd) - - Return information about the filesystem containing the file associated with - file descriptor *fd*, like :func:`statvfs`. As of Python 3.3, this is - equivalent to ``os.statvfs(fd)``. - - .. availability:: Unix. - - -.. function:: fsync(fd) - - Force write of file with filedescriptor *fd* to disk. On Unix, this calls the - native :c:func:`fsync` function; on Windows, the MS :c:func:`_commit` function. - - If you're starting with a buffered Python :term:`file object` *f*, first do - ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal - buffers associated with *f* are written to disk. - - .. availability:: Unix, Windows. - - -.. function:: ftruncate(fd, length) - - Truncate the file corresponding to file descriptor *fd*, so that it is at - most *length* bytes in size. As of Python 3.3, this is equivalent to - ``os.truncate(fd, length)``. - - .. audit-event:: os.truncate fd,length os.ftruncate - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.5 - Added support for Windows - - -.. function:: get_blocking(fd) - - Get the blocking mode of the file descriptor: ``False`` if the - :data:`O_NONBLOCK` flag is set, ``True`` if the flag is cleared. - - See also :func:`set_blocking` and :meth:`socket.socket.setblocking`. - - .. availability:: Unix. - - .. versionadded:: 3.5 - - -.. function:: isatty(fd) - - Return ``True`` if the file descriptor *fd* is open and connected to a - tty(-like) device, else ``False``. - - -.. function:: lockf(fd, cmd, len) - - Apply, test or remove a POSIX lock on an open file descriptor. - *fd* is an open file descriptor. - *cmd* specifies the command to use - one of :data:`F_LOCK`, :data:`F_TLOCK`, - :data:`F_ULOCK` or :data:`F_TEST`. - *len* specifies the section of the file to lock. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. data:: F_LOCK - F_TLOCK - F_ULOCK - F_TEST - - Flags that specify what action :func:`lockf` will take. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: lseek(fd, pos, how) - - Set the current position of file descriptor *fd* to position *pos*, modified - by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the - beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the - current position; :const:`SEEK_END` or ``2`` to set it relative to the end of - the file. Return the new cursor position in bytes, starting from the beginning. - - -.. data:: SEEK_SET - SEEK_CUR - SEEK_END - - Parameters to the :func:`lseek` function. Their values are 0, 1, and 2, - respectively. - - .. versionadded:: 3.3 - Some operating systems could support additional values, like - :data:`os.SEEK_HOLE` or :data:`os.SEEK_DATA`. - - -.. function:: open(path, flags, mode=0o777, *, dir_fd=None) - - Open the file *path* and set various flags according to *flags* and possibly - its mode according to *mode*. When computing *mode*, the current umask value - is first masked out. Return the file descriptor for the newly opened file. - The new file descriptor is :ref:`non-inheritable `. - - For a description of the flag and mode values, see the C run-time documentation; - flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in - the :mod:`os` module. In particular, on Windows adding - :const:`O_BINARY` is needed to open files in binary mode. - - This function can support :ref:`paths relative to directory descriptors - ` with the *dir_fd* parameter. - - .. audit-event:: open path,mode,flags os.open - - .. versionchanged:: 3.4 - The new file descriptor is now non-inheritable. - - .. note:: - - This function is intended for low-level I/O. For normal usage, use the - built-in function :func:`open`, which returns a :term:`file object` with - :meth:`~file.read` and :meth:`~file.write` methods (and many more). To - wrap a file descriptor in a file object, use :func:`fdopen`. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.5 - If the system call is interrupted and the signal handler does not raise an - exception, the function now retries the system call instead of raising an - :exc:`InterruptedError` exception (see :pep:`475` for the rationale). - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - -The following constants are options for the *flags* parameter to the -:func:`~os.open` function. They can be combined using the bitwise OR operator -``|``. Some of them are not available on all platforms. For descriptions of -their availability and use, consult the :manpage:`open(2)` manual page on Unix -or `the MSDN `_ on Windows. - - -.. data:: O_RDONLY - O_WRONLY - O_RDWR - O_APPEND - O_CREAT - O_EXCL - O_TRUNC - - The above constants are available on Unix and Windows. - - -.. data:: O_DSYNC - O_RSYNC - O_SYNC - O_NDELAY - O_NONBLOCK - O_NOCTTY - O_CLOEXEC - - The above constants are only available on Unix. - - .. versionchanged:: 3.3 - Add :data:`O_CLOEXEC` constant. - -.. data:: O_BINARY - O_NOINHERIT - O_SHORT_LIVED - O_TEMPORARY - O_RANDOM - O_SEQUENTIAL - O_TEXT - - The above constants are only available on Windows. - - -.. data:: O_ASYNC - O_DIRECT - O_DIRECTORY - O_NOFOLLOW - O_NOATIME - O_PATH - O_TMPFILE - O_SHLOCK - O_EXLOCK - - The above constants are extensions and not present if they are not defined by - the C library. - - .. versionchanged:: 3.4 - Add :data:`O_PATH` on systems that support it. - Add :data:`O_TMPFILE`, only available on Linux Kernel 3.11 - or newer. - - -.. function:: openpty() - - .. index:: module: pty - - Open a new pseudo-terminal pair. Return a pair of file descriptors - ``(master, slave)`` for the pty and the tty, respectively. The new file - descriptors are :ref:`non-inheritable `. For a (slightly) more - portable approach, use the :mod:`pty` module. - - .. availability:: some flavors of Unix. - - .. versionchanged:: 3.4 - The new file descriptors are now non-inheritable. - - -.. function:: pipe() - - Create a pipe. Return a pair of file descriptors ``(r, w)`` usable for - reading and writing, respectively. The new file descriptor is - :ref:`non-inheritable `. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.4 - The new file descriptors are now non-inheritable. - - -.. function:: pipe2(flags) - - Create a pipe with *flags* set atomically. - *flags* can be constructed by ORing together one or more of these values: - :data:`O_NONBLOCK`, :data:`O_CLOEXEC`. - Return a pair of file descriptors ``(r, w)`` usable for reading and writing, - respectively. - - .. availability:: some flavors of Unix. - - .. versionadded:: 3.3 - - -.. function:: posix_fallocate(fd, offset, len) - - Ensures that enough disk space is allocated for the file specified by *fd* - starting from *offset* and continuing for *len* bytes. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: posix_fadvise(fd, offset, len, advice) - - Announces an intention to access data in a specific pattern thus allowing - the kernel to make optimizations. - The advice applies to the region of the file specified by *fd* starting at - *offset* and continuing for *len* bytes. - *advice* is one of :data:`POSIX_FADV_NORMAL`, :data:`POSIX_FADV_SEQUENTIAL`, - :data:`POSIX_FADV_RANDOM`, :data:`POSIX_FADV_NOREUSE`, - :data:`POSIX_FADV_WILLNEED` or :data:`POSIX_FADV_DONTNEED`. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. data:: POSIX_FADV_NORMAL - POSIX_FADV_SEQUENTIAL - POSIX_FADV_RANDOM - POSIX_FADV_NOREUSE - POSIX_FADV_WILLNEED - POSIX_FADV_DONTNEED - - Flags that can be used in *advice* in :func:`posix_fadvise` that specify - the access pattern that is likely to be used. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: pread(fd, n, offset) - - Read at most *n* bytes from file descriptor *fd* at a position of *offset*, - leaving the file offset unchanged. - - Return a bytestring containing the bytes read. If the end of the file - referred to by *fd* has been reached, an empty bytes object is returned. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: preadv(fd, buffers, offset, flags=0) - - Read from a file descriptor *fd* at a position of *offset* into mutable - :term:`bytes-like objects ` *buffers*, leaving the file - offset unchanged. Transfer data into each buffer until it is full and then - move on to the next buffer in the sequence to hold the rest of the data. - - The flags argument contains a bitwise OR of zero or more of the following - flags: - - - :data:`RWF_HIPRI` - - :data:`RWF_NOWAIT` - - Return the total number of bytes actually read which can be less than the - total capacity of all the objects. - - The operating system may set a limit (:func:`sysconf` value - ``'SC_IOV_MAX'``) on the number of buffers that can be used. - - Combine the functionality of :func:`os.readv` and :func:`os.pread`. - - .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, - OpenBSD 2.7 and newer. Using flags requires Linux 4.6 or newer. - - .. versionadded:: 3.7 - - -.. data:: RWF_NOWAIT - - Do not wait for data which is not immediately available. If this flag is - specified, the system call will return instantly if it would have to read - data from the backing storage or wait for a lock. - - If some data was successfully read, it will return the number of bytes read. - If no bytes were read, it will return ``-1`` and set errno to - :data:`errno.EAGAIN`. - - .. availability:: Linux 4.14 and newer. - - .. versionadded:: 3.7 - - -.. data:: RWF_HIPRI - - High priority read/write. Allows block-based filesystems to use polling - of the device, which provides lower latency, but may use additional - resources. - - Currently, on Linux, this feature is usable only on a file descriptor opened - using the :data:`O_DIRECT` flag. - - .. availability:: Linux 4.6 and newer. - - .. versionadded:: 3.7 - - -.. function:: pwrite(fd, str, offset) - - Write the bytestring in *str* to file descriptor *fd* at position of - *offset*, leaving the file offset unchanged. - - Return the number of bytes actually written. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: pwritev(fd, buffers, offset, flags=0) - - Write the *buffers* contents to file descriptor *fd* at a offset *offset*, - leaving the file offset unchanged. *buffers* must be a sequence of - :term:`bytes-like objects `. Buffers are processed in - array order. Entire contents of the first buffer is written before - proceeding to the second, and so on. - - The flags argument contains a bitwise OR of zero or more of the following - flags: - - - :data:`RWF_DSYNC` - - :data:`RWF_SYNC` - - Return the total number of bytes actually written. - - The operating system may set a limit (:func:`sysconf` value - ``'SC_IOV_MAX'``) on the number of buffers that can be used. - - Combine the functionality of :func:`os.writev` and :func:`os.pwrite`. - - .. availability:: Linux 2.6.30 and newer, FreeBSD 6.0 and newer, - OpenBSD 2.7 and newer. Using flags requires Linux 4.7 or newer. - - .. versionadded:: 3.7 - - -.. data:: RWF_DSYNC - - Provide a per-write equivalent of the :data:`O_DSYNC` ``open(2)`` flag. This - flag effect applies only to the data range written by the system call. - - .. availability:: Linux 4.7 and newer. - - .. versionadded:: 3.7 - - -.. data:: RWF_SYNC - - Provide a per-write equivalent of the :data:`O_SYNC` ``open(2)`` flag. This - flag effect applies only to the data range written by the system call. - - .. availability:: Linux 4.7 and newer. - - .. versionadded:: 3.7 - - -.. function:: read(fd, n) - - Read at most *n* bytes from file descriptor *fd*. - - Return a bytestring containing the bytes read. If the end of the file - referred to by *fd* has been reached, an empty bytes object is returned. - - .. note:: - - This function is intended for low-level I/O and must be applied to a file - descriptor as returned by :func:`os.open` or :func:`pipe`. To read a - "file object" returned by the built-in function :func:`open` or by - :func:`popen` or :func:`fdopen`, or :data:`sys.stdin`, use its - :meth:`~file.read` or :meth:`~file.readline` methods. - - .. versionchanged:: 3.5 - If the system call is interrupted and the signal handler does not raise an - exception, the function now retries the system call instead of raising an - :exc:`InterruptedError` exception (see :pep:`475` for the rationale). - - -.. function:: sendfile(out_fd, in_fd, offset, count) - sendfile(out_fd, in_fd, offset, count, [headers], [trailers], flags=0) - - Copy *count* bytes from file descriptor *in_fd* to file descriptor *out_fd* - starting at *offset*. - Return the number of bytes sent. When EOF is reached return ``0``. - - The first function notation is supported by all platforms that define - :func:`sendfile`. - - On Linux, if *offset* is given as ``None``, the bytes are read from the - current position of *in_fd* and the position of *in_fd* is updated. - - The second case may be used on Mac OS X and FreeBSD where *headers* and - *trailers* are arbitrary sequences of buffers that are written before and - after the data from *in_fd* is written. It returns the same as the first case. - - On Mac OS X and FreeBSD, a value of ``0`` for *count* specifies to send until - the end of *in_fd* is reached. - - All platforms support sockets as *out_fd* file descriptor, and some platforms - allow other types (e.g. regular file, pipe) as well. - - Cross-platform applications should not use *headers*, *trailers* and *flags* - arguments. - - .. availability:: Unix. - - .. note:: - - For a higher-level wrapper of :func:`sendfile`, see - :meth:`socket.socket.sendfile`. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.9 - Parameters *out* and *in* was renamed to *out_fd* and *in_fd*. - - -.. function:: set_blocking(fd, blocking) - - Set the blocking mode of the specified file descriptor. Set the - :data:`O_NONBLOCK` flag if blocking is ``False``, clear the flag otherwise. - - See also :func:`get_blocking` and :meth:`socket.socket.setblocking`. - - .. availability:: Unix. - - .. versionadded:: 3.5 - - -.. data:: SF_NODISKIO - SF_MNOWAIT - SF_SYNC - - Parameters to the :func:`sendfile` function, if the implementation supports - them. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: readv(fd, buffers) - - Read from a file descriptor *fd* into a number of mutable :term:`bytes-like - objects ` *buffers*. Transfer data into each buffer until - it is full and then move on to the next buffer in the sequence to hold the - rest of the data. - - Return the total number of bytes actually read which can be less than the - total capacity of all the objects. - - The operating system may set a limit (:func:`sysconf` value - ``'SC_IOV_MAX'``) on the number of buffers that can be used. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: tcgetpgrp(fd) - - Return the process group associated with the terminal given by *fd* (an open - file descriptor as returned by :func:`os.open`). - - .. availability:: Unix. - - -.. function:: tcsetpgrp(fd, pg) - - Set the process group associated with the terminal given by *fd* (an open file - descriptor as returned by :func:`os.open`) to *pg*. - - .. availability:: Unix. - - -.. function:: ttyname(fd) - - Return a string which specifies the terminal device associated with - file descriptor *fd*. If *fd* is not associated with a terminal device, an - exception is raised. - - .. availability:: Unix. - - -.. function:: write(fd, str) - - Write the bytestring in *str* to file descriptor *fd*. - - Return the number of bytes actually written. - - .. note:: - - This function is intended for low-level I/O and must be applied to a file - descriptor as returned by :func:`os.open` or :func:`pipe`. To write a "file - object" returned by the built-in function :func:`open` or by :func:`popen` or - :func:`fdopen`, or :data:`sys.stdout` or :data:`sys.stderr`, use its - :meth:`~file.write` method. - - .. versionchanged:: 3.5 - If the system call is interrupted and the signal handler does not raise an - exception, the function now retries the system call instead of raising an - :exc:`InterruptedError` exception (see :pep:`475` for the rationale). - - -.. function:: writev(fd, buffers) - - Write the contents of *buffers* to file descriptor *fd*. *buffers* must be - a sequence of :term:`bytes-like objects `. Buffers are - processed in array order. Entire contents of the first buffer is written - before proceeding to the second, and so on. - - Returns the total number of bytes actually written. - - The operating system may set a limit (:func:`sysconf` value - ``'SC_IOV_MAX'``) on the number of buffers that can be used. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. _terminal-size: - -Querying the size of a terminal -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 3.3 - -.. function:: get_terminal_size(fd=STDOUT_FILENO) - - Return the size of the terminal window as ``(columns, lines)``, - tuple of type :class:`terminal_size`. - - The optional argument ``fd`` (default ``STDOUT_FILENO``, or standard - output) specifies which file descriptor should be queried. - - If the file descriptor is not connected to a terminal, an :exc:`OSError` - is raised. - - :func:`shutil.get_terminal_size` is the high-level function which - should normally be used, ``os.get_terminal_size`` is the low-level - implementation. - - .. availability:: Unix, Windows. - -.. class:: terminal_size - - A subclass of tuple, holding ``(columns, lines)`` of the terminal window size. - - .. attribute:: columns - - Width of the terminal window in characters. - - .. attribute:: lines - - Height of the terminal window in characters. - - -.. _fd_inheritance: - -Inheritance of File Descriptors -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 3.4 - -A file descriptor has an "inheritable" flag which indicates if the file descriptor -can be inherited by child processes. Since Python 3.4, file descriptors -created by Python are non-inheritable by default. - -On UNIX, non-inheritable file descriptors are closed in child processes at the -execution of a new program, other file descriptors are inherited. - -On Windows, non-inheritable handles and file descriptors are closed in child -processes, except for standard streams (file descriptors 0, 1 and 2: stdin, stdout -and stderr), which are always inherited. Using :func:`spawn\* ` functions, -all inheritable handles and all inheritable file descriptors are inherited. -Using the :mod:`subprocess` module, all file descriptors except standard -streams are closed, and inheritable handles are only inherited if the -*close_fds* parameter is ``False``. - -.. function:: get_inheritable(fd) - - Get the "inheritable" flag of the specified file descriptor (a boolean). - -.. function:: set_inheritable(fd, inheritable) - - Set the "inheritable" flag of the specified file descriptor. - -.. function:: get_handle_inheritable(handle) - - Get the "inheritable" flag of the specified handle (a boolean). - - .. availability:: Windows. - -.. function:: set_handle_inheritable(handle, inheritable) - - Set the "inheritable" flag of the specified handle. - - .. availability:: Windows. - - -.. _os-file-dir: - -Files and Directories ---------------------- - -On some Unix platforms, many of these functions support one or more of these -features: - -.. _path_fd: - -* **specifying a file descriptor:** - Normally the *path* argument provided to functions in the :mod:`os` module - must be a string specifying a file path. However, some functions now - alternatively accept an open file descriptor for their *path* argument. - The function will then operate on the file referred to by the descriptor. - (For POSIX systems, Python will call the variant of the function prefixed - with ``f`` (e.g. call ``fchdir`` instead of ``chdir``).) - - You can check whether or not *path* can be specified as a file descriptor - for a particular function on your platform using :data:`os.supports_fd`. - If this functionality is unavailable, using it will raise a - :exc:`NotImplementedError`. - - If the function also supports *dir_fd* or *follow_symlinks* arguments, it's - an error to specify one of those when supplying *path* as a file descriptor. - -.. _dir_fd: - -* **paths relative to directory descriptors:** If *dir_fd* is not ``None``, it - should be a file descriptor referring to a directory, and the path to operate - on should be relative; path will then be relative to that directory. If the - path is absolute, *dir_fd* is ignored. (For POSIX systems, Python will call - the variant of the function with an ``at`` suffix and possibly prefixed with - ``f`` (e.g. call ``faccessat`` instead of ``access``). - - You can check whether or not *dir_fd* is supported for a particular function - on your platform using :data:`os.supports_dir_fd`. If it's unavailable, - using it will raise a :exc:`NotImplementedError`. - -.. _follow_symlinks: - -* **not following symlinks:** If *follow_symlinks* is - ``False``, and the last element of the path to operate on is a symbolic link, - the function will operate on the symbolic link itself rather than the file - pointed to by the link. (For POSIX systems, Python will call the ``l...`` - variant of the function.) - - You can check whether or not *follow_symlinks* is supported for a particular - function on your platform using :data:`os.supports_follow_symlinks`. - If it's unavailable, using it will raise a :exc:`NotImplementedError`. - - - -.. function:: access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True) - - Use the real uid/gid to test for access to *path*. Note that most operations - will use the effective uid/gid, therefore this routine can be used in a - suid/sgid environment to test if the invoking user has the specified access to - *path*. *mode* should be :const:`F_OK` to test the existence of *path*, or it - can be the inclusive OR of one or more of :const:`R_OK`, :const:`W_OK`, and - :const:`X_OK` to test permissions. Return :const:`True` if access is allowed, - :const:`False` if not. See the Unix man page :manpage:`access(2)` for more - information. - - This function can support specifying :ref:`paths relative to directory - descriptors ` and :ref:`not following symlinks `. - - If *effective_ids* is ``True``, :func:`access` will perform its access - checks using the effective uid/gid instead of the real uid/gid. - *effective_ids* may not be supported on your platform; you can check whether - or not it is available using :data:`os.supports_effective_ids`. If it is - unavailable, using it will raise a :exc:`NotImplementedError`. - - .. note:: - - Using :func:`access` to check if a user is authorized to e.g. open a file - before actually doing so using :func:`open` creates a security hole, - because the user might exploit the short time interval between checking - and opening the file to manipulate it. It's preferable to use :term:`EAFP` - techniques. For example:: - - if os.access("myfile", os.R_OK): - with open("myfile") as fp: - return fp.read() - return "some default data" - - is better written as:: - - try: - fp = open("myfile") - except PermissionError: - return "some default data" - else: - with fp: - return fp.read() - - .. note:: - - I/O operations may fail even when :func:`access` indicates that they would - succeed, particularly for operations on network filesystems which may have - permissions semantics beyond the usual POSIX permission-bit model. - - .. versionchanged:: 3.3 - Added the *dir_fd*, *effective_ids*, and *follow_symlinks* parameters. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. data:: F_OK - R_OK - W_OK - X_OK - - Values to pass as the *mode* parameter of :func:`access` to test the - existence, readability, writability and executability of *path*, - respectively. - - -.. function:: chdir(path) - - .. index:: single: directory; changing - - Change the current working directory to *path*. - - This function can support :ref:`specifying a file descriptor `. The - descriptor must refer to an opened directory, not an open file. - - This function can raise :exc:`OSError` and subclasses such as - :exc:`FileNotFoundError`, :exc:`PermissionError`, and :exc:`NotADirectoryError`. - - .. versionadded:: 3.3 - Added support for specifying *path* as a file descriptor - on some platforms. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: chflags(path, flags, *, follow_symlinks=True) - - Set the flags of *path* to the numeric *flags*. *flags* may take a combination - (bitwise OR) of the following values (as defined in the :mod:`stat` module): - - * :data:`stat.UF_NODUMP` - * :data:`stat.UF_IMMUTABLE` - * :data:`stat.UF_APPEND` - * :data:`stat.UF_OPAQUE` - * :data:`stat.UF_NOUNLINK` - * :data:`stat.UF_COMPRESSED` - * :data:`stat.UF_HIDDEN` - * :data:`stat.SF_ARCHIVED` - * :data:`stat.SF_IMMUTABLE` - * :data:`stat.SF_APPEND` - * :data:`stat.SF_NOUNLINK` - * :data:`stat.SF_SNAPSHOT` - - This function can support :ref:`not following symlinks `. - - .. availability:: Unix. - - .. versionadded:: 3.3 - The *follow_symlinks* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: chmod(path, mode, *, dir_fd=None, follow_symlinks=True) - - Change the mode of *path* to the numeric *mode*. *mode* may take one of the - following values (as defined in the :mod:`stat` module) or bitwise ORed - combinations of them: - - * :data:`stat.S_ISUID` - * :data:`stat.S_ISGID` - * :data:`stat.S_ENFMT` - * :data:`stat.S_ISVTX` - * :data:`stat.S_IREAD` - * :data:`stat.S_IWRITE` - * :data:`stat.S_IEXEC` - * :data:`stat.S_IRWXU` - * :data:`stat.S_IRUSR` - * :data:`stat.S_IWUSR` - * :data:`stat.S_IXUSR` - * :data:`stat.S_IRWXG` - * :data:`stat.S_IRGRP` - * :data:`stat.S_IWGRP` - * :data:`stat.S_IXGRP` - * :data:`stat.S_IRWXO` - * :data:`stat.S_IROTH` - * :data:`stat.S_IWOTH` - * :data:`stat.S_IXOTH` - - This function can support :ref:`specifying a file descriptor `, - :ref:`paths relative to directory descriptors ` and :ref:`not - following symlinks `. - - .. note:: - - Although Windows supports :func:`chmod`, you can only set the file's - read-only flag with it (via the ``stat.S_IWRITE`` and ``stat.S_IREAD`` - constants or a corresponding integer value). All other bits are ignored. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor, - and the *dir_fd* and *follow_symlinks* arguments. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True) - - Change the owner and group id of *path* to the numeric *uid* and *gid*. To - leave one of the ids unchanged, set it to -1. - - This function can support :ref:`specifying a file descriptor `, - :ref:`paths relative to directory descriptors ` and :ref:`not - following symlinks `. - - See :func:`shutil.chown` for a higher-level function that accepts names in - addition to numeric ids. - - .. availability:: Unix. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor, - and the *dir_fd* and *follow_symlinks* arguments. - - .. versionchanged:: 3.6 - Supports a :term:`path-like object`. - - -.. function:: chroot(path) - - Change the root directory of the current process to *path*. - - .. availability:: Unix. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: fchdir(fd) - - Change the current working directory to the directory represented by the file - descriptor *fd*. The descriptor must refer to an opened directory, not an - open file. As of Python 3.3, this is equivalent to ``os.chdir(fd)``. - - .. availability:: Unix. - - -.. function:: getcwd() - - Return a string representing the current working directory. - - -.. function:: getcwdb() - - Return a bytestring representing the current working directory. - - .. versionchanged:: 3.8 - The function now uses the UTF-8 encoding on Windows, rather than the ANSI - code page: see :pep:`529` for the rationale. The function is no longer - deprecated on Windows. - - -.. function:: lchflags(path, flags) - - Set the flags of *path* to the numeric *flags*, like :func:`chflags`, but do - not follow symbolic links. As of Python 3.3, this is equivalent to - ``os.chflags(path, flags, follow_symlinks=False)``. - - .. availability:: Unix. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: lchmod(path, mode) - - Change the mode of *path* to the numeric *mode*. If path is a symlink, this - affects the symlink rather than the target. See the docs for :func:`chmod` - for possible values of *mode*. As of Python 3.3, this is equivalent to - ``os.chmod(path, mode, follow_symlinks=False)``. - - .. availability:: Unix. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - -.. function:: lchown(path, uid, gid) - - Change the owner and group id of *path* to the numeric *uid* and *gid*. This - function will not follow symbolic links. As of Python 3.3, this is equivalent - to ``os.chown(path, uid, gid, follow_symlinks=False)``. - - .. availability:: Unix. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True) - - Create a hard link pointing to *src* named *dst*. - - This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to - supply :ref:`paths relative to directory descriptors `, and :ref:`not - following symlinks `. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.2 - Added Windows support. - - .. versionadded:: 3.3 - Added the *src_dir_fd*, *dst_dir_fd*, and *follow_symlinks* arguments. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *src* and *dst*. - - -.. function:: listdir(path='.') - - Return a list containing the names of the entries in the directory given by - *path*. The list is in arbitrary order, and does not include the special - entries ``'.'`` and ``'..'`` even if they are present in the directory. - - *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` - (directly or indirectly through the :class:`PathLike` interface), - the filenames returned will also be of type ``bytes``; - in all other circumstances, they will be of type ``str``. - - This function can also support :ref:`specifying a file descriptor - `; the file descriptor must refer to a directory. - - .. audit-event:: os.listdir path os.listdir - - .. note:: - To encode ``str`` filenames to ``bytes``, use :func:`~os.fsencode`. - - .. seealso:: - - The :func:`scandir` function returns directory entries along with - file attribute information, giving better performance for many - common use cases. - - .. versionchanged:: 3.2 - The *path* parameter became optional. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: lstat(path, \*, dir_fd=None) - - Perform the equivalent of an :c:func:`lstat` system call on the given path. - Similar to :func:`~os.stat`, but does not follow symbolic links. Return a - :class:`stat_result` object. - - On platforms that do not support symbolic links, this is an alias for - :func:`~os.stat`. - - As of Python 3.3, this is equivalent to ``os.stat(path, dir_fd=dir_fd, - follow_symlinks=False)``. - - This function can also support :ref:`paths relative to directory descriptors - `. - - .. seealso:: - - The :func:`.stat` function. - - .. versionchanged:: 3.2 - Added support for Windows 6.0 (Vista) symbolic links. - - .. versionchanged:: 3.3 - Added the *dir_fd* parameter. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *src* and *dst*. - - .. versionchanged:: 3.8 - On Windows, now opens reparse points that represent another path - (name surrogates), including symbolic links and directory junctions. - Other kinds of reparse points are resolved by the operating system as - for :func:`~os.stat`. - - -.. function:: mkdir(path, mode=0o777, *, dir_fd=None) - - Create a directory named *path* with numeric mode *mode*. - - If the directory already exists, :exc:`FileExistsError` is raised. - - .. _mkdir_modebits: - - On some systems, *mode* is ignored. Where it is used, the current umask - value is first masked out. If bits other than the last 9 (i.e. the last 3 - digits of the octal representation of the *mode*) are set, their meaning is - platform-dependent. On some platforms, they are ignored and you should call - :func:`chmod` explicitly to set them. - - This function can also support :ref:`paths relative to directory descriptors - `. - - It is also possible to create temporary directories; see the - :mod:`tempfile` module's :func:`tempfile.mkdtemp` function. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: makedirs(name, mode=0o777, exist_ok=False) - - .. index:: - single: directory; creating - single: UNC paths; and os.makedirs() - - Recursive directory creation function. Like :func:`mkdir`, but makes all - intermediate-level directories needed to contain the leaf directory. - - The *mode* parameter is passed to :func:`mkdir` for creating the leaf - directory; see :ref:`the mkdir() description ` for how it - is interpreted. To set the file permission bits of any newly-created parent - directories you can set the umask before invoking :func:`makedirs`. The - file permission bits of existing parent directories are not changed. - - If *exist_ok* is ``False`` (the default), an :exc:`FileExistsError` is - raised if the target directory already exists. - - .. note:: - - :func:`makedirs` will become confused if the path elements to create - include :data:`pardir` (eg. ".." on UNIX systems). - - This function handles UNC paths correctly. - - .. versionadded:: 3.2 - The *exist_ok* parameter. - - .. versionchanged:: 3.4.1 - - Before Python 3.4.1, if *exist_ok* was ``True`` and the directory existed, - :func:`makedirs` would still raise an error if *mode* did not match the - mode of the existing directory. Since this behavior was impossible to - implement safely, it was removed in Python 3.4.1. See :issue:`21082`. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. versionchanged:: 3.7 - The *mode* argument no longer affects the file permission bits of - newly-created intermediate-level directories. - - -.. function:: mkfifo(path, mode=0o666, *, dir_fd=None) - - Create a FIFO (a named pipe) named *path* with numeric mode *mode*. - The current umask value is first masked out from the mode. - - This function can also support :ref:`paths relative to directory descriptors - `. - - FIFOs are pipes that can be accessed like regular files. FIFOs exist until they - are deleted (for example with :func:`os.unlink`). Generally, FIFOs are used as - rendezvous between "client" and "server" type processes: the server opens the - FIFO for reading, and the client opens it for writing. Note that :func:`mkfifo` - doesn't open the FIFO --- it just creates the rendezvous point. - - .. availability:: Unix. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: mknod(path, mode=0o600, device=0, *, dir_fd=None) - - Create a filesystem node (file, device special file or named pipe) named - *path*. *mode* specifies both the permissions to use and the type of node - to be created, being combined (bitwise OR) with one of ``stat.S_IFREG``, - ``stat.S_IFCHR``, ``stat.S_IFBLK``, and ``stat.S_IFIFO`` (those constants are - available in :mod:`stat`). For ``stat.S_IFCHR`` and ``stat.S_IFBLK``, - *device* defines the newly created device special file (probably using - :func:`os.makedev`), otherwise it is ignored. - - This function can also support :ref:`paths relative to directory descriptors - `. - - .. availability:: Unix. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: major(device) - - Extract the device major number from a raw device number (usually the - :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). - - -.. function:: minor(device) - - Extract the device minor number from a raw device number (usually the - :attr:`st_dev` or :attr:`st_rdev` field from :c:type:`stat`). - - -.. function:: makedev(major, minor) - - Compose a raw device number from the major and minor device numbers. - - -.. function:: pathconf(path, name) - - Return system configuration information relevant to a named file. *name* - specifies the configuration value to retrieve; it may be a string which is the - name of a defined system value; these names are specified in a number of - standards (POSIX.1, Unix 95, Unix 98, and others). Some platforms define - additional names as well. The names known to the host operating system are - given in the ``pathconf_names`` dictionary. For configuration variables not - included in that mapping, passing an integer for *name* is also accepted. - - If *name* is a string and is not known, :exc:`ValueError` is raised. If a - specific value for *name* is not supported by the host system, even if it is - included in ``pathconf_names``, an :exc:`OSError` is raised with - :const:`errno.EINVAL` for the error number. - - This function can support :ref:`specifying a file descriptor - `. - - .. availability:: Unix. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. data:: pathconf_names - - Dictionary mapping names accepted by :func:`pathconf` and :func:`fpathconf` to - the integer values defined for those names by the host operating system. This - can be used to determine the set of names known to the system. - - .. availability:: Unix. - - -.. function:: readlink(path, *, dir_fd=None) - - Return a string representing the path to which the symbolic link points. The - result may be either an absolute or relative pathname; if it is relative, it - may be converted to an absolute pathname using - ``os.path.join(os.path.dirname(path), result)``. - - If the *path* is a string object (directly or indirectly through a - :class:`PathLike` interface), the result will also be a string object, - and the call may raise a UnicodeDecodeError. If the *path* is a bytes - object (direct or indirectly), the result will be a bytes object. - - This function can also support :ref:`paths relative to directory descriptors - `. - - When trying to resolve a path that may contain links, use - :func:`~os.path.realpath` to properly handle recursion and platform - differences. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.2 - Added support for Windows 6.0 (Vista) symbolic links. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` on Unix. - - .. versionchanged:: 3.8 - Accepts a :term:`path-like object` and a bytes object on Windows. - - .. versionchanged:: 3.8 - Added support for directory junctions, and changed to return the - substitution path (which typically includes ``\\?\`` prefix) rather - than the optional "print name" field that was previously returned. - -.. function:: remove(path, *, dir_fd=None) - - Remove (delete) the file *path*. If *path* is a directory, an - :exc:`IsADirectoryError` is raised. Use :func:`rmdir` to remove directories. - - This function can support :ref:`paths relative to directory descriptors - `. - - On Windows, attempting to remove a file that is in use causes an exception to - be raised; on Unix, the directory entry is removed but the storage allocated - to the file is not made available until the original file is no longer in use. - - This function is semantically identical to :func:`unlink`. - - .. versionadded:: 3.3 - The *dir_fd* argument. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: removedirs(name) - - .. index:: single: directory; deleting - - Remove directories recursively. Works like :func:`rmdir` except that, if the - leaf directory is successfully removed, :func:`removedirs` tries to - successively remove every parent directory mentioned in *path* until an error - is raised (which is ignored, because it generally means that a parent directory - is not empty). For example, ``os.removedirs('foo/bar/baz')`` will first remove - the directory ``'foo/bar/baz'``, and then remove ``'foo/bar'`` and ``'foo'`` if - they are empty. Raises :exc:`OSError` if the leaf directory could not be - successfully removed. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) - - Rename the file or directory *src* to *dst*. If *dst* exists, the operation - will fail with an :exc:`OSError` subclass in a number of cases: - - On Windows, if *dst* exists a :exc:`FileExistsError` is always raised. - - On Unix, if *src* is a file and *dst* is a directory or vice-versa, an - :exc:`IsADirectoryError` or a :exc:`NotADirectoryError` will be raised - respectively. If both are directories and *dst* is empty, *dst* will be - silently replaced. If *dst* is a non-empty directory, an :exc:`OSError` - is raised. If both are files, *dst* it will be replaced silently if the user - has permission. The operation may fail on some Unix flavors if *src* and - *dst* are on different filesystems. If successful, the renaming will be an - atomic operation (this is a POSIX requirement). - - This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to - supply :ref:`paths relative to directory descriptors `. - - If you want cross-platform overwriting of the destination, use :func:`replace`. - - .. versionadded:: 3.3 - The *src_dir_fd* and *dst_dir_fd* arguments. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *src* and *dst*. - - -.. function:: renames(old, new) - - Recursive directory or file renaming function. Works like :func:`rename`, except - creation of any intermediate directories needed to make the new pathname good is - attempted first. After the rename, directories corresponding to rightmost path - segments of the old name will be pruned away using :func:`removedirs`. - - .. note:: - - This function can fail with the new directory structure made if you lack - permissions needed to remove the leaf directory or file. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *old* and *new*. - - -.. function:: replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None) - - Rename the file or directory *src* to *dst*. If *dst* is a directory, - :exc:`OSError` will be raised. If *dst* exists and is a file, it will - be replaced silently if the user has permission. The operation may fail - if *src* and *dst* are on different filesystems. If successful, - the renaming will be an atomic operation (this is a POSIX requirement). - - This function can support specifying *src_dir_fd* and/or *dst_dir_fd* to - supply :ref:`paths relative to directory descriptors `. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *src* and *dst*. - - -.. function:: rmdir(path, *, dir_fd=None) - - Remove (delete) the directory *path*. If the directory does not exist or is - not empty, an :exc:`FileNotFoundError` or an :exc:`OSError` is raised - respectively. In order to remove whole directory trees, - :func:`shutil.rmtree` can be used. - - This function can support :ref:`paths relative to directory descriptors - `. - - .. versionadded:: 3.3 - The *dir_fd* parameter. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: scandir(path='.') - - Return an iterator of :class:`os.DirEntry` objects corresponding to the - entries in the directory given by *path*. The entries are yielded in - arbitrary order, and the special entries ``'.'`` and ``'..'`` are not - included. - - Using :func:`scandir` instead of :func:`listdir` can significantly - increase the performance of code that also needs file type or file - attribute information, because :class:`os.DirEntry` objects expose this - information if the operating system provides it when scanning a directory. - All :class:`os.DirEntry` methods may perform a system call, but - :func:`~os.DirEntry.is_dir` and :func:`~os.DirEntry.is_file` usually only - require a system call for symbolic links; :func:`os.DirEntry.stat` - always requires a system call on Unix but only requires one for - symbolic links on Windows. - - *path* may be a :term:`path-like object`. If *path* is of type ``bytes`` - (directly or indirectly through the :class:`PathLike` interface), - the type of the :attr:`~os.DirEntry.name` and :attr:`~os.DirEntry.path` - attributes of each :class:`os.DirEntry` will be ``bytes``; in all other - circumstances, they will be of type ``str``. - - This function can also support :ref:`specifying a file descriptor - `; the file descriptor must refer to a directory. - - .. audit-event:: os.scandir path os.scandir - - The :func:`scandir` iterator supports the :term:`context manager` protocol - and has the following method: - - .. method:: scandir.close() - - Close the iterator and free acquired resources. - - This is called automatically when the iterator is exhausted or garbage - collected, or when an error happens during iterating. However it - is advisable to call it explicitly or use the :keyword:`with` - statement. - - .. versionadded:: 3.6 - - The following example shows a simple use of :func:`scandir` to display all - the files (excluding directories) in the given *path* that don't start with - ``'.'``. The ``entry.is_file()`` call will generally not make an additional - system call:: - - with os.scandir(path) as it: - for entry in it: - if not entry.name.startswith('.') and entry.is_file(): - print(entry.name) - - .. note:: - - On Unix-based systems, :func:`scandir` uses the system's - `opendir() `_ - and - `readdir() `_ - functions. On Windows, it uses the Win32 - `FindFirstFileW `_ - and - `FindNextFileW `_ - functions. - - .. versionadded:: 3.5 - - .. versionadded:: 3.6 - Added support for the :term:`context manager` protocol and the - :func:`~scandir.close()` method. If a :func:`scandir` iterator is neither - exhausted nor explicitly closed a :exc:`ResourceWarning` will be emitted - in its destructor. - - The function accepts a :term:`path-like object`. - - .. versionchanged:: 3.7 - Added support for :ref:`file descriptors ` on Unix. - - -.. class:: DirEntry - - Object yielded by :func:`scandir` to expose the file path and other file - attributes of a directory entry. - - :func:`scandir` will provide as much of this information as possible without - making additional system calls. When a ``stat()`` or ``lstat()`` system call - is made, the ``os.DirEntry`` object will cache the result. - - ``os.DirEntry`` instances are not intended to be stored in long-lived data - structures; if you know the file metadata has changed or if a long time has - elapsed since calling :func:`scandir`, call ``os.stat(entry.path)`` to fetch - up-to-date information. - - Because the ``os.DirEntry`` methods can make operating system calls, they may - also raise :exc:`OSError`. If you need very fine-grained - control over errors, you can catch :exc:`OSError` when calling one of the - ``os.DirEntry`` methods and handle as appropriate. - - To be directly usable as a :term:`path-like object`, ``os.DirEntry`` - implements the :class:`PathLike` interface. - - Attributes and methods on a ``os.DirEntry`` instance are as follows: - - .. attribute:: name - - The entry's base filename, relative to the :func:`scandir` *path* - argument. - - The :attr:`name` attribute will be ``bytes`` if the :func:`scandir` - *path* argument is of type ``bytes`` and ``str`` otherwise. Use - :func:`~os.fsdecode` to decode byte filenames. - - .. attribute:: path - - The entry's full path name: equivalent to ``os.path.join(scandir_path, - entry.name)`` where *scandir_path* is the :func:`scandir` *path* - argument. The path is only absolute if the :func:`scandir` *path* - argument was absolute. If the :func:`scandir` *path* - argument was a :ref:`file descriptor `, the :attr:`path` - attribute is the same as the :attr:`name` attribute. - - The :attr:`path` attribute will be ``bytes`` if the :func:`scandir` - *path* argument is of type ``bytes`` and ``str`` otherwise. Use - :func:`~os.fsdecode` to decode byte filenames. - - .. method:: inode() - - Return the inode number of the entry. - - The result is cached on the ``os.DirEntry`` object. Use - ``os.stat(entry.path, follow_symlinks=False).st_ino`` to fetch up-to-date - information. - - On the first, uncached call, a system call is required on Windows but - not on Unix. - - .. method:: is_dir(\*, follow_symlinks=True) - - Return ``True`` if this entry is a directory or a symbolic link pointing - to a directory; return ``False`` if the entry is or points to any other - kind of file, or if it doesn't exist anymore. - - If *follow_symlinks* is ``False``, return ``True`` only if this entry - is a directory (without following symlinks); return ``False`` if the - entry is any other kind of file or if it doesn't exist anymore. - - The result is cached on the ``os.DirEntry`` object, with a separate cache - for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` along - with :func:`stat.S_ISDIR` to fetch up-to-date information. - - On the first, uncached call, no system call is required in most cases. - Specifically, for non-symlinks, neither Windows or Unix require a system - call, except on certain Unix file systems, such as network file systems, - that return ``dirent.d_type == DT_UNKNOWN``. If the entry is a symlink, - a system call will be required to follow the symlink unless - *follow_symlinks* is ``False``. - - This method can raise :exc:`OSError`, such as :exc:`PermissionError`, - but :exc:`FileNotFoundError` is caught and not raised. - - .. method:: is_file(\*, follow_symlinks=True) - - Return ``True`` if this entry is a file or a symbolic link pointing to a - file; return ``False`` if the entry is or points to a directory or other - non-file entry, or if it doesn't exist anymore. - - If *follow_symlinks* is ``False``, return ``True`` only if this entry - is a file (without following symlinks); return ``False`` if the entry is - a directory or other non-file entry, or if it doesn't exist anymore. - - The result is cached on the ``os.DirEntry`` object. Caching, system calls - made, and exceptions raised are as per :func:`~os.DirEntry.is_dir`. - - .. method:: is_symlink() - - Return ``True`` if this entry is a symbolic link (even if broken); - return ``False`` if the entry points to a directory or any kind of file, - or if it doesn't exist anymore. - - The result is cached on the ``os.DirEntry`` object. Call - :func:`os.path.islink` to fetch up-to-date information. - - On the first, uncached call, no system call is required in most cases. - Specifically, neither Windows or Unix require a system call, except on - certain Unix file systems, such as network file systems, that return - ``dirent.d_type == DT_UNKNOWN``. - - This method can raise :exc:`OSError`, such as :exc:`PermissionError`, - but :exc:`FileNotFoundError` is caught and not raised. - - .. method:: stat(\*, follow_symlinks=True) - - Return a :class:`stat_result` object for this entry. This method - follows symbolic links by default; to stat a symbolic link add the - ``follow_symlinks=False`` argument. - - On Unix, this method always requires a system call. On Windows, it - only requires a system call if *follow_symlinks* is ``True`` and the - entry is a reparse point (for example, a symbolic link or directory - junction). - - On Windows, the ``st_ino``, ``st_dev`` and ``st_nlink`` attributes of the - :class:`stat_result` are always set to zero. Call :func:`os.stat` to - get these attributes. - - The result is cached on the ``os.DirEntry`` object, with a separate cache - for *follow_symlinks* ``True`` and ``False``. Call :func:`os.stat` to - fetch up-to-date information. - - Note that there is a nice correspondence between several attributes - and methods of ``os.DirEntry`` and of :class:`pathlib.Path`. In - particular, the ``name`` attribute has the same - meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()`` - and ``stat()`` methods. - - .. versionadded:: 3.5 - - .. versionchanged:: 3.6 - Added support for the :class:`~os.PathLike` interface. Added support - for :class:`bytes` paths on Windows. - - -.. function:: stat(path, \*, dir_fd=None, follow_symlinks=True) - - Get the status of a file or a file descriptor. Perform the equivalent of a - :c:func:`stat` system call on the given path. *path* may be specified as - either a string or bytes -- directly or indirectly through the :class:`PathLike` - interface -- or as an open file descriptor. Return a :class:`stat_result` - object. - - This function normally follows symlinks; to stat a symlink add the argument - ``follow_symlinks=False``, or use :func:`lstat`. - - This function can support :ref:`specifying a file descriptor ` and - :ref:`not following symlinks `. - - On Windows, passing ``follow_symlinks=False`` will disable following all - name-surrogate reparse points, which includes symlinks and directory - junctions. Other types of reparse points that do not resemble links or that - the operating system is unable to follow will be opened directly. When - following a chain of multiple links, this may result in the original link - being returned instead of the non-link that prevented full traversal. To - obtain stat results for the final path in this case, use the - :func:`os.path.realpath` function to resolve the path name as far as - possible and call :func:`lstat` on the result. This does not apply to - dangling symlinks or junction points, which will raise the usual exceptions. - - .. index:: module: stat - - Example:: - - >>> import os - >>> statinfo = os.stat('somefile.txt') - >>> statinfo - os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026, - st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295, - st_mtime=1297230027, st_ctime=1297230027) - >>> statinfo.st_size - 264 - - .. seealso:: - - :func:`fstat` and :func:`lstat` functions. - - .. versionadded:: 3.3 - Added the *dir_fd* and *follow_symlinks* arguments, specifying a file - descriptor instead of a path. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. versionchanged:: 3.8 - On Windows, all reparse points that can be resolved by the operating - system are now followed, and passing ``follow_symlinks=False`` - disables following all name surrogate reparse points. If the operating - system reaches a reparse point that it is not able to follow, *stat* now - returns the information for the original path as if - ``follow_symlinks=False`` had been specified instead of raising an error. - - -.. class:: stat_result - - Object whose attributes correspond roughly to the members of the - :c:type:`stat` structure. It is used for the result of :func:`os.stat`, - :func:`os.fstat` and :func:`os.lstat`. - - Attributes: - - .. attribute:: st_mode - - File mode: file type and file mode bits (permissions). - - .. attribute:: st_ino - - Platform dependent, but if non-zero, uniquely identifies the - file for a given value of ``st_dev``. Typically: - - * the inode number on Unix, - * the `file index - `_ on - Windows - - .. attribute:: st_dev - - Identifier of the device on which this file resides. - - .. attribute:: st_nlink - - Number of hard links. - - .. attribute:: st_uid - - User identifier of the file owner. - - .. attribute:: st_gid - - Group identifier of the file owner. - - .. attribute:: st_size - - Size of the file in bytes, if it is a regular file or a symbolic link. - The size of a symbolic link is the length of the pathname it contains, - without a terminating null byte. - - Timestamps: - - .. attribute:: st_atime - - Time of most recent access expressed in seconds. - - .. attribute:: st_mtime - - Time of most recent content modification expressed in seconds. - - .. attribute:: st_ctime - - Platform dependent: - - * the time of most recent metadata change on Unix, - * the time of creation on Windows, expressed in seconds. - - .. attribute:: st_atime_ns - - Time of most recent access expressed in nanoseconds as an integer. - - .. attribute:: st_mtime_ns - - Time of most recent content modification expressed in nanoseconds as an - integer. - - .. attribute:: st_ctime_ns - - Platform dependent: - - * the time of most recent metadata change on Unix, - * the time of creation on Windows, expressed in nanoseconds as an - integer. - - .. note:: - - The exact meaning and resolution of the :attr:`st_atime`, - :attr:`st_mtime`, and :attr:`st_ctime` attributes depend on the operating - system and the file system. For example, on Windows systems using the FAT - or FAT32 file systems, :attr:`st_mtime` has 2-second resolution, and - :attr:`st_atime` has only 1-day resolution. See your operating system - documentation for details. - - Similarly, although :attr:`st_atime_ns`, :attr:`st_mtime_ns`, - and :attr:`st_ctime_ns` are always expressed in nanoseconds, many - systems do not provide nanosecond precision. On systems that do - provide nanosecond precision, the floating-point object used to - store :attr:`st_atime`, :attr:`st_mtime`, and :attr:`st_ctime` - cannot preserve all of it, and as such will be slightly inexact. - If you need the exact timestamps you should always use - :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and :attr:`st_ctime_ns`. - - On some Unix systems (such as Linux), the following attributes may also be - available: - - .. attribute:: st_blocks - - Number of 512-byte blocks allocated for file. - This may be smaller than :attr:`st_size`/512 when the file has holes. - - .. attribute:: st_blksize - - "Preferred" blocksize for efficient file system I/O. Writing to a file in - smaller chunks may cause an inefficient read-modify-rewrite. - - .. attribute:: st_rdev - - Type of device if an inode device. - - .. attribute:: st_flags - - User defined flags for file. - - On other Unix systems (such as FreeBSD), the following attributes may be - available (but may be only filled out if root tries to use them): - - .. attribute:: st_gen - - File generation number. - - .. attribute:: st_birthtime - - Time of file creation. - - On Solaris and derivatives, the following attributes may also be - available: - - .. attribute:: st_fstype - - String that uniquely identifies the type of the filesystem that - contains the file. - - On Mac OS systems, the following attributes may also be available: - - .. attribute:: st_rsize - - Real size of the file. - - .. attribute:: st_creator - - Creator of the file. - - .. attribute:: st_type - - File type. - - On Windows systems, the following attributes are also available: - - .. attribute:: st_file_attributes - - Windows file attributes: ``dwFileAttributes`` member of the - ``BY_HANDLE_FILE_INFORMATION`` structure returned by - :c:func:`GetFileInformationByHandle`. See the ``FILE_ATTRIBUTE_*`` - constants in the :mod:`stat` module. - - .. attribute:: st_reparse_tag - - When :attr:`st_file_attributes` has the ``FILE_ATTRIBUTE_REPARSE_POINT`` - set, this field contains the tag identifying the type of reparse point. - See the ``IO_REPARSE_TAG_*`` constants in the :mod:`stat` module. - - The standard module :mod:`stat` defines functions and constants that are - useful for extracting information from a :c:type:`stat` structure. (On - Windows, some items are filled with dummy values.) - - For backward compatibility, a :class:`stat_result` instance is also - accessible as a tuple of at least 10 integers giving the most important (and - portable) members of the :c:type:`stat` structure, in the order - :attr:`st_mode`, :attr:`st_ino`, :attr:`st_dev`, :attr:`st_nlink`, - :attr:`st_uid`, :attr:`st_gid`, :attr:`st_size`, :attr:`st_atime`, - :attr:`st_mtime`, :attr:`st_ctime`. More items may be added at the end by - some implementations. For compatibility with older Python versions, - accessing :class:`stat_result` as a tuple always returns integers. - - .. versionadded:: 3.3 - Added the :attr:`st_atime_ns`, :attr:`st_mtime_ns`, and - :attr:`st_ctime_ns` members. - - .. versionadded:: 3.5 - Added the :attr:`st_file_attributes` member on Windows. - - .. versionchanged:: 3.5 - Windows now returns the file index as :attr:`st_ino` when - available. - - .. versionadded:: 3.7 - Added the :attr:`st_fstype` member to Solaris/derivatives. - - .. versionadded:: 3.8 - Added the :attr:`st_reparse_tag` member on Windows. - - .. versionchanged:: 3.8 - On Windows, the :attr:`st_mode` member now identifies special - files as :const:`S_IFCHR`, :const:`S_IFIFO` or :const:`S_IFBLK` - as appropriate. - -.. function:: statvfs(path) - - Perform a :c:func:`statvfs` system call on the given path. The return value is - an object whose attributes describe the filesystem on the given path, and - correspond to the members of the :c:type:`statvfs` structure, namely: - :attr:`f_bsize`, :attr:`f_frsize`, :attr:`f_blocks`, :attr:`f_bfree`, - :attr:`f_bavail`, :attr:`f_files`, :attr:`f_ffree`, :attr:`f_favail`, - :attr:`f_flag`, :attr:`f_namemax`, :attr:`f_fsid`. - - Two module-level constants are defined for the :attr:`f_flag` attribute's - bit-flags: if :const:`ST_RDONLY` is set, the filesystem is mounted - read-only, and if :const:`ST_NOSUID` is set, the semantics of - setuid/setgid bits are disabled or not supported. - - Additional module-level constants are defined for GNU/glibc based systems. - These are :const:`ST_NODEV` (disallow access to device special files), - :const:`ST_NOEXEC` (disallow program execution), :const:`ST_SYNCHRONOUS` - (writes are synced at once), :const:`ST_MANDLOCK` (allow mandatory locks on an FS), - :const:`ST_WRITE` (write on file/directory/symlink), :const:`ST_APPEND` - (append-only file), :const:`ST_IMMUTABLE` (immutable file), :const:`ST_NOATIME` - (do not update access times), :const:`ST_NODIRATIME` (do not update directory access - times), :const:`ST_RELATIME` (update atime relative to mtime/ctime). - - This function can support :ref:`specifying a file descriptor `. - - .. availability:: Unix. - - .. versionchanged:: 3.2 - The :const:`ST_RDONLY` and :const:`ST_NOSUID` constants were added. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor. - - .. versionchanged:: 3.4 - The :const:`ST_NODEV`, :const:`ST_NOEXEC`, :const:`ST_SYNCHRONOUS`, - :const:`ST_MANDLOCK`, :const:`ST_WRITE`, :const:`ST_APPEND`, - :const:`ST_IMMUTABLE`, :const:`ST_NOATIME`, :const:`ST_NODIRATIME`, - and :const:`ST_RELATIME` constants were added. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. versionadded:: 3.7 - Added :attr:`f_fsid`. - - -.. data:: supports_dir_fd - - A :class:`set` object indicating which functions in the :mod:`os` - module accept an open file descriptor for their *dir_fd* parameter. - Different platforms provide different features, and the underlying - functionality Python uses to implement the *dir_fd* parameter is not - available on all platforms Python supports. For consistency's sake, - functions that may support *dir_fd* always allow specifying the - parameter, but will throw an exception if the functionality is used - when it's not locally available. (Specifying ``None`` for *dir_fd* - is always supported on all platforms.) - - To check whether a particular function accepts an open file descriptor - for its *dir_fd* parameter, use the ``in`` operator on ``supports_dir_fd``. - As an example, this expression evaluates to ``True`` if :func:`os.stat` - accepts open file descriptors for *dir_fd* on the local platform:: - - os.stat in os.supports_dir_fd - - Currently *dir_fd* parameters only work on Unix platforms; - none of them work on Windows. - - .. versionadded:: 3.3 - - -.. data:: supports_effective_ids - - A :class:`set` object indicating whether :func:`os.access` permits - specifying ``True`` for its *effective_ids* parameter on the local platform. - (Specifying ``False`` for *effective_ids* is always supported on all - platforms.) If the local platform supports it, the collection will contain - :func:`os.access`; otherwise it will be empty. - - This expression evaluates to ``True`` if :func:`os.access` supports - ``effective_ids=True`` on the local platform:: - - os.access in os.supports_effective_ids - - Currently *effective_ids* is only supported on Unix platforms; - it does not work on Windows. - - .. versionadded:: 3.3 - - -.. data:: supports_fd - - A :class:`set` object indicating which functions in the - :mod:`os` module permit specifying their *path* parameter as an open file - descriptor on the local platform. Different platforms provide different - features, and the underlying functionality Python uses to accept open file - descriptors as *path* arguments is not available on all platforms Python - supports. - - To determine whether a particular function permits specifying an open file - descriptor for its *path* parameter, use the ``in`` operator on - ``supports_fd``. As an example, this expression evaluates to ``True`` if - :func:`os.chdir` accepts open file descriptors for *path* on your local - platform:: - - os.chdir in os.supports_fd - - .. versionadded:: 3.3 - - -.. data:: supports_follow_symlinks - - A :class:`set` object indicating which functions in the :mod:`os` module - accept ``False`` for their *follow_symlinks* parameter on the local platform. - Different platforms provide different features, and the underlying - functionality Python uses to implement *follow_symlinks* is not available - on all platforms Python supports. For consistency's sake, functions that - may support *follow_symlinks* always allow specifying the parameter, but - will throw an exception if the functionality is used when it's not locally - available. (Specifying ``True`` for *follow_symlinks* is always supported - on all platforms.) - - To check whether a particular function accepts ``False`` for its - *follow_symlinks* parameter, use the ``in`` operator on - ``supports_follow_symlinks``. As an example, this expression evaluates - to ``True`` if you may specify ``follow_symlinks=False`` when calling - :func:`os.stat` on the local platform:: - - os.stat in os.supports_follow_symlinks - - .. versionadded:: 3.3 - - -.. function:: symlink(src, dst, target_is_directory=False, *, dir_fd=None) - - Create a symbolic link pointing to *src* named *dst*. - - On Windows, a symlink represents either a file or a directory, and does not - morph to the target dynamically. If the target is present, the type of the - symlink will be created to match. Otherwise, the symlink will be created - as a directory if *target_is_directory* is ``True`` or a file symlink (the - default) otherwise. On non-Windows platforms, *target_is_directory* is ignored. - - This function can support :ref:`paths relative to directory descriptors - `. - - .. note:: - - On newer versions of Windows 10, unprivileged accounts can create symlinks - if Developer Mode is enabled. When Developer Mode is not available/enabled, - the *SeCreateSymbolicLinkPrivilege* privilege is required, or the process - must be run as an administrator. - - - :exc:`OSError` is raised when the function is called by an unprivileged - user. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.2 - Added support for Windows 6.0 (Vista) symbolic links. - - .. versionadded:: 3.3 - Added the *dir_fd* argument, and now allow *target_is_directory* - on non-Windows platforms. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *src* and *dst*. - - .. versionchanged:: 3.8 - Added support for unelevated symlinks on Windows with Developer Mode. - - -.. function:: sync() - - Force write of everything to disk. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. function:: truncate(path, length) - - Truncate the file corresponding to *path*, so that it is at most - *length* bytes in size. - - This function can support :ref:`specifying a file descriptor `. - - .. audit-event:: os.truncate path,length os.truncate - - .. availability:: Unix, Windows. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.5 - Added support for Windows - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: unlink(path, *, dir_fd=None) - - Remove (delete) the file *path*. This function is semantically - identical to :func:`remove`; the ``unlink`` name is its - traditional Unix name. Please see the documentation for - :func:`remove` for further information. - - .. versionadded:: 3.3 - The *dir_fd* parameter. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: utime(path, times=None, *[, ns], dir_fd=None, follow_symlinks=True) - - Set the access and modified times of the file specified by *path*. - - :func:`utime` takes two optional parameters, *times* and *ns*. - These specify the times set on *path* and are used as follows: - - - If *ns* is specified, - it must be a 2-tuple of the form ``(atime_ns, mtime_ns)`` - where each member is an int expressing nanoseconds. - - If *times* is not ``None``, - it must be a 2-tuple of the form ``(atime, mtime)`` - where each member is an int or float expressing seconds. - - If *times* is ``None`` and *ns* is unspecified, - this is equivalent to specifying ``ns=(atime_ns, mtime_ns)`` - where both times are the current time. - - It is an error to specify tuples for both *times* and *ns*. - - Note that the exact times you set here may not be returned by a subsequent - :func:`~os.stat` call, depending on the resolution with which your operating - system records access and modification times; see :func:`~os.stat`. The best - way to preserve exact times is to use the *st_atime_ns* and *st_mtime_ns* - fields from the :func:`os.stat` result object with the *ns* parameter to - `utime`. - - This function can support :ref:`specifying a file descriptor `, - :ref:`paths relative to directory descriptors ` and :ref:`not - following symlinks `. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor, - and the *dir_fd*, *follow_symlinks*, and *ns* parameters. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: walk(top, topdown=True, onerror=None, followlinks=False) - - .. index:: - single: directory; walking - single: directory; traversal - - Generate the file names in a directory tree by walking the tree - either top-down or bottom-up. For each directory in the tree rooted at directory - *top* (including *top* itself), it yields a 3-tuple ``(dirpath, dirnames, - filenames)``. - - *dirpath* is a string, the path to the directory. *dirnames* is a list of the - names of the subdirectories in *dirpath* (excluding ``'.'`` and ``'..'``). - *filenames* is a list of the names of the non-directory files in *dirpath*. - Note that the names in the lists contain no path components. To get a full path - (which begins with *top*) to a file or directory in *dirpath*, do - ``os.path.join(dirpath, name)``. - - If optional argument *topdown* is ``True`` or not specified, the triple for a - directory is generated before the triples for any of its subdirectories - (directories are generated top-down). If *topdown* is ``False``, the triple - for a directory is generated after the triples for all of its subdirectories - (directories are generated bottom-up). No matter the value of *topdown*, the - list of subdirectories is retrieved before the tuples for the directory and - its subdirectories are generated. - - When *topdown* is ``True``, the caller can modify the *dirnames* list in-place - (perhaps using :keyword:`del` or slice assignment), and :func:`walk` will only - recurse into the subdirectories whose names remain in *dirnames*; this can be - used to prune the search, impose a specific order of visiting, or even to inform - :func:`walk` about directories the caller creates or renames before it resumes - :func:`walk` again. Modifying *dirnames* when *topdown* is ``False`` has - no effect on the behavior of the walk, because in bottom-up mode the directories - in *dirnames* are generated before *dirpath* itself is generated. - - By default, errors from the :func:`scandir` call are ignored. If optional - argument *onerror* is specified, it should be a function; it will be called with - one argument, an :exc:`OSError` instance. It can report the error to continue - with the walk, or raise the exception to abort the walk. Note that the filename - is available as the ``filename`` attribute of the exception object. - - By default, :func:`walk` will not walk down into symbolic links that resolve to - directories. Set *followlinks* to ``True`` to visit directories pointed to by - symlinks, on systems that support them. - - .. note:: - - Be aware that setting *followlinks* to ``True`` can lead to infinite - recursion if a link points to a parent directory of itself. :func:`walk` - does not keep track of the directories it visited already. - - .. note:: - - If you pass a relative pathname, don't change the current working directory - between resumptions of :func:`walk`. :func:`walk` never changes the current - directory, and assumes that its caller doesn't either. - - This example displays the number of bytes taken by non-directory files in each - directory under the starting directory, except that it doesn't look under any - CVS subdirectory:: - - import os - from os.path import join, getsize - for root, dirs, files in os.walk('python/Lib/email'): - print(root, "consumes", end=" ") - print(sum(getsize(join(root, name)) for name in files), end=" ") - print("bytes in", len(files), "non-directory files") - if 'CVS' in dirs: - dirs.remove('CVS') # don't visit CVS directories - - In the next example (simple implementation of :func:`shutil.rmtree`), - walking the tree bottom-up is essential, :func:`rmdir` doesn't allow - deleting a directory before the directory is empty:: - - # Delete everything reachable from the directory named in "top", - # assuming there are no symbolic links. - # CAUTION: This is dangerous! For example, if top == '/', it - # could delete all your disk files. - import os - for root, dirs, files in os.walk(top, topdown=False): - for name in files: - os.remove(os.path.join(root, name)) - for name in dirs: - os.rmdir(os.path.join(root, name)) - - .. versionchanged:: 3.5 - This function now calls :func:`os.scandir` instead of :func:`os.listdir`, - making it faster by reducing the number of calls to :func:`os.stat`. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None) - - .. index:: - single: directory; walking - single: directory; traversal - - This behaves exactly like :func:`walk`, except that it yields a 4-tuple - ``(dirpath, dirnames, filenames, dirfd)``, and it supports ``dir_fd``. - - *dirpath*, *dirnames* and *filenames* are identical to :func:`walk` output, - and *dirfd* is a file descriptor referring to the directory *dirpath*. - - This function always supports :ref:`paths relative to directory descriptors - ` and :ref:`not following symlinks `. Note however - that, unlike other functions, the :func:`fwalk` default value for - *follow_symlinks* is ``False``. - - .. note:: - - Since :func:`fwalk` yields file descriptors, those are only valid until - the next iteration step, so you should duplicate them (e.g. with - :func:`dup`) if you want to keep them longer. - - This example displays the number of bytes taken by non-directory files in each - directory under the starting directory, except that it doesn't look under any - CVS subdirectory:: - - import os - for root, dirs, files, rootfd in os.fwalk('python/Lib/email'): - print(root, "consumes", end="") - print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]), - end="") - print("bytes in", len(files), "non-directory files") - if 'CVS' in dirs: - dirs.remove('CVS') # don't visit CVS directories - - In the next example, walking the tree bottom-up is essential: - :func:`rmdir` doesn't allow deleting a directory before the directory is - empty:: - - # Delete everything reachable from the directory named in "top", - # assuming there are no symbolic links. - # CAUTION: This is dangerous! For example, if top == '/', it - # could delete all your disk files. - import os - for root, dirs, files, rootfd in os.fwalk(top, topdown=False): - for name in files: - os.unlink(name, dir_fd=rootfd) - for name in dirs: - os.rmdir(name, dir_fd=rootfd) - - .. availability:: Unix. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - .. versionchanged:: 3.7 - Added support for :class:`bytes` paths. - - -.. function:: memfd_create(name[, flags=os.MFD_CLOEXEC]) - - Create an anonymous file and return a file descriptor that refers to it. - *flags* must be one of the ``os.MFD_*`` constants available on the system - (or a bitwise ORed combination of them). By default, the new file - descriptor is :ref:`non-inheritable `. - - The name supplied in *name* is used as a filename and will be displayed as - the target of the corresponding symbolic link in the directory - ``/proc/self/fd/``. The displayed name is always prefixed with ``memfd:`` - and serves only for debugging purposes. Names do not affect the behavior of - the file descriptor, and as such multiple files can have the same name - without any side effects. - - .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. - - .. versionadded:: 3.8 - - -.. data:: MFD_CLOEXEC - MFD_ALLOW_SEALING - MFD_HUGETLB - MFD_HUGE_SHIFT - MFD_HUGE_MASK - MFD_HUGE_64KB - MFD_HUGE_512KB - MFD_HUGE_1MB - MFD_HUGE_2MB - MFD_HUGE_8MB - MFD_HUGE_16MB - MFD_HUGE_32MB - MFD_HUGE_256MB - MFD_HUGE_512MB - MFD_HUGE_1GB - MFD_HUGE_2GB - MFD_HUGE_16GB - - These flags can be passed to :func:`memfd_create`. - - .. availability:: Linux 3.17 or newer with glibc 2.27 or newer. The - ``MFD_HUGE*`` flags are only available since Linux 4.14. - - .. versionadded:: 3.8 - - -Linux extended attributes -~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 3.3 - -These functions are all available on Linux only. - -.. function:: getxattr(path, attribute, *, follow_symlinks=True) - - Return the value of the extended filesystem attribute *attribute* for - *path*. *attribute* can be bytes or str (directly or indirectly through the - :class:`PathLike` interface). If it is str, it is encoded with the filesystem - encoding. - - This function can support :ref:`specifying a file descriptor ` and - :ref:`not following symlinks `. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *path* and *attribute*. - - -.. function:: listxattr(path=None, *, follow_symlinks=True) - - Return a list of the extended filesystem attributes on *path*. The - attributes in the list are represented as strings decoded with the filesystem - encoding. If *path* is ``None``, :func:`listxattr` will examine the current - directory. - - This function can support :ref:`specifying a file descriptor ` and - :ref:`not following symlinks `. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. function:: removexattr(path, attribute, *, follow_symlinks=True) - - Removes the extended filesystem attribute *attribute* from *path*. - *attribute* should be bytes or str (directly or indirectly through the - :class:`PathLike` interface). If it is a string, it is encoded - with the filesystem encoding. - - This function can support :ref:`specifying a file descriptor ` and - :ref:`not following symlinks `. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *path* and *attribute*. - - -.. function:: setxattr(path, attribute, value, flags=0, *, follow_symlinks=True) - - Set the extended filesystem attribute *attribute* on *path* to *value*. - *attribute* must be a bytes or str with no embedded NULs (directly or - indirectly through the :class:`PathLike` interface). If it is a str, - it is encoded with the filesystem encoding. *flags* may be - :data:`XATTR_REPLACE` or :data:`XATTR_CREATE`. If :data:`XATTR_REPLACE` is - given and the attribute does not exist, ``EEXISTS`` will be raised. - If :data:`XATTR_CREATE` is given and the attribute already exists, the - attribute will not be created and ``ENODATA`` will be raised. - - This function can support :ref:`specifying a file descriptor ` and - :ref:`not following symlinks `. - - .. note:: - - A bug in Linux kernel versions less than 2.6.39 caused the flags argument - to be ignored on some filesystems. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object` for *path* and *attribute*. - - -.. data:: XATTR_SIZE_MAX - - The maximum size the value of an extended attribute can be. Currently, this - is 64 KiB on Linux. - - -.. data:: XATTR_CREATE - - This is a possible value for the flags argument in :func:`setxattr`. It - indicates the operation must create an attribute. - - -.. data:: XATTR_REPLACE - - This is a possible value for the flags argument in :func:`setxattr`. It - indicates the operation must replace an existing attribute. - - -.. _os-process: - -Process Management ------------------- - -These functions may be used to create and manage processes. - -The various :func:`exec\* ` functions take a list of arguments for the new -program loaded into the process. In each case, the first of these arguments is -passed to the new program as its own name rather than as an argument a user may -have typed on a command line. For the C programmer, this is the ``argv[0]`` -passed to a program's :c:func:`main`. For example, ``os.execv('/bin/echo', -['foo', 'bar'])`` will only print ``bar`` on standard output; ``foo`` will seem -to be ignored. - - -.. function:: abort() - - Generate a :const:`SIGABRT` signal to the current process. On Unix, the default - behavior is to produce a core dump; on Windows, the process immediately returns - an exit code of ``3``. Be aware that calling this function will not call the - Python signal handler registered for :const:`SIGABRT` with - :func:`signal.signal`. - - -.. function:: add_dll_directory(path) - - Add a path to the DLL search path. - - This search path is used when resolving dependencies for imported - extension modules (the module itself is resolved through sys.path), - and also by :mod:`ctypes`. - - Remove the directory by calling **close()** on the returned object - or using it in a :keyword:`with` statement. - - See the `Microsoft documentation - `_ - for more information about how DLLs are loaded. - - .. availability:: Windows. - - .. versionadded:: 3.8 - Previous versions of CPython would resolve DLLs using the default - behavior for the current process. This led to inconsistencies, - such as only sometimes searching :envvar:`PATH` or the current - working directory, and OS functions such as ``AddDllDirectory`` - having no effect. - - In 3.8, the two primary ways DLLs are loaded now explicitly - override the process-wide behavior to ensure consistency. See the - :ref:`porting notes ` for information on - updating libraries. - - -.. function:: execl(path, arg0, arg1, ...) - execle(path, arg0, arg1, ..., env) - execlp(file, arg0, arg1, ...) - execlpe(file, arg0, arg1, ..., env) - execv(path, args) - execve(path, args, env) - execvp(file, args) - execvpe(file, args, env) - - These functions all execute a new program, replacing the current process; they - do not return. On Unix, the new executable is loaded into the current process, - and will have the same process id as the caller. Errors will be reported as - :exc:`OSError` exceptions. - - The current process is replaced immediately. Open file objects and - descriptors are not flushed, so if there may be data buffered - on these open files, you should flush them using - :func:`sys.stdout.flush` or :func:`os.fsync` before calling an - :func:`exec\* ` function. - - The "l" and "v" variants of the :func:`exec\* ` functions differ in how - command-line arguments are passed. The "l" variants are perhaps the easiest - to work with if the number of parameters is fixed when the code is written; the - individual parameters simply become additional parameters to the :func:`execl\*` - functions. The "v" variants are good when the number of parameters is - variable, with the arguments being passed in a list or tuple as the *args* - parameter. In either case, the arguments to the child process should start with - the name of the command being run, but this is not enforced. - - The variants which include a "p" near the end (:func:`execlp`, - :func:`execlpe`, :func:`execvp`, and :func:`execvpe`) will use the - :envvar:`PATH` environment variable to locate the program *file*. When the - environment is being replaced (using one of the :func:`exec\*e ` variants, - discussed in the next paragraph), the new environment is used as the source of - the :envvar:`PATH` variable. The other variants, :func:`execl`, :func:`execle`, - :func:`execv`, and :func:`execve`, will not use the :envvar:`PATH` variable to - locate the executable; *path* must contain an appropriate absolute or relative - path. - - For :func:`execle`, :func:`execlpe`, :func:`execve`, and :func:`execvpe` (note - that these all end in "e"), the *env* parameter must be a mapping which is - used to define the environment variables for the new process (these are used - instead of the current process' environment); the functions :func:`execl`, - :func:`execlp`, :func:`execv`, and :func:`execvp` all cause the new process to - inherit the environment of the current process. - - For :func:`execve` on some platforms, *path* may also be specified as an open - file descriptor. This functionality may not be supported on your platform; - you can check whether or not it is available using :data:`os.supports_fd`. - If it is unavailable, using it will raise a :exc:`NotImplementedError`. - - .. availability:: Unix, Windows. - - .. versionadded:: 3.3 - Added support for specifying *path* as an open file descriptor - for :func:`execve`. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - -.. function:: _exit(n) - - Exit the process with status *n*, without calling cleanup handlers, flushing - stdio buffers, etc. - - .. note:: - - The standard way to exit is ``sys.exit(n)``. :func:`_exit` should - normally only be used in the child process after a :func:`fork`. - -The following exit codes are defined and can be used with :func:`_exit`, -although they are not required. These are typically used for system programs -written in Python, such as a mail server's external command delivery program. - -.. note:: - - Some of these may not be available on all Unix platforms, since there is some - variation. These constants are defined where they are defined by the underlying - platform. - - -.. data:: EX_OK - - Exit code that means no error occurred. - - .. availability:: Unix. - - -.. data:: EX_USAGE - - Exit code that means the command was used incorrectly, such as when the wrong - number of arguments are given. - - .. availability:: Unix. - - -.. data:: EX_DATAERR - - Exit code that means the input data was incorrect. - - .. availability:: Unix. - - -.. data:: EX_NOINPUT - - Exit code that means an input file did not exist or was not readable. - - .. availability:: Unix. - - -.. data:: EX_NOUSER - - Exit code that means a specified user did not exist. - - .. availability:: Unix. - - -.. data:: EX_NOHOST - - Exit code that means a specified host did not exist. - - .. availability:: Unix. - - -.. data:: EX_UNAVAILABLE - - Exit code that means that a required service is unavailable. - - .. availability:: Unix. - - -.. data:: EX_SOFTWARE - - Exit code that means an internal software error was detected. - - .. availability:: Unix. - - -.. data:: EX_OSERR - - Exit code that means an operating system error was detected, such as the - inability to fork or create a pipe. - - .. availability:: Unix. - - -.. data:: EX_OSFILE - - Exit code that means some system file did not exist, could not be opened, or had - some other kind of error. - - .. availability:: Unix. - - -.. data:: EX_CANTCREAT - - Exit code that means a user specified output file could not be created. - - .. availability:: Unix. - - -.. data:: EX_IOERR - - Exit code that means that an error occurred while doing I/O on some file. - - .. availability:: Unix. - - -.. data:: EX_TEMPFAIL - - Exit code that means a temporary failure occurred. This indicates something - that may not really be an error, such as a network connection that couldn't be - made during a retryable operation. - - .. availability:: Unix. - - -.. data:: EX_PROTOCOL - - Exit code that means that a protocol exchange was illegal, invalid, or not - understood. - - .. availability:: Unix. - - -.. data:: EX_NOPERM - - Exit code that means that there were insufficient permissions to perform the - operation (but not intended for file system problems). - - .. availability:: Unix. - - -.. data:: EX_CONFIG - - Exit code that means that some kind of configuration error occurred. - - .. availability:: Unix. - - -.. data:: EX_NOTFOUND - - Exit code that means something like "an entry was not found". - - .. availability:: Unix. - - -.. function:: fork() - - Fork a child process. Return ``0`` in the child and the child's process id in the - parent. If an error occurs :exc:`OSError` is raised. - - Note that some platforms including FreeBSD <= 6.3 and Cygwin have - known issues when using ``fork()`` from a thread. - - .. versionchanged:: 3.8 - Calling ``fork()`` in a subinterpreter is no longer supported - (:exc:`RuntimeError` is raised). - - .. warning:: - - See :mod:`ssl` for applications that use the SSL module with fork(). - - .. availability:: Unix. - - -.. function:: forkpty() - - Fork a child process, using a new pseudo-terminal as the child's controlling - terminal. Return a pair of ``(pid, fd)``, where *pid* is ``0`` in the child, the - new child's process id in the parent, and *fd* is the file descriptor of the - master end of the pseudo-terminal. For a more portable approach, use the - :mod:`pty` module. If an error occurs :exc:`OSError` is raised. - - .. versionchanged:: 3.8 - Calling ``forkpty()`` in a subinterpreter is no longer supported - (:exc:`RuntimeError` is raised). - - .. availability:: some flavors of Unix. - - -.. function:: kill(pid, sig) - - .. index:: - single: process; killing - single: process; signalling - - Send signal *sig* to the process *pid*. Constants for the specific signals - available on the host platform are defined in the :mod:`signal` module. - - Windows: The :data:`signal.CTRL_C_EVENT` and - :data:`signal.CTRL_BREAK_EVENT` signals are special signals which can - only be sent to console processes which share a common console window, - e.g., some subprocesses. Any other value for *sig* will cause the process - to be unconditionally killed by the TerminateProcess API, and the exit code - will be set to *sig*. The Windows version of :func:`kill` additionally takes - process handles to be killed. - - See also :func:`signal.pthread_kill`. - - .. versionadded:: 3.2 - Windows support. - - -.. function:: killpg(pgid, sig) - - .. index:: - single: process; killing - single: process; signalling - - Send the signal *sig* to the process group *pgid*. - - .. availability:: Unix. - - -.. function:: nice(increment) - - Add *increment* to the process's "niceness". Return the new niceness. - - .. availability:: Unix. - - -.. function:: pidfd_open(pid, flags=0) - - Return a file descriptor referring to the process *pid*. This descriptor can - be used to perform process management without races and signals. The *flags* - argument is provided for future extensions; no flag values are currently - defined. - - See the :manpage:`pidfd_open(2)` man page for more details. - - .. availability:: Linux 5.3+ - .. versionadded:: 3.9 - - -.. function:: plock(op) - - Lock program segments into memory. The value of *op* (defined in - ````) determines which segments are locked. - - .. availability:: Unix. - - -.. function:: popen(cmd, mode='r', buffering=-1) - - Open a pipe to or from command *cmd*. - The return value is an open file object - connected to the pipe, which can be read or written depending on whether *mode* - is ``'r'`` (default) or ``'w'``. The *buffering* argument has the same meaning as - the corresponding argument to the built-in :func:`open` function. The - returned file object reads or writes text strings rather than bytes. - - The ``close`` method returns :const:`None` if the subprocess exited - successfully, or the subprocess's return code if there was an - error. On POSIX systems, if the return code is positive it - represents the return value of the process left-shifted by one - byte. If the return code is negative, the process was terminated - by the signal given by the negated value of the return code. (For - example, the return value might be ``- signal.SIGKILL`` if the - subprocess was killed.) On Windows systems, the return value - contains the signed integer return code from the child process. - - This is implemented using :class:`subprocess.Popen`; see that class's - documentation for more powerful ways to manage and communicate with - subprocesses. - - -.. function:: posix_spawn(path, argv, env, *, file_actions=None, \ - setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ - setsigdef=(), scheduler=None) - - Wraps the :c:func:`posix_spawn` C library API for use from Python. - - Most users should use :func:`subprocess.run` instead of :func:`posix_spawn`. - - The positional-only arguments *path*, *args*, and *env* are similar to - :func:`execve`. - - The *path* parameter is the path to the executable file.The *path* should - contain a directory.Use :func:`posix_spawnp` to pass an executable file - without directory. - - The *file_actions* argument may be a sequence of tuples describing actions - to take on specific file descriptors in the child process between the C - library implementation's :c:func:`fork` and :c:func:`exec` steps. - The first item in each tuple must be one of the three type indicator - listed below describing the remaining tuple elements: - - .. data:: POSIX_SPAWN_OPEN - - (``os.POSIX_SPAWN_OPEN``, *fd*, *path*, *flags*, *mode*) - - Performs ``os.dup2(os.open(path, flags, mode), fd)``. - - .. data:: POSIX_SPAWN_CLOSE - - (``os.POSIX_SPAWN_CLOSE``, *fd*) - - Performs ``os.close(fd)``. - - .. data:: POSIX_SPAWN_DUP2 - - (``os.POSIX_SPAWN_DUP2``, *fd*, *new_fd*) - - Performs ``os.dup2(fd, new_fd)``. - - These tuples correspond to the C library - :c:func:`posix_spawn_file_actions_addopen`, - :c:func:`posix_spawn_file_actions_addclose`, and - :c:func:`posix_spawn_file_actions_adddup2` API calls used to prepare - for the :c:func:`posix_spawn` call itself. - - The *setpgroup* argument will set the process group of the child to the value - specified. If the value specified is 0, the child's process group ID will be - made the same as its process ID. If the value of *setpgroup* is not set, the - child will inherit the parent's process group ID. This argument corresponds - to the C library :c:data:`POSIX_SPAWN_SETPGROUP` flag. - - If the *resetids* argument is ``True`` it will reset the effective UID and - GID of the child to the real UID and GID of the parent process. If the - argument is ``False``, then the child retains the effective UID and GID of - the parent. In either case, if the set-user-ID and set-group-ID permission - bits are enabled on the executable file, their effect will override the - setting of the effective UID and GID. This argument corresponds to the C - library :c:data:`POSIX_SPAWN_RESETIDS` flag. - - If the *setsid* argument is ``True``, it will create a new session ID - for `posix_spawn`. *setsid* requires :c:data:`POSIX_SPAWN_SETSID` - or :c:data:`POSIX_SPAWN_SETSID_NP` flag. Otherwise, :exc:`NotImplementedError` - is raised. - - The *setsigmask* argument will set the signal mask to the signal set - specified. If the parameter is not used, then the child inherits the - parent's signal mask. This argument corresponds to the C library - :c:data:`POSIX_SPAWN_SETSIGMASK` flag. - - The *sigdef* argument will reset the disposition of all signals in the set - specified. This argument corresponds to the C library - :c:data:`POSIX_SPAWN_SETSIGDEF` flag. - - The *scheduler* argument must be a tuple containing the (optional) scheduler - policy and an instance of :class:`sched_param` with the scheduler parameters. - A value of ``None`` in the place of the scheduler policy indicates that is - not being provided. This argument is a combination of the C library - :c:data:`POSIX_SPAWN_SETSCHEDPARAM` and :c:data:`POSIX_SPAWN_SETSCHEDULER` - flags. - - .. versionadded:: 3.8 - - .. availability:: Unix. - -.. function:: posix_spawnp(path, argv, env, *, file_actions=None, \ - setpgroup=None, resetids=False, setsid=False, setsigmask=(), \ - setsigdef=(), scheduler=None) - - Wraps the :c:func:`posix_spawnp` C library API for use from Python. - - Similar to :func:`posix_spawn` except that the system searches - for the *executable* file in the list of directories specified by the - :envvar:`PATH` environment variable (in the same way as for ``execvp(3)``). - - .. versionadded:: 3.8 - - .. availability:: See :func:`posix_spawn` documentation. - - -.. function:: register_at_fork(*, before=None, after_in_parent=None, \ - after_in_child=None) - - Register callables to be executed when a new child process is forked - using :func:`os.fork` or similar process cloning APIs. - The parameters are optional and keyword-only. - Each specifies a different call point. - - * *before* is a function called before forking a child process. - * *after_in_parent* is a function called from the parent process - after forking a child process. - * *after_in_child* is a function called from the child process. - - These calls are only made if control is expected to return to the - Python interpreter. A typical :mod:`subprocess` launch will not - trigger them as the child is not going to re-enter the interpreter. - - Functions registered for execution before forking are called in - reverse registration order. Functions registered for execution - after forking (either in the parent or in the child) are called - in registration order. - - Note that :c:func:`fork` calls made by third-party C code may not - call those functions, unless it explicitly calls :c:func:`PyOS_BeforeFork`, - :c:func:`PyOS_AfterFork_Parent` and :c:func:`PyOS_AfterFork_Child`. - - There is no way to unregister a function. - - .. availability:: Unix. - - .. versionadded:: 3.7 - - -.. function:: spawnl(mode, path, ...) - spawnle(mode, path, ..., env) - spawnlp(mode, file, ...) - spawnlpe(mode, file, ..., env) - spawnv(mode, path, args) - spawnve(mode, path, args, env) - spawnvp(mode, file, args) - spawnvpe(mode, file, args, env) - - Execute the program *path* in a new process. - - (Note that the :mod:`subprocess` module provides more powerful facilities for - spawning new processes and retrieving their results; using that module is - preferable to using these functions. Check especially the - :ref:`subprocess-replacements` section.) - - If *mode* is :const:`P_NOWAIT`, this function returns the process id of the new - process; if *mode* is :const:`P_WAIT`, returns the process's exit code if it - exits normally, or ``-signal``, where *signal* is the signal that killed the - process. On Windows, the process id will actually be the process handle, so can - be used with the :func:`waitpid` function. - - Note on VxWorks, this function doesn't return ``-signal`` when the new process is - killed. Instead it raises OSError exception. - - The "l" and "v" variants of the :func:`spawn\* ` functions differ in how - command-line arguments are passed. The "l" variants are perhaps the easiest - to work with if the number of parameters is fixed when the code is written; the - individual parameters simply become additional parameters to the - :func:`spawnl\*` functions. The "v" variants are good when the number of - parameters is variable, with the arguments being passed in a list or tuple as - the *args* parameter. In either case, the arguments to the child process must - start with the name of the command being run. - - The variants which include a second "p" near the end (:func:`spawnlp`, - :func:`spawnlpe`, :func:`spawnvp`, and :func:`spawnvpe`) will use the - :envvar:`PATH` environment variable to locate the program *file*. When the - environment is being replaced (using one of the :func:`spawn\*e ` variants, - discussed in the next paragraph), the new environment is used as the source of - the :envvar:`PATH` variable. The other variants, :func:`spawnl`, - :func:`spawnle`, :func:`spawnv`, and :func:`spawnve`, will not use the - :envvar:`PATH` variable to locate the executable; *path* must contain an - appropriate absolute or relative path. - - For :func:`spawnle`, :func:`spawnlpe`, :func:`spawnve`, and :func:`spawnvpe` - (note that these all end in "e"), the *env* parameter must be a mapping - which is used to define the environment variables for the new process (they are - used instead of the current process' environment); the functions - :func:`spawnl`, :func:`spawnlp`, :func:`spawnv`, and :func:`spawnvp` all cause - the new process to inherit the environment of the current process. Note that - keys and values in the *env* dictionary must be strings; invalid keys or - values will cause the function to fail, with a return value of ``127``. - - As an example, the following calls to :func:`spawnlp` and :func:`spawnvpe` are - equivalent:: - - import os - os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null') - - L = ['cp', 'index.html', '/dev/null'] - os.spawnvpe(os.P_WAIT, 'cp', L, os.environ) - - .. availability:: Unix, Windows. :func:`spawnlp`, :func:`spawnlpe`, :func:`spawnvp` - and :func:`spawnvpe` are not available on Windows. :func:`spawnle` and - :func:`spawnve` are not thread-safe on Windows; we advise you to use the - :mod:`subprocess` module instead. - - .. versionchanged:: 3.6 - Accepts a :term:`path-like object`. - - -.. data:: P_NOWAIT - P_NOWAITO - - Possible values for the *mode* parameter to the :func:`spawn\* ` family of - functions. If either of these values is given, the :func:`spawn\*` functions - will return as soon as the new process has been created, with the process id as - the return value. - - .. availability:: Unix, Windows. - - -.. data:: P_WAIT - - Possible value for the *mode* parameter to the :func:`spawn\* ` family of - functions. If this is given as *mode*, the :func:`spawn\*` functions will not - return until the new process has run to completion and will return the exit code - of the process the run is successful, or ``-signal`` if a signal kills the - process. - - .. availability:: Unix, Windows. - - -.. data:: P_DETACH - P_OVERLAY - - Possible values for the *mode* parameter to the :func:`spawn\* ` family of - functions. These are less portable than those listed above. :const:`P_DETACH` - is similar to :const:`P_NOWAIT`, but the new process is detached from the - console of the calling process. If :const:`P_OVERLAY` is used, the current - process will be replaced; the :func:`spawn\* ` function will not return. - - .. availability:: Windows. - - -.. function:: startfile(path[, operation]) - - Start a file with its associated application. - - When *operation* is not specified or ``'open'``, this acts like double-clicking - the file in Windows Explorer, or giving the file name as an argument to the - :program:`start` command from the interactive command shell: the file is opened - with whatever application (if any) its extension is associated. - - When another *operation* is given, it must be a "command verb" that specifies - what should be done with the file. Common verbs documented by Microsoft are - ``'print'`` and ``'edit'`` (to be used on files) as well as ``'explore'`` and - ``'find'`` (to be used on directories). - - :func:`startfile` returns as soon as the associated application is launched. - There is no option to wait for the application to close, and no way to retrieve - the application's exit status. The *path* parameter is relative to the current - directory. If you want to use an absolute path, make sure the first character - is not a slash (``'/'``); the underlying Win32 :c:func:`ShellExecute` function - doesn't work if it is. Use the :func:`os.path.normpath` function to ensure that - the path is properly encoded for Win32. - - To reduce interpreter startup overhead, the Win32 :c:func:`ShellExecute` - function is not resolved until this function is first called. If the function - cannot be resolved, :exc:`NotImplementedError` will be raised. - - .. availability:: Windows. - - -.. function:: system(command) - - Execute the command (a string) in a subshell. This is implemented by calling - the Standard C function :c:func:`system`, and has the same limitations. - Changes to :data:`sys.stdin`, etc. are not reflected in the environment of - the executed command. If *command* generates any output, it will be sent to - the interpreter standard output stream. - - On Unix, the return value is the exit status of the process encoded in the - format specified for :func:`wait`. Note that POSIX does not specify the - meaning of the return value of the C :c:func:`system` function, so the return - value of the Python function is system-dependent. - - On Windows, the return value is that returned by the system shell after - running *command*. The shell is given by the Windows environment variable - :envvar:`COMSPEC`: it is usually :program:`cmd.exe`, which returns the exit - status of the command run; on systems using a non-native shell, consult your - shell documentation. - - The :mod:`subprocess` module provides more powerful facilities for spawning - new processes and retrieving their results; using that module is preferable - to using this function. See the :ref:`subprocess-replacements` section in - the :mod:`subprocess` documentation for some helpful recipes. - - .. audit-event:: os.system command os.system - - .. availability:: Unix, Windows. - - -.. function:: times() - - Returns the current global process times. - The return value is an object with five attributes: - - * :attr:`user` - user time - * :attr:`system` - system time - * :attr:`children_user` - user time of all child processes - * :attr:`children_system` - system time of all child processes - * :attr:`elapsed` - elapsed real time since a fixed point in the past - - For backwards compatibility, this object also behaves like a five-tuple - containing :attr:`user`, :attr:`system`, :attr:`children_user`, - :attr:`children_system`, and :attr:`elapsed` in that order. - - See the Unix manual page - :manpage:`times(2)` and :manpage:`times(3)` manual page on Unix or `the GetProcessTimes MSDN - ` - _ on Windows. - On Windows, only :attr:`user` and :attr:`system` are known; the other - attributes are zero. - - .. availability:: Unix, Windows. - - .. versionchanged:: 3.3 - Return type changed from a tuple to a tuple-like object - with named attributes. - - -.. function:: wait() - - Wait for completion of a child process, and return a tuple containing its pid - and exit status indication: a 16-bit number, whose low byte is the signal number - that killed the process, and whose high byte is the exit status (if the signal - number is zero); the high bit of the low byte is set if a core file was - produced. - - .. availability:: Unix. - -.. function:: waitid(idtype, id, options) - - Wait for the completion of one or more child processes. - *idtype* can be :data:`P_PID`, :data:`P_PGID`, :data:`P_ALL`, or - :data:`P_PIDFD` on Linux. - *id* specifies the pid to wait on. - *options* is constructed from the ORing of one or more of :data:`WEXITED`, - :data:`WSTOPPED` or :data:`WCONTINUED` and additionally may be ORed with - :data:`WNOHANG` or :data:`WNOWAIT`. The return value is an object - representing the data contained in the :c:type:`siginfo_t` structure, namely: - :attr:`si_pid`, :attr:`si_uid`, :attr:`si_signo`, :attr:`si_status`, - :attr:`si_code` or ``None`` if :data:`WNOHANG` is specified and there are no - children in a waitable state. - - .. availability:: Unix. - - .. versionadded:: 3.3 - -.. data:: P_PID - P_PGID - P_ALL - - These are the possible values for *idtype* in :func:`waitid`. They affect - how *id* is interpreted. - - .. availability:: Unix. - - .. versionadded:: 3.3 - -.. data:: P_PIDFD - - This is a Linux-specific *idtype* that indicates that *id* is a file - descriptor that refers to a process. - - .. availability:: Linux 5.4+ - - .. versionadded:: 3.9 - -.. data:: WEXITED - WSTOPPED - WNOWAIT - - Flags that can be used in *options* in :func:`waitid` that specify what - child signal to wait for. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - -.. data:: CLD_EXITED - CLD_KILLED - CLD_DUMPED - CLD_TRAPPED - CLD_STOPPED - CLD_CONTINUED - - These are the possible values for :attr:`si_code` in the result returned by - :func:`waitid`. - - .. availability:: Unix. - - .. versionadded:: 3.3 - - .. versionchanged:: 3.9 - Added :data:`CLD_KILLED` and :data:`CLD_STOPPED` values. - - -.. function:: waitpid(pid, options) - - The details of this function differ on Unix and Windows. - - On Unix: Wait for completion of a child process given by process id *pid*, and - return a tuple containing its process id and exit status indication (encoded as - for :func:`wait`). The semantics of the call are affected by the value of the - integer *options*, which should be ``0`` for normal operation. - - If *pid* is greater than ``0``, :func:`waitpid` requests status information for - that specific process. If *pid* is ``0``, the request is for the status of any - child in the process group of the current process. If *pid* is ``-1``, the - request pertains to any child of the current process. If *pid* is less than - ``-1``, status is requested for any process in the process group ``-pid`` (the - absolute value of *pid*). - - An :exc:`OSError` is raised with the value of errno when the syscall - returns -1. - - On Windows: Wait for completion of a process given by process handle *pid*, and - return a tuple containing *pid*, and its exit status shifted left by 8 bits - (shifting makes cross-platform use of the function easier). A *pid* less than or - equal to ``0`` has no special meaning on Windows, and raises an exception. The - value of integer *options* has no effect. *pid* can refer to any process whose - id is known, not necessarily a child process. The :func:`spawn\* ` - functions called with :const:`P_NOWAIT` return suitable process handles. - - .. versionchanged:: 3.5 - If the system call is interrupted and the signal handler does not raise an - exception, the function now retries the system call instead of raising an - :exc:`InterruptedError` exception (see :pep:`475` for the rationale). - - -.. function:: wait3(options) - - Similar to :func:`waitpid`, except no process id argument is given and a - 3-element tuple containing the child's process id, exit status indication, - and resource usage information is returned. Refer to - :mod:`resource`.\ :func:`~resource.getrusage` for details on resource usage - information. The option argument is the same as that provided to - :func:`waitpid` and :func:`wait4`. - - .. availability:: Unix. - - -.. function:: wait4(pid, options) - - Similar to :func:`waitpid`, except a 3-element tuple, containing the child's - process id, exit status indication, and resource usage information is returned. - Refer to :mod:`resource`.\ :func:`~resource.getrusage` for details on - resource usage information. The arguments to :func:`wait4` are the same - as those provided to :func:`waitpid`. - - .. availability:: Unix. - - -.. data:: WNOHANG - - The option for :func:`waitpid` to return immediately if no child process status - is available immediately. The function returns ``(0, 0)`` in this case. - - .. availability:: Unix. - - -.. data:: WCONTINUED - - This option causes child processes to be reported if they have been continued - from a job control stop since their status was last reported. - - .. availability:: some Unix systems. - - -.. data:: WUNTRACED - - This option causes child processes to be reported if they have been stopped but - their current state has not been reported since they were stopped. - - .. availability:: Unix. - - -The following functions take a process status code as returned by -:func:`system`, :func:`wait`, or :func:`waitpid` as a parameter. They may be -used to determine the disposition of a process. - -.. function:: WCOREDUMP(status) - - Return ``True`` if a core dump was generated for the process, otherwise - return ``False``. - - .. availability:: Unix. - - -.. function:: WIFCONTINUED(status) - - Return ``True`` if the process has been continued from a job control stop, - otherwise return ``False``. - - .. availability:: Unix. - - -.. function:: WIFSTOPPED(status) - - Return ``True`` if the process has been stopped, otherwise return - ``False``. - - .. availability:: Unix. - - -.. function:: WIFSIGNALED(status) - - Return ``True`` if the process exited due to a signal, otherwise return - ``False``. - - .. availability:: Unix. - - -.. function:: WIFEXITED(status) - - Return ``True`` if the process exited using the :manpage:`exit(2)` system call, - otherwise return ``False``. - - .. availability:: Unix. - - -.. function:: WEXITSTATUS(status) - - If ``WIFEXITED(status)`` is true, return the integer parameter to the - :manpage:`exit(2)` system call. Otherwise, the return value is meaningless. - - .. availability:: Unix. - - -.. function:: WSTOPSIG(status) - - Return the signal which caused the process to stop. - - .. availability:: Unix. - - -.. function:: WTERMSIG(status) - - Return the signal which caused the process to exit. - - .. availability:: Unix. - - -Interface to the scheduler --------------------------- - -These functions control how a process is allocated CPU time by the operating -system. They are only available on some Unix platforms. For more detailed -information, consult your Unix manpages. - -.. versionadded:: 3.3 - -The following scheduling policies are exposed if they are supported by the -operating system. - -.. data:: SCHED_OTHER - - The default scheduling policy. - -.. data:: SCHED_BATCH - - Scheduling policy for CPU-intensive processes that tries to preserve - interactivity on the rest of the computer. - -.. data:: SCHED_IDLE - - Scheduling policy for extremely low priority background tasks. - -.. data:: SCHED_SPORADIC - - Scheduling policy for sporadic server programs. - -.. data:: SCHED_FIFO - - A First In First Out scheduling policy. - -.. data:: SCHED_RR - - A round-robin scheduling policy. - -.. data:: SCHED_RESET_ON_FORK - - This flag can be OR'ed with any other scheduling policy. When a process with - this flag set forks, its child's scheduling policy and priority are reset to - the default. - - -.. class:: sched_param(sched_priority) - - This class represents tunable scheduling parameters used in - :func:`sched_setparam`, :func:`sched_setscheduler`, and - :func:`sched_getparam`. It is immutable. - - At the moment, there is only one possible parameter: - - .. attribute:: sched_priority - - The scheduling priority for a scheduling policy. - - -.. function:: sched_get_priority_min(policy) - - Get the minimum priority value for *policy*. *policy* is one of the - scheduling policy constants above. - - -.. function:: sched_get_priority_max(policy) - - Get the maximum priority value for *policy*. *policy* is one of the - scheduling policy constants above. - - -.. function:: sched_setscheduler(pid, policy, param) - - Set the scheduling policy for the process with PID *pid*. A *pid* of 0 means - the calling process. *policy* is one of the scheduling policy constants - above. *param* is a :class:`sched_param` instance. - - -.. function:: sched_getscheduler(pid) - - Return the scheduling policy for the process with PID *pid*. A *pid* of 0 - means the calling process. The result is one of the scheduling policy - constants above. - - -.. function:: sched_setparam(pid, param) - - Set a scheduling parameters for the process with PID *pid*. A *pid* of 0 means - the calling process. *param* is a :class:`sched_param` instance. - - -.. function:: sched_getparam(pid) - - Return the scheduling parameters as a :class:`sched_param` instance for the - process with PID *pid*. A *pid* of 0 means the calling process. - - -.. function:: sched_rr_get_interval(pid) - - Return the round-robin quantum in seconds for the process with PID *pid*. A - *pid* of 0 means the calling process. - - -.. function:: sched_yield() - - Voluntarily relinquish the CPU. - - -.. function:: sched_setaffinity(pid, mask) - - Restrict the process with PID *pid* (or the current process if zero) to a - set of CPUs. *mask* is an iterable of integers representing the set of - CPUs to which the process should be restricted. - - -.. function:: sched_getaffinity(pid) - - Return the set of CPUs the process with PID *pid* (or the current process - if zero) is restricted to. - - -.. _os-path: - -Miscellaneous System Information --------------------------------- - - -.. function:: confstr(name) - - Return string-valued system configuration values. *name* specifies the - configuration value to retrieve; it may be a string which is the name of a - defined system value; these names are specified in a number of standards (POSIX, - Unix 95, Unix 98, and others). Some platforms define additional names as well. - The names known to the host operating system are given as the keys of the - ``confstr_names`` dictionary. For configuration variables not included in that - mapping, passing an integer for *name* is also accepted. - - If the configuration value specified by *name* isn't defined, ``None`` is - returned. - - If *name* is a string and is not known, :exc:`ValueError` is raised. If a - specific value for *name* is not supported by the host system, even if it is - included in ``confstr_names``, an :exc:`OSError` is raised with - :const:`errno.EINVAL` for the error number. - - .. availability:: Unix. - - -.. data:: confstr_names - - Dictionary mapping names accepted by :func:`confstr` to the integer values - defined for those names by the host operating system. This can be used to - determine the set of names known to the system. - - .. availability:: Unix. - - -.. function:: cpu_count() - - Return the number of CPUs in the system. Returns ``None`` if undetermined. - - This number is not equivalent to the number of CPUs the current process can - use. The number of usable CPUs can be obtained with - ``len(os.sched_getaffinity(0))`` - - - .. versionadded:: 3.4 - - -.. function:: getloadavg() - - Return the number of processes in the system run queue averaged over the last - 1, 5, and 15 minutes or raises :exc:`OSError` if the load average was - unobtainable. - - .. availability:: Unix. - - -.. function:: sysconf(name) - - Return integer-valued system configuration values. If the configuration value - specified by *name* isn't defined, ``-1`` is returned. The comments regarding - the *name* parameter for :func:`confstr` apply here as well; the dictionary that - provides information on the known names is given by ``sysconf_names``. - - .. availability:: Unix. - - -.. data:: sysconf_names - - Dictionary mapping names accepted by :func:`sysconf` to the integer values - defined for those names by the host operating system. This can be used to - determine the set of names known to the system. - - .. availability:: Unix. - -The following data values are used to support path manipulation operations. These -are defined for all platforms. - -Higher-level operations on pathnames are defined in the :mod:`os.path` module. - - -.. index:: single: . (dot); in pathnames -.. data:: curdir - - The constant string used by the operating system to refer to the current - directory. This is ``'.'`` for Windows and POSIX. Also available via - :mod:`os.path`. - - -.. index:: single: ..; in pathnames -.. data:: pardir - - The constant string used by the operating system to refer to the parent - directory. This is ``'..'`` for Windows and POSIX. Also available via - :mod:`os.path`. - - -.. index:: single: / (slash); in pathnames -.. index:: single: \ (backslash); in pathnames (Windows) -.. data:: sep - - The character used by the operating system to separate pathname components. - This is ``'/'`` for POSIX and ``'\\'`` for Windows. Note that knowing this - is not sufficient to be able to parse or concatenate pathnames --- use - :func:`os.path.split` and :func:`os.path.join` --- but it is occasionally - useful. Also available via :mod:`os.path`. - - -.. index:: single: / (slash); in pathnames -.. data:: altsep - - An alternative character used by the operating system to separate pathname - components, or ``None`` if only one separator character exists. This is set to - ``'/'`` on Windows systems where ``sep`` is a backslash. Also available via - :mod:`os.path`. - - -.. index:: single: . (dot); in pathnames -.. data:: extsep - - The character which separates the base filename from the extension; for example, - the ``'.'`` in :file:`os.py`. Also available via :mod:`os.path`. - - -.. index:: single: : (colon); path separator (POSIX) - single: ; (semicolon) -.. data:: pathsep - - The character conventionally used by the operating system to separate search - path components (as in :envvar:`PATH`), such as ``':'`` for POSIX or ``';'`` for - Windows. Also available via :mod:`os.path`. - - -.. data:: defpath - - The default search path used by :func:`exec\*p\* ` and - :func:`spawn\*p\* ` if the environment doesn't have a ``'PATH'`` - key. Also available via :mod:`os.path`. - - -.. data:: linesep - - The string used to separate (or, rather, terminate) lines on the current - platform. This may be a single character, such as ``'\n'`` for POSIX, or - multiple characters, for example, ``'\r\n'`` for Windows. Do not use - *os.linesep* as a line terminator when writing files opened in text mode (the - default); use a single ``'\n'`` instead, on all platforms. - - -.. data:: devnull - - The file path of the null device. For example: ``'/dev/null'`` for - POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. - -.. data:: RTLD_LAZY - RTLD_NOW - RTLD_GLOBAL - RTLD_LOCAL - RTLD_NODELETE - RTLD_NOLOAD - RTLD_DEEPBIND - - Flags for use with the :func:`~sys.setdlopenflags` and - :func:`~sys.getdlopenflags` functions. See the Unix manual page - :manpage:`dlopen(3)` for what the different flags mean. - - .. versionadded:: 3.3 - - -Random numbers --------------- - - -.. function:: getrandom(size, flags=0) - - Get up to *size* random bytes. The function can return less bytes than - requested. - - These bytes can be used to seed user-space random number generators or for - cryptographic purposes. - - ``getrandom()`` relies on entropy gathered from device drivers and other - sources of environmental noise. Unnecessarily reading large quantities of - data will have a negative impact on other users of the ``/dev/random`` and - ``/dev/urandom`` devices. - - The flags argument is a bit mask that can contain zero or more of the - following values ORed together: :py:data:`os.GRND_RANDOM` and - :py:data:`GRND_NONBLOCK`. - - See also the `Linux getrandom() manual page - `_. - - .. availability:: Linux 3.17 and newer. - - .. versionadded:: 3.6 - -.. function:: urandom(size) - - Return a string of *size* random bytes suitable for cryptographic use. - - This function returns random bytes from an OS-specific randomness source. The - returned data should be unpredictable enough for cryptographic applications, - though its exact quality depends on the OS implementation. - - On Linux, if the ``getrandom()`` syscall is available, it is used in - blocking mode: block until the system urandom entropy pool is initialized - (128 bits of entropy are collected by the kernel). See the :pep:`524` for - the rationale. On Linux, the :func:`getrandom` function can be used to get - random bytes in non-blocking mode (using the :data:`GRND_NONBLOCK` flag) or - to poll until the system urandom entropy pool is initialized. - - On a Unix-like system, random bytes are read from the ``/dev/urandom`` - device. If the ``/dev/urandom`` device is not available or not readable, the - :exc:`NotImplementedError` exception is raised. - - On Windows, it will use ``CryptGenRandom()``. - - .. seealso:: - The :mod:`secrets` module provides higher level functions. For an - easy-to-use interface to the random number generator provided by your - platform, please see :class:`random.SystemRandom`. - - .. versionchanged:: 3.6.0 - On Linux, ``getrandom()`` is now used in blocking mode to increase the - security. - - .. versionchanged:: 3.5.2 - On Linux, if the ``getrandom()`` syscall blocks (the urandom entropy pool - is not initialized yet), fall back on reading ``/dev/urandom``. - - .. versionchanged:: 3.5 - On Linux 3.17 and newer, the ``getrandom()`` syscall is now used - when available. On OpenBSD 5.6 and newer, the C ``getentropy()`` - function is now used. These functions avoid the usage of an internal file - descriptor. - -.. data:: GRND_NONBLOCK - - By default, when reading from ``/dev/random``, :func:`getrandom` blocks if - no random bytes are available, and when reading from ``/dev/urandom``, it blocks - if the entropy pool has not yet been initialized. - - If the :py:data:`GRND_NONBLOCK` flag is set, then :func:`getrandom` does not - block in these cases, but instead immediately raises :exc:`BlockingIOError`. - - .. versionadded:: 3.6 - -.. data:: GRND_RANDOM - - If this bit is set, then random bytes are drawn from the - ``/dev/random`` pool instead of the ``/dev/urandom`` pool. - - .. versionadded:: 3.6 diff --git a/Doc/library/pty.rst.bak b/Doc/library/pty.rst.bak deleted file mode 100644 index 12268437d07e98..00000000000000 --- a/Doc/library/pty.rst.bak +++ /dev/null @@ -1,114 +0,0 @@ -:mod:`pty` --- Pseudo-terminal utilities -======================================== - -.. module:: pty - :platform: Linux - :synopsis: Pseudo-Terminal Handling for Linux. - -.. moduleauthor:: Steen Lumholt -.. sectionauthor:: Moshe Zadka - -**Source code:** :source:`Lib/pty.py` - --------------- - -The :mod:`pty` module defines operations for handling the pseudo-terminal -concept: starting another process and being able to write to and read from its -controlling terminal programmatically. - -Because pseudo-terminal handling is highly platform dependent, there is code to -do it only for Linux. (The Linux code is supposed to work on other platforms, -but hasn't been tested yet.) - -The :mod:`pty` module defines the following functions: - - -.. function:: fork() - - Fork. Connect the child's controlling terminal to a pseudo-terminal. Return - value is ``(pid, fd)``. Note that the child gets *pid* 0, and the *fd* is - *invalid*. The parent's return value is the *pid* of the child, and *fd* is a - file descriptor connected to the child's controlling terminal (and also to the - child's standard input and output). - - -.. function:: openpty() - - Open a new pseudo-terminal pair, using :func:`os.openpty` if possible, or - emulation code for generic Unix systems. Return a pair of file descriptors - ``(master, slave)``, for the master and the slave end, respectively. - - -.. function:: spawn(argv[, master_read[, stdin_read]]) - - Spawn a process, and connect its controlling terminal with the current - process's standard io. This is often used to baffle programs which insist on - reading from the controlling terminal. It is expected that the process - spawned behind the pty will eventually terminate, and when it does *spawn* - will return. - - The functions *master_read* and *stdin_read* are passed a file descriptor - which they should read from, and they should always return a byte string. In - order to force spawn to return before the child process exits an - :exc:`OSError` should be thrown. - - The default implementation for both functions will read and return up to 1024 - bytes each time the function is called. The *master_read* callback is passed - the pseudoterminal’s master file descriptor to read output from the child - process, and *stdin_read* is passed file descriptor 0, to read from the - parent process's standard input. - - Returning an empty byte string from either callback is interpreted as an - end-of-file (EOF) condition, and that callback will not be called after - that. If *stdin_read* signals EOF the controlling terminal can no longer - communicate with the parent process OR the child process. Unless the child - process will quit without any input, *spawn* will then loop forever. If - *master_read* signals EOF the same behavior results (on linux at least). - - If both callbacks signal EOF then *spawn* will probably never return, unless - *select* throws an error on your platform when passed three empty lists. This - is a bug, documented in `issue 26228 `_. - - - .. versionchanged:: 3.4 - :func:`spawn` now returns the status value from :func:`os.waitpid` - on the child process. - -Example -------- - -.. sectionauthor:: Steen Lumholt - -The following program acts like the Unix command :manpage:`script(1)`, using a -pseudo-terminal to record all input and output of a terminal session in a -"typescript". :: - - import argparse - import os - import pty - import sys - import time - - parser = argparse.ArgumentParser() - parser.add_argument('-a', dest='append', action='store_true') - parser.add_argument('-p', dest='use_python', action='store_true') - parser.add_argument('filename', nargs='?', default='typescript') - options = parser.parse_args() - - shell = sys.executable if options.use_python else os.environ.get('SHELL', 'sh') - filename = options.filename - mode = 'ab' if options.append else 'wb' - - with open(filename, mode) as script: - def read(fd): - data = os.read(fd, 1024) - script.write(data) - return data - - print('Script started, file is', filename) - script.write(('Script started on %s\n' % time.asctime()).encode()) - - pty.spawn(shell, read) - - script.write(('Script done on %s\n' % time.asctime()).encode()) - print('Script done, file is', filename) diff --git a/Doc/library/stdtypes.rst.bak b/Doc/library/stdtypes.rst.bak deleted file mode 100644 index fd3401fd18a099..00000000000000 --- a/Doc/library/stdtypes.rst.bak +++ /dev/null @@ -1,4885 +0,0 @@ -.. XXX: reference/datamodel and this have quite a few overlaps! - - -.. _bltin-types: - -************** -Built-in Types -************** - -The following sections describe the standard types that are built into the -interpreter. - -.. index:: pair: built-in; types - -The principal built-in types are numerics, sequences, mappings, classes, -instances and exceptions. - -Some collection classes are mutable. The methods that add, subtract, or -rearrange their members in place, and don't return a specific item, never return -the collection instance itself but ``None``. - -Some operations are supported by several object types; in particular, -practically all objects can be compared for equality, tested for truth -value, and converted to a string (with the :func:`repr` function or the -slightly different :func:`str` function). The latter function is implicitly -used when an object is written by the :func:`print` function. - - -.. _truth: - -Truth Value Testing -=================== - -.. index:: - statement: if - statement: while - pair: truth; value - pair: Boolean; operations - single: false - -Any object can be tested for truth value, for use in an :keyword:`if` or -:keyword:`while` condition or as operand of the Boolean operations below. - -.. index:: single: true - -By default, an object is considered true unless its class defines either a -:meth:`__bool__` method that returns ``False`` or a :meth:`__len__` method that -returns zero, when called with the object. [1]_ Here are most of the built-in -objects considered false: - - .. index:: - single: None (Built-in object) - single: False (Built-in object) - -* constants defined to be false: ``None`` and ``False``. - -* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``, - ``Fraction(0, 1)`` - -* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``, - ``range(0)`` - -.. index:: - operator: or - operator: and - single: False - single: True - -Operations and built-in functions that have a Boolean result always return ``0`` -or ``False`` for false and ``1`` or ``True`` for true, unless otherwise stated. -(Important exception: the Boolean operations ``or`` and ``and`` always return -one of their operands.) - - -.. _boolean: - -Boolean Operations --- :keyword:`!and`, :keyword:`!or`, :keyword:`!not` -======================================================================= - -.. index:: pair: Boolean; operations - -These are the Boolean operations, ordered by ascending priority: - -+-------------+---------------------------------+-------+ -| Operation | Result | Notes | -+=============+=================================+=======+ -| ``x or y`` | if *x* is false, then *y*, else | \(1) | -| | *x* | | -+-------------+---------------------------------+-------+ -| ``x and y`` | if *x* is false, then *x*, else | \(2) | -| | *y* | | -+-------------+---------------------------------+-------+ -| ``not x`` | if *x* is false, then ``True``, | \(3) | -| | else ``False`` | | -+-------------+---------------------------------+-------+ - -.. index:: - operator: and - operator: or - operator: not - -Notes: - -(1) - This is a short-circuit operator, so it only evaluates the second - argument if the first one is false. - -(2) - This is a short-circuit operator, so it only evaluates the second - argument if the first one is true. - -(3) - ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is - interpreted as ``not (a == b)``, and ``a == not b`` is a syntax error. - - -.. _stdcomparisons: - -Comparisons -=========== - -.. index:: - pair: chaining; comparisons - pair: operator; comparison - operator: == - operator: < (less) - operator: <= - operator: > (greater) - operator: >= - operator: != - operator: is - operator: is not - -There are eight comparison operations in Python. They all have the same -priority (which is higher than that of the Boolean operations). Comparisons can -be chained arbitrarily; for example, ``x < y <= z`` is equivalent to ``x < y and -y <= z``, except that *y* is evaluated only once (but in both cases *z* is not -evaluated at all when ``x < y`` is found to be false). - -This table summarizes the comparison operations: - -+------------+-------------------------+ -| Operation | Meaning | -+============+=========================+ -| ``<`` | strictly less than | -+------------+-------------------------+ -| ``<=`` | less than or equal | -+------------+-------------------------+ -| ``>`` | strictly greater than | -+------------+-------------------------+ -| ``>=`` | greater than or equal | -+------------+-------------------------+ -| ``==`` | equal | -+------------+-------------------------+ -| ``!=`` | not equal | -+------------+-------------------------+ -| ``is`` | object identity | -+------------+-------------------------+ -| ``is not`` | negated object identity | -+------------+-------------------------+ - -.. index:: - pair: object; numeric - pair: objects; comparing - -Objects of different types, except different numeric types, never compare equal. -The ``==`` operator is always defined but for some object types (for example, -class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=`` -operators are only defined where they make sense; for example, they raise a -:exc:`TypeError` exception when one of the arguments is a complex number. - -.. index:: - single: __eq__() (instance method) - single: __ne__() (instance method) - single: __lt__() (instance method) - single: __le__() (instance method) - single: __gt__() (instance method) - single: __ge__() (instance method) - -Non-identical instances of a class normally compare as non-equal unless the -class defines the :meth:`__eq__` method. - -Instances of a class cannot be ordered with respect to other instances of the -same class, or other types of object, unless the class defines enough of the -methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in -general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the -conventional meanings of the comparison operators). - -The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be -customized; also they can be applied to any two objects and never raise an -exception. - -.. index:: - operator: in - operator: not in - -Two more operations with the same syntactic priority, :keyword:`in` and -:keyword:`not in`, are supported by types that are :term:`iterable` or -implement the :meth:`__contains__` method. - -.. _typesnumeric: - -Numeric Types --- :class:`int`, :class:`float`, :class:`complex` -================================================================ - -.. index:: - object: numeric - object: Boolean - object: integer - object: floating point - object: complex number - pair: C; language - -There are three distinct numeric types: :dfn:`integers`, :dfn:`floating -point numbers`, and :dfn:`complex numbers`. In addition, Booleans are a -subtype of integers. Integers have unlimited precision. Floating point -numbers are usually implemented using :c:type:`double` in C; information -about the precision and internal representation of floating point -numbers for the machine on which your program is running is available -in :data:`sys.float_info`. Complex numbers have a real and imaginary -part, which are each a floating point number. To extract these parts -from a complex number *z*, use ``z.real`` and ``z.imag``. (The standard -library includes the additional numeric types :mod:`fractions.Fraction`, for -rationals, and :mod:`decimal.Decimal`, for floating-point numbers with -user-definable precision.) - -.. index:: - pair: numeric; literals - pair: integer; literals - pair: floating point; literals - pair: complex number; literals - pair: hexadecimal; literals - pair: octal; literals - pair: binary; literals - -Numbers are created by numeric literals or as the result of built-in functions -and operators. Unadorned integer literals (including hex, octal and binary -numbers) yield integers. Numeric literals containing a decimal point or an -exponent sign yield floating point numbers. Appending ``'j'`` or ``'J'`` to a -numeric literal yields an imaginary number (a complex number with a zero real -part) which you can add to an integer or float to get a complex number with real -and imaginary parts. - -.. index:: - single: arithmetic - builtin: int - builtin: float - builtin: complex - single: operator; + (plus) - single: + (plus); unary operator - single: + (plus); binary operator - single: operator; - (minus) - single: - (minus); unary operator - single: - (minus); binary operator - operator: * (asterisk) - operator: / (slash) - operator: // - operator: % (percent) - operator: ** - -Python fully supports mixed arithmetic: when a binary arithmetic operator has -operands of different numeric types, the operand with the "narrower" type is -widened to that of the other, where integer is narrower than floating point, -which is narrower than complex. Comparisons between numbers of mixed type use -the same rule. [2]_ The constructors :func:`int`, :func:`float`, and -:func:`complex` can be used to produce numbers of a specific type. - -All numeric types (except complex) support the following operations (for priorities of -the operations, see :ref:`operator-summary`): - -+---------------------+---------------------------------+---------+--------------------+ -| Operation | Result | Notes | Full documentation | -+=====================+=================================+=========+====================+ -| ``x + y`` | sum of *x* and *y* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``x - y`` | difference of *x* and *y* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``x * y`` | product of *x* and *y* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``x / y`` | quotient of *x* and *y* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``x // y`` | floored quotient of *x* and | \(1) | | -| | *y* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``x % y`` | remainder of ``x / y`` | \(2) | | -+---------------------+---------------------------------+---------+--------------------+ -| ``-x`` | *x* negated | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``+x`` | *x* unchanged | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``abs(x)`` | absolute value or magnitude of | | :func:`abs` | -| | *x* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``int(x)`` | *x* converted to integer | \(3)\(6)| :func:`int` | -+---------------------+---------------------------------+---------+--------------------+ -| ``float(x)`` | *x* converted to floating point | \(4)\(6)| :func:`float` | -+---------------------+---------------------------------+---------+--------------------+ -| ``complex(re, im)`` | a complex number with real part | \(6) | :func:`complex` | -| | *re*, imaginary part *im*. | | | -| | *im* defaults to zero. | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``c.conjugate()`` | conjugate of the complex number | | | -| | *c* | | | -+---------------------+---------------------------------+---------+--------------------+ -| ``divmod(x, y)`` | the pair ``(x // y, x % y)`` | \(2) | :func:`divmod` | -+---------------------+---------------------------------+---------+--------------------+ -| ``pow(x, y)`` | *x* to the power *y* | \(5) | :func:`pow` | -+---------------------+---------------------------------+---------+--------------------+ -| ``x ** y`` | *x* to the power *y* | \(5) | | -+---------------------+---------------------------------+---------+--------------------+ - -.. index:: - triple: operations on; numeric; types - single: conjugate() (complex number method) - -Notes: - -(1) - Also referred to as integer division. The resultant value is a whole - integer, though the result's type is not necessarily int. The result is - always rounded towards minus infinity: ``1//2`` is ``0``, ``(-1)//2`` is - ``-1``, ``1//(-2)`` is ``-1``, and ``(-1)//(-2)`` is ``0``. - -(2) - Not for complex numbers. Instead convert to floats using :func:`abs` if - appropriate. - -(3) - .. index:: - module: math - single: floor() (in module math) - single: ceil() (in module math) - single: trunc() (in module math) - pair: numeric; conversions - pair: C; language - - Conversion from floating point to integer may round or truncate - as in C; see functions :func:`math.floor` and :func:`math.ceil` for - well-defined conversions. - -(4) - float also accepts the strings "nan" and "inf" with an optional prefix "+" - or "-" for Not a Number (NaN) and positive or negative infinity. - -(5) - Python defines ``pow(0, 0)`` and ``0 ** 0`` to be ``1``, as is common for - programming languages. - -(6) - The numeric literals accepted include the digits ``0`` to ``9`` or any - Unicode equivalent (code points with the ``Nd`` property). - - See http://www.unicode.org/Public/12.1.0/ucd/extracted/DerivedNumericType.txt - for a complete list of code points with the ``Nd`` property. - - -All :class:`numbers.Real` types (:class:`int` and :class:`float`) also include -the following operations: - -+--------------------+---------------------------------------------+ -| Operation | Result | -+====================+=============================================+ -| :func:`math.trunc(\| *x* truncated to :class:`~numbers.Integral` | -| x) ` | | -+--------------------+---------------------------------------------+ -| :func:`round(x[, | *x* rounded to *n* digits, | -| n]) ` | rounding half to even. If *n* is | -| | omitted, it defaults to 0. | -+--------------------+---------------------------------------------+ -| :func:`math.floor(\| the greatest :class:`~numbers.Integral` | -| x) ` | <= *x* | -+--------------------+---------------------------------------------+ -| :func:`math.ceil(x)| the least :class:`~numbers.Integral` >= *x* | -| ` | | -+--------------------+---------------------------------------------+ - -For additional numeric operations see the :mod:`math` and :mod:`cmath` -modules. - -.. XXXJH exceptions: overflow (when? what operations?) zerodivision - - -.. _bitstring-ops: - -Bitwise Operations on Integer Types ------------------------------------ - -.. index:: - triple: operations on; integer; types - pair: bitwise; operations - pair: shifting; operations - pair: masking; operations - operator: | (vertical bar) - operator: ^ (caret) - operator: & (ampersand) - operator: << - operator: >> - operator: ~ (tilde) - -Bitwise operations only make sense for integers. The result of bitwise -operations is calculated as though carried out in two's complement with an -infinite number of sign bits. - -The priorities of the binary bitwise operations are all lower than the numeric -operations and higher than the comparisons; the unary operation ``~`` has the -same priority as the other unary numeric operations (``+`` and ``-``). - -This table lists the bitwise operations sorted in ascending priority: - -+------------+--------------------------------+----------+ -| Operation | Result | Notes | -+============+================================+==========+ -| ``x | y`` | bitwise :dfn:`or` of *x* and | \(4) | -| | *y* | | -+------------+--------------------------------+----------+ -| ``x ^ y`` | bitwise :dfn:`exclusive or` of | \(4) | -| | *x* and *y* | | -+------------+--------------------------------+----------+ -| ``x & y`` | bitwise :dfn:`and` of *x* and | \(4) | -| | *y* | | -+------------+--------------------------------+----------+ -| ``x << n`` | *x* shifted left by *n* bits | (1)(2) | -+------------+--------------------------------+----------+ -| ``x >> n`` | *x* shifted right by *n* bits | (1)(3) | -+------------+--------------------------------+----------+ -| ``~x`` | the bits of *x* inverted | | -+------------+--------------------------------+----------+ - -Notes: - -(1) - Negative shift counts are illegal and cause a :exc:`ValueError` to be raised. - -(2) - A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)`` - without overflow check. - -(3) - A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without - overflow check. - -(4) - Performing these calculations with at least one extra sign extension bit in - a finite two's complement representation (a working bit-width of - ``1 + max(x.bit_length(), y.bit_length())`` or more) is sufficient to get the - same result as if there were an infinite number of sign bits. - - -Additional Methods on Integer Types ------------------------------------ - -The int type implements the :class:`numbers.Integral` :term:`abstract base -class`. In addition, it provides a few more methods: - -.. method:: int.bit_length() - - Return the number of bits necessary to represent an integer in binary, - excluding the sign and leading zeros:: - - >>> n = -37 - >>> bin(n) - '-0b100101' - >>> n.bit_length() - 6 - - More precisely, if ``x`` is nonzero, then ``x.bit_length()`` is the - unique positive integer ``k`` such that ``2**(k-1) <= abs(x) < 2**k``. - Equivalently, when ``abs(x)`` is small enough to have a correctly - rounded logarithm, then ``k = 1 + int(log(abs(x), 2))``. - If ``x`` is zero, then ``x.bit_length()`` returns ``0``. - - Equivalent to:: - - def bit_length(self): - s = bin(self) # binary representation: bin(-37) --> '-0b100101' - s = s.lstrip('-0b') # remove leading zeros and minus sign - return len(s) # len('100101') --> 6 - - .. versionadded:: 3.1 - -.. method:: int.to_bytes(length, byteorder, \*, signed=False) - - Return an array of bytes representing an integer. - - >>> (1024).to_bytes(2, byteorder='big') - b'\x04\x00' - >>> (1024).to_bytes(10, byteorder='big') - b'\x00\x00\x00\x00\x00\x00\x00\x00\x04\x00' - >>> (-1024).to_bytes(10, byteorder='big', signed=True) - b'\xff\xff\xff\xff\xff\xff\xff\xff\xfc\x00' - >>> x = 1000 - >>> x.to_bytes((x.bit_length() + 7) // 8, byteorder='little') - b'\xe8\x03' - - The integer is represented using *length* bytes. An :exc:`OverflowError` - is raised if the integer is not representable with the given number of - bytes. - - The *byteorder* argument determines the byte order used to represent the - integer. If *byteorder* is ``"big"``, the most significant byte is at the - beginning of the byte array. If *byteorder* is ``"little"``, the most - significant byte is at the end of the byte array. To request the native - byte order of the host system, use :data:`sys.byteorder` as the byte order - value. - - The *signed* argument determines whether two's complement is used to - represent the integer. If *signed* is ``False`` and a negative integer is - given, an :exc:`OverflowError` is raised. The default value for *signed* - is ``False``. - - .. versionadded:: 3.2 - -.. classmethod:: int.from_bytes(bytes, byteorder, \*, signed=False) - - Return the integer represented by the given array of bytes. - - >>> int.from_bytes(b'\x00\x10', byteorder='big') - 16 - >>> int.from_bytes(b'\x00\x10', byteorder='little') - 4096 - >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=True) - -1024 - >>> int.from_bytes(b'\xfc\x00', byteorder='big', signed=False) - 64512 - >>> int.from_bytes([255, 0, 0], byteorder='big') - 16711680 - - The argument *bytes* must either be a :term:`bytes-like object` or an - iterable producing bytes. - - The *byteorder* argument determines the byte order used to represent the - integer. If *byteorder* is ``"big"``, the most significant byte is at the - beginning of the byte array. If *byteorder* is ``"little"``, the most - significant byte is at the end of the byte array. To request the native - byte order of the host system, use :data:`sys.byteorder` as the byte order - value. - - The *signed* argument indicates whether two's complement is used to - represent the integer. - - .. versionadded:: 3.2 - -.. method:: int.as_integer_ratio() - - Return a pair of integers whose ratio is exactly equal to the original - integer and with a positive denominator. The integer ratio of integers - (whole numbers) is always the integer as the numerator and ``1`` as the - denominator. - - .. versionadded:: 3.8 - -Additional Methods on Float ---------------------------- - -The float type implements the :class:`numbers.Real` :term:`abstract base -class`. float also has the following additional methods. - -.. method:: float.as_integer_ratio() - - Return a pair of integers whose ratio is exactly equal to the - original float and with a positive denominator. Raises - :exc:`OverflowError` on infinities and a :exc:`ValueError` on - NaNs. - -.. method:: float.is_integer() - - Return ``True`` if the float instance is finite with integral - value, and ``False`` otherwise:: - - >>> (-2.0).is_integer() - True - >>> (3.2).is_integer() - False - -Two methods support conversion to -and from hexadecimal strings. Since Python's floats are stored -internally as binary numbers, converting a float to or from a -*decimal* string usually involves a small rounding error. In -contrast, hexadecimal strings allow exact representation and -specification of floating-point numbers. This can be useful when -debugging, and in numerical work. - - -.. method:: float.hex() - - Return a representation of a floating-point number as a hexadecimal - string. For finite floating-point numbers, this representation - will always include a leading ``0x`` and a trailing ``p`` and - exponent. - - -.. classmethod:: float.fromhex(s) - - Class method to return the float represented by a hexadecimal - string *s*. The string *s* may have leading and trailing - whitespace. - - -Note that :meth:`float.hex` is an instance method, while -:meth:`float.fromhex` is a class method. - -A hexadecimal string takes the form:: - - [sign] ['0x'] integer ['.' fraction] ['p' exponent] - -where the optional ``sign`` may by either ``+`` or ``-``, ``integer`` -and ``fraction`` are strings of hexadecimal digits, and ``exponent`` -is a decimal integer with an optional leading sign. Case is not -significant, and there must be at least one hexadecimal digit in -either the integer or the fraction. This syntax is similar to the -syntax specified in section 6.4.4.2 of the C99 standard, and also to -the syntax used in Java 1.5 onwards. In particular, the output of -:meth:`float.hex` is usable as a hexadecimal floating-point literal in -C or Java code, and hexadecimal strings produced by C's ``%a`` format -character or Java's ``Double.toHexString`` are accepted by -:meth:`float.fromhex`. - - -Note that the exponent is written in decimal rather than hexadecimal, -and that it gives the power of 2 by which to multiply the coefficient. -For example, the hexadecimal string ``0x3.a7p10`` represents the -floating-point number ``(3 + 10./16 + 7./16**2) * 2.0**10``, or -``3740.0``:: - - >>> float.fromhex('0x3.a7p10') - 3740.0 - - -Applying the reverse conversion to ``3740.0`` gives a different -hexadecimal string representing the same number:: - - >>> float.hex(3740.0) - '0x1.d380000000000p+11' - - -.. _numeric-hash: - -Hashing of numeric types ------------------------- - -For numbers ``x`` and ``y``, possibly of different types, it's a requirement -that ``hash(x) == hash(y)`` whenever ``x == y`` (see the :meth:`__hash__` -method documentation for more details). For ease of implementation and -efficiency across a variety of numeric types (including :class:`int`, -:class:`float`, :class:`decimal.Decimal` and :class:`fractions.Fraction`) -Python's hash for numeric types is based on a single mathematical function -that's defined for any rational number, and hence applies to all instances of -:class:`int` and :class:`fractions.Fraction`, and all finite instances of -:class:`float` and :class:`decimal.Decimal`. Essentially, this function is -given by reduction modulo ``P`` for a fixed prime ``P``. The value of ``P`` is -made available to Python as the :attr:`modulus` attribute of -:data:`sys.hash_info`. - -.. impl-detail:: - - Currently, the prime used is ``P = 2**31 - 1`` on machines with 32-bit C - longs and ``P = 2**61 - 1`` on machines with 64-bit C longs. - -Here are the rules in detail: - -- If ``x = m / n`` is a nonnegative rational number and ``n`` is not divisible - by ``P``, define ``hash(x)`` as ``m * invmod(n, P) % P``, where ``invmod(n, - P)`` gives the inverse of ``n`` modulo ``P``. - -- If ``x = m / n`` is a nonnegative rational number and ``n`` is - divisible by ``P`` (but ``m`` is not) then ``n`` has no inverse - modulo ``P`` and the rule above doesn't apply; in this case define - ``hash(x)`` to be the constant value ``sys.hash_info.inf``. - -- If ``x = m / n`` is a negative rational number define ``hash(x)`` - as ``-hash(-x)``. If the resulting hash is ``-1``, replace it with - ``-2``. - -- The particular values ``sys.hash_info.inf``, ``-sys.hash_info.inf`` - and ``sys.hash_info.nan`` are used as hash values for positive - infinity, negative infinity, or nans (respectively). (All hashable - nans have the same hash value.) - -- For a :class:`complex` number ``z``, the hash values of the real - and imaginary parts are combined by computing ``hash(z.real) + - sys.hash_info.imag * hash(z.imag)``, reduced modulo - ``2**sys.hash_info.width`` so that it lies in - ``range(-2**(sys.hash_info.width - 1), 2**(sys.hash_info.width - - 1))``. Again, if the result is ``-1``, it's replaced with ``-2``. - - -To clarify the above rules, here's some example Python code, -equivalent to the built-in hash, for computing the hash of a rational -number, :class:`float`, or :class:`complex`:: - - - import sys, math - - def hash_fraction(m, n): - """Compute the hash of a rational number m / n. - - Assumes m and n are integers, with n positive. - Equivalent to hash(fractions.Fraction(m, n)). - - """ - P = sys.hash_info.modulus - # Remove common factors of P. (Unnecessary if m and n already coprime.) - while m % P == n % P == 0: - m, n = m // P, n // P - - if n % P == 0: - hash_value = sys.hash_info.inf - else: - # Fermat's Little Theorem: pow(n, P-1, P) is 1, so - # pow(n, P-2, P) gives the inverse of n modulo P. - hash_value = (abs(m) % P) * pow(n, P - 2, P) % P - if m < 0: - hash_value = -hash_value - if hash_value == -1: - hash_value = -2 - return hash_value - - def hash_float(x): - """Compute the hash of a float x.""" - - if math.isnan(x): - return sys.hash_info.nan - elif math.isinf(x): - return sys.hash_info.inf if x > 0 else -sys.hash_info.inf - else: - return hash_fraction(*x.as_integer_ratio()) - - def hash_complex(z): - """Compute the hash of a complex number z.""" - - hash_value = hash_float(z.real) + sys.hash_info.imag * hash_float(z.imag) - # do a signed reduction modulo 2**sys.hash_info.width - M = 2**(sys.hash_info.width - 1) - hash_value = (hash_value & (M - 1)) - (hash_value & M) - if hash_value == -1: - hash_value = -2 - return hash_value - -.. _typeiter: - -Iterator Types -============== - -.. index:: - single: iterator protocol - single: protocol; iterator - single: sequence; iteration - single: container; iteration over - -Python supports a concept of iteration over containers. This is implemented -using two distinct methods; these are used to allow user-defined classes to -support iteration. Sequences, described below in more detail, always support -the iteration methods. - -One method needs to be defined for container objects to provide iteration -support: - -.. XXX duplicated in reference/datamodel! - -.. method:: container.__iter__() - - Return an iterator object. The object is required to support the iterator - protocol described below. If a container supports different types of - iteration, additional methods can be provided to specifically request - iterators for those iteration types. (An example of an object supporting - multiple forms of iteration would be a tree structure which supports both - breadth-first and depth-first traversal.) This method corresponds to the - :c:member:`~PyTypeObject.tp_iter` slot of the type structure for Python objects in the Python/C - API. - -The iterator objects themselves are required to support the following two -methods, which together form the :dfn:`iterator protocol`: - - -.. method:: iterator.__iter__() - - Return the iterator object itself. This is required to allow both containers - and iterators to be used with the :keyword:`for` and :keyword:`in` statements. - This method corresponds to the :c:member:`~PyTypeObject.tp_iter` slot of the type structure for - Python objects in the Python/C API. - - -.. method:: iterator.__next__() - - Return the next item from the container. If there are no further items, raise - the :exc:`StopIteration` exception. This method corresponds to the - :c:member:`~PyTypeObject.tp_iternext` slot of the type structure for Python objects in the - Python/C API. - -Python defines several iterator objects to support iteration over general and -specific sequence types, dictionaries, and other more specialized forms. The -specific types are not important beyond their implementation of the iterator -protocol. - -Once an iterator's :meth:`~iterator.__next__` method raises -:exc:`StopIteration`, it must continue to do so on subsequent calls. -Implementations that do not obey this property are deemed broken. - - -.. _generator-types: - -Generator Types ---------------- - -Python's :term:`generator`\s provide a convenient way to implement the iterator -protocol. If a container object's :meth:`__iter__` method is implemented as a -generator, it will automatically return an iterator object (technically, a -generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__` -methods. -More information about generators can be found in :ref:`the documentation for -the yield expression `. - - -.. _typesseq: - -Sequence Types --- :class:`list`, :class:`tuple`, :class:`range` -================================================================ - -There are three basic sequence types: lists, tuples, and range objects. -Additional sequence types tailored for processing of -:ref:`binary data ` and :ref:`text strings ` are -described in dedicated sections. - - -.. _typesseq-common: - -Common Sequence Operations --------------------------- - -.. index:: object: sequence - -The operations in the following table are supported by most sequence types, -both mutable and immutable. The :class:`collections.abc.Sequence` ABC is -provided to make it easier to correctly implement these operations on -custom sequence types. - -This table lists the sequence operations sorted in ascending priority. In the -table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are -integers and *x* is an arbitrary object that meets any type and value -restrictions imposed by *s*. - -The ``in`` and ``not in`` operations have the same priorities as the -comparison operations. The ``+`` (concatenation) and ``*`` (repetition) -operations have the same priority as the corresponding numeric operations. [3]_ - -.. index:: - triple: operations on; sequence; types - builtin: len - builtin: min - builtin: max - pair: concatenation; operation - pair: repetition; operation - pair: subscript; operation - pair: slice; operation - operator: in - operator: not in - single: count() (sequence method) - single: index() (sequence method) - -+--------------------------+--------------------------------+----------+ -| Operation | Result | Notes | -+==========================+================================+==========+ -| ``x in s`` | ``True`` if an item of *s* is | \(1) | -| | equal to *x*, else ``False`` | | -+--------------------------+--------------------------------+----------+ -| ``x not in s`` | ``False`` if an item of *s* is | \(1) | -| | equal to *x*, else ``True`` | | -+--------------------------+--------------------------------+----------+ -| ``s + t`` | the concatenation of *s* and | (6)(7) | -| | *t* | | -+--------------------------+--------------------------------+----------+ -| ``s * n`` or | equivalent to adding *s* to | (2)(7) | -| ``n * s`` | itself *n* times | | -+--------------------------+--------------------------------+----------+ -| ``s[i]`` | *i*\ th item of *s*, origin 0 | \(3) | -+--------------------------+--------------------------------+----------+ -| ``s[i:j]`` | slice of *s* from *i* to *j* | (3)(4) | -+--------------------------+--------------------------------+----------+ -| ``s[i:j:k]`` | slice of *s* from *i* to *j* | (3)(5) | -| | with step *k* | | -+--------------------------+--------------------------------+----------+ -| ``len(s)`` | length of *s* | | -+--------------------------+--------------------------------+----------+ -| ``min(s)`` | smallest item of *s* | | -+--------------------------+--------------------------------+----------+ -| ``max(s)`` | largest item of *s* | | -+--------------------------+--------------------------------+----------+ -| ``s.index(x[, i[, j]])`` | index of the first occurrence | \(8) | -| | of *x* in *s* (at or after | | -| | index *i* and before index *j*)| | -+--------------------------+--------------------------------+----------+ -| ``s.count(x)`` | total number of occurrences of | | -| | *x* in *s* | | -+--------------------------+--------------------------------+----------+ - -Sequences of the same type also support comparisons. In particular, tuples -and lists are compared lexicographically by comparing corresponding elements. -This means that to compare equal, every element must compare equal and the -two sequences must be of the same type and have the same length. (For full -details see :ref:`comparisons` in the language reference.) - -Notes: - -(1) - While the ``in`` and ``not in`` operations are used only for simple - containment testing in the general case, some specialised sequences - (such as :class:`str`, :class:`bytes` and :class:`bytearray`) also use - them for subsequence testing:: - - >>> "gg" in "eggs" - True - -(2) - Values of *n* less than ``0`` are treated as ``0`` (which yields an empty - sequence of the same type as *s*). Note that items in the sequence *s* - are not copied; they are referenced multiple times. This often haunts - new Python programmers; consider:: - - >>> lists = [[]] * 3 - >>> lists - [[], [], []] - >>> lists[0].append(3) - >>> lists - [[3], [3], [3]] - - What has happened is that ``[[]]`` is a one-element list containing an empty - list, so all three elements of ``[[]] * 3`` are references to this single empty - list. Modifying any of the elements of ``lists`` modifies this single list. - You can create a list of different lists this way:: - - >>> lists = [[] for i in range(3)] - >>> lists[0].append(3) - >>> lists[1].append(5) - >>> lists[2].append(7) - >>> lists - [[3], [5], [7]] - - Further explanation is available in the FAQ entry - :ref:`faq-multidimensional-list`. - -(3) - If *i* or *j* is negative, the index is relative to the end of sequence *s*: - ``len(s) + i`` or ``len(s) + j`` is substituted. But note that ``-0`` is - still ``0``. - -(4) - The slice of *s* from *i* to *j* is defined as the sequence of items with index - *k* such that ``i <= k < j``. If *i* or *j* is greater than ``len(s)``, use - ``len(s)``. If *i* is omitted or ``None``, use ``0``. If *j* is omitted or - ``None``, use ``len(s)``. If *i* is greater than or equal to *j*, the slice is - empty. - -(5) - The slice of *s* from *i* to *j* with step *k* is defined as the sequence of - items with index ``x = i + n*k`` such that ``0 <= n < (j-i)/k``. In other words, - the indices are ``i``, ``i+k``, ``i+2*k``, ``i+3*k`` and so on, stopping when - *j* is reached (but never including *j*). When *k* is positive, - *i* and *j* are reduced to ``len(s)`` if they are greater. - When *k* is negative, *i* and *j* are reduced to ``len(s) - 1`` if - they are greater. If *i* or *j* are omitted or ``None``, they become - "end" values (which end depends on the sign of *k*). Note, *k* cannot be zero. - If *k* is ``None``, it is treated like ``1``. - -(6) - Concatenating immutable sequences always results in a new object. This - means that building up a sequence by repeated concatenation will have a - quadratic runtime cost in the total sequence length. To get a linear - runtime cost, you must switch to one of the alternatives below: - - * if concatenating :class:`str` objects, you can build a list and use - :meth:`str.join` at the end or else write to an :class:`io.StringIO` - instance and retrieve its value when complete - - * if concatenating :class:`bytes` objects, you can similarly use - :meth:`bytes.join` or :class:`io.BytesIO`, or you can do in-place - concatenation with a :class:`bytearray` object. :class:`bytearray` - objects are mutable and have an efficient overallocation mechanism - - * if concatenating :class:`tuple` objects, extend a :class:`list` instead - - * for other types, investigate the relevant class documentation - - -(7) - Some sequence types (such as :class:`range`) only support item sequences - that follow specific patterns, and hence don't support sequence - concatenation or repetition. - -(8) - ``index`` raises :exc:`ValueError` when *x* is not found in *s*. - Not all implementations support passing the additional arguments *i* and *j*. - These arguments allow efficient searching of subsections of the sequence. Passing - the extra arguments is roughly equivalent to using ``s[i:j].index(x)``, only - without copying any data and with the returned index being relative to - the start of the sequence rather than the start of the slice. - - -.. _typesseq-immutable: - -Immutable Sequence Types ------------------------- - -.. index:: - triple: immutable; sequence; types - object: tuple - builtin: hash - -The only operation that immutable sequence types generally implement that is -not also implemented by mutable sequence types is support for the :func:`hash` -built-in. - -This support allows immutable sequences, such as :class:`tuple` instances, to -be used as :class:`dict` keys and stored in :class:`set` and :class:`frozenset` -instances. - -Attempting to hash an immutable sequence that contains unhashable values will -result in :exc:`TypeError`. - - -.. _typesseq-mutable: - -Mutable Sequence Types ----------------------- - -.. index:: - triple: mutable; sequence; types - object: list - object: bytearray - -The operations in the following table are defined on mutable sequence types. -The :class:`collections.abc.MutableSequence` ABC is provided to make it -easier to correctly implement these operations on custom sequence types. - -In the table *s* is an instance of a mutable sequence type, *t* is any -iterable object and *x* is an arbitrary object that meets any type -and value restrictions imposed by *s* (for example, :class:`bytearray` only -accepts integers that meet the value restriction ``0 <= x <= 255``). - - -.. index:: - triple: operations on; sequence; types - triple: operations on; list; type - pair: subscript; assignment - pair: slice; assignment - statement: del - single: append() (sequence method) - single: clear() (sequence method) - single: copy() (sequence method) - single: extend() (sequence method) - single: insert() (sequence method) - single: pop() (sequence method) - single: remove() (sequence method) - single: reverse() (sequence method) - -+------------------------------+--------------------------------+---------------------+ -| Operation | Result | Notes | -+==============================+================================+=====================+ -| ``s[i] = x`` | item *i* of *s* is replaced by | | -| | *x* | | -+------------------------------+--------------------------------+---------------------+ -| ``s[i:j] = t`` | slice of *s* from *i* to *j* | | -| | is replaced by the contents of | | -| | the iterable *t* | | -+------------------------------+--------------------------------+---------------------+ -| ``del s[i:j]`` | same as ``s[i:j] = []`` | | -+------------------------------+--------------------------------+---------------------+ -| ``s[i:j:k] = t`` | the elements of ``s[i:j:k]`` | \(1) | -| | are replaced by those of *t* | | -+------------------------------+--------------------------------+---------------------+ -| ``del s[i:j:k]`` | removes the elements of | | -| | ``s[i:j:k]`` from the list | | -+------------------------------+--------------------------------+---------------------+ -| ``s.append(x)`` | appends *x* to the end of the | | -| | sequence (same as | | -| | ``s[len(s):len(s)] = [x]``) | | -+------------------------------+--------------------------------+---------------------+ -| ``s.clear()`` | removes all items from *s* | \(5) | -| | (same as ``del s[:]``) | | -+------------------------------+--------------------------------+---------------------+ -| ``s.copy()`` | creates a shallow copy of *s* | \(5) | -| | (same as ``s[:]``) | | -+------------------------------+--------------------------------+---------------------+ -| ``s.extend(t)`` or | extends *s* with the | | -| ``s += t`` | contents of *t* (for the | | -| | most part the same as | | -| | ``s[len(s):len(s)] = t``) | | -+------------------------------+--------------------------------+---------------------+ -| ``s *= n`` | updates *s* with its contents | \(6) | -| | repeated *n* times | | -+------------------------------+--------------------------------+---------------------+ -| ``s.insert(i, x)`` | inserts *x* into *s* at the | | -| | index given by *i* | | -| | (same as ``s[i:i] = [x]``) | | -+------------------------------+--------------------------------+---------------------+ -| ``s.pop([i])`` | retrieves the item at *i* and | \(2) | -| | also removes it from *s* | | -+------------------------------+--------------------------------+---------------------+ -| ``s.remove(x)`` | remove the first item from *s* | \(3) | -| | where ``s[i]`` is equal to *x* | | -+------------------------------+--------------------------------+---------------------+ -| ``s.reverse()`` | reverses the items of *s* in | \(4) | -| | place | | -+------------------------------+--------------------------------+---------------------+ - - -Notes: - -(1) - *t* must have the same length as the slice it is replacing. - -(2) - The optional argument *i* defaults to ``-1``, so that by default the last - item is removed and returned. - -(3) - :meth:`remove` raises :exc:`ValueError` when *x* is not found in *s*. - -(4) - The :meth:`reverse` method modifies the sequence in place for economy of - space when reversing a large sequence. To remind users that it operates by - side effect, it does not return the reversed sequence. - -(5) - :meth:`clear` and :meth:`!copy` are included for consistency with the - interfaces of mutable containers that don't support slicing operations - (such as :class:`dict` and :class:`set`). :meth:`!copy` is not part of the - :class:`collections.abc.MutableSequence` ABC, but most concrete - mutable sequence classes provide it. - - .. versionadded:: 3.3 - :meth:`clear` and :meth:`!copy` methods. - -(6) - The value *n* is an integer, or an object implementing - :meth:`~object.__index__`. Zero and negative values of *n* clear - the sequence. Items in the sequence are not copied; they are referenced - multiple times, as explained for ``s * n`` under :ref:`typesseq-common`. - - -.. _typesseq-list: - -Lists ------ - -.. index:: object: list - -Lists are mutable sequences, typically used to store collections of -homogeneous items (where the precise degree of similarity will vary by -application). - -.. class:: list([iterable]) - - Lists may be constructed in several ways: - - * Using a pair of square brackets to denote the empty list: ``[]`` - * Using square brackets, separating items with commas: ``[a]``, ``[a, b, c]`` - * Using a list comprehension: ``[x for x in iterable]`` - * Using the type constructor: ``list()`` or ``list(iterable)`` - - The constructor builds a list whose items are the same and in the same - order as *iterable*'s items. *iterable* may be either a sequence, a - container that supports iteration, or an iterator object. If *iterable* - is already a list, a copy is made and returned, similar to ``iterable[:]``. - For example, ``list('abc')`` returns ``['a', 'b', 'c']`` and - ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``. - If no argument is given, the constructor creates a new empty list, ``[]``. - - - Many other operations also produce lists, including the :func:`sorted` - built-in. - - Lists implement all of the :ref:`common ` and - :ref:`mutable ` sequence operations. Lists also provide the - following additional method: - - .. method:: list.sort(*, key=None, reverse=False) - - This method sorts the list in place, using only ``<`` comparisons - between items. Exceptions are not suppressed - if any comparison operations - fail, the entire sort operation will fail (and the list will likely be left - in a partially modified state). - - :meth:`sort` accepts two arguments that can only be passed by keyword - (:ref:`keyword-only arguments `): - - *key* specifies a function of one argument that is used to extract a - comparison key from each list element (for example, ``key=str.lower``). - The key corresponding to each item in the list is calculated once and - then used for the entire sorting process. The default value of ``None`` - means that list items are sorted directly without calculating a separate - key value. - - The :func:`functools.cmp_to_key` utility is available to convert a 2.x - style *cmp* function to a *key* function. - - *reverse* is a boolean value. If set to ``True``, then the list elements - are sorted as if each comparison were reversed. - - This method modifies the sequence in place for economy of space when - sorting a large sequence. To remind users that it operates by side - effect, it does not return the sorted sequence (use :func:`sorted` to - explicitly request a new sorted list instance). - - The :meth:`sort` method is guaranteed to be stable. A sort is stable if it - guarantees not to change the relative order of elements that compare equal - --- this is helpful for sorting in multiple passes (for example, sort by - department, then by salary grade). - - For sorting examples and a brief sorting tutorial, see :ref:`sortinghowto`. - - .. impl-detail:: - - While a list is being sorted, the effect of attempting to mutate, or even - inspect, the list is undefined. The C implementation of Python makes the - list appear empty for the duration, and raises :exc:`ValueError` if it can - detect that the list has been mutated during a sort. - - -.. _typesseq-tuple: - -Tuples ------- - -.. index:: object: tuple - -Tuples are immutable sequences, typically used to store collections of -heterogeneous data (such as the 2-tuples produced by the :func:`enumerate` -built-in). Tuples are also used for cases where an immutable sequence of -homogeneous data is needed (such as allowing storage in a :class:`set` or -:class:`dict` instance). - -.. class:: tuple([iterable]) - - Tuples may be constructed in a number of ways: - - * Using a pair of parentheses to denote the empty tuple: ``()`` - * Using a trailing comma for a singleton tuple: ``a,`` or ``(a,)`` - * Separating items with commas: ``a, b, c`` or ``(a, b, c)`` - * Using the :func:`tuple` built-in: ``tuple()`` or ``tuple(iterable)`` - - The constructor builds a tuple whose items are the same and in the same - order as *iterable*'s items. *iterable* may be either a sequence, a - container that supports iteration, or an iterator object. If *iterable* - is already a tuple, it is returned unchanged. For example, - ``tuple('abc')`` returns ``('a', 'b', 'c')`` and - ``tuple( [1, 2, 3] )`` returns ``(1, 2, 3)``. - If no argument is given, the constructor creates a new empty tuple, ``()``. - - Note that it is actually the comma which makes a tuple, not the parentheses. - The parentheses are optional, except in the empty tuple case, or - when they are needed to avoid syntactic ambiguity. For example, - ``f(a, b, c)`` is a function call with three arguments, while - ``f((a, b, c))`` is a function call with a 3-tuple as the sole argument. - - Tuples implement all of the :ref:`common ` sequence - operations. - -For heterogeneous collections of data where access by name is clearer than -access by index, :func:`collections.namedtuple` may be a more appropriate -choice than a simple tuple object. - - -.. _typesseq-range: - -Ranges ------- - -.. index:: object: range - -The :class:`range` type represents an immutable sequence of numbers and is -commonly used for looping a specific number of times in :keyword:`for` -loops. - -.. class:: range(stop) - range(start, stop[, step]) - - The arguments to the range constructor must be integers (either built-in - :class:`int` or any object that implements the ``__index__`` special - method). If the *step* argument is omitted, it defaults to ``1``. - If the *start* argument is omitted, it defaults to ``0``. - If *step* is zero, :exc:`ValueError` is raised. - - For a positive *step*, the contents of a range ``r`` are determined by the - formula ``r[i] = start + step*i`` where ``i >= 0`` and - ``r[i] < stop``. - - For a negative *step*, the contents of the range are still determined by - the formula ``r[i] = start + step*i``, but the constraints are ``i >= 0`` - and ``r[i] > stop``. - - A range object will be empty if ``r[0]`` does not meet the value - constraint. Ranges do support negative indices, but these are interpreted - as indexing from the end of the sequence determined by the positive - indices. - - Ranges containing absolute values larger than :data:`sys.maxsize` are - permitted but some features (such as :func:`len`) may raise - :exc:`OverflowError`. - - Range examples:: - - >>> list(range(10)) - [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] - >>> list(range(1, 11)) - [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] - >>> list(range(0, 30, 5)) - [0, 5, 10, 15, 20, 25] - >>> list(range(0, 10, 3)) - [0, 3, 6, 9] - >>> list(range(0, -10, -1)) - [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] - >>> list(range(0)) - [] - >>> list(range(1, 0)) - [] - - Ranges implement all of the :ref:`common ` sequence operations - except concatenation and repetition (due to the fact that range objects can - only represent sequences that follow a strict pattern and repetition and - concatenation will usually violate that pattern). - - .. attribute:: start - - The value of the *start* parameter (or ``0`` if the parameter was - not supplied) - - .. attribute:: stop - - The value of the *stop* parameter - - .. attribute:: step - - The value of the *step* parameter (or ``1`` if the parameter was - not supplied) - -The advantage of the :class:`range` type over a regular :class:`list` or -:class:`tuple` is that a :class:`range` object will always take the same -(small) amount of memory, no matter the size of the range it represents (as it -only stores the ``start``, ``stop`` and ``step`` values, calculating individual -items and subranges as needed). - -Range objects implement the :class:`collections.abc.Sequence` ABC, and provide -features such as containment tests, element index lookup, slicing and -support for negative indices (see :ref:`typesseq`): - - >>> r = range(0, 20, 2) - >>> r - range(0, 20, 2) - >>> 11 in r - False - >>> 10 in r - True - >>> r.index(10) - 5 - >>> r[5] - 10 - >>> r[:5] - range(0, 10, 2) - >>> r[-1] - 18 - -Testing range objects for equality with ``==`` and ``!=`` compares -them as sequences. That is, two range objects are considered equal if -they represent the same sequence of values. (Note that two range -objects that compare equal might have different :attr:`~range.start`, -:attr:`~range.stop` and :attr:`~range.step` attributes, for example -``range(0) == range(2, 1, 3)`` or ``range(0, 3, 2) == range(0, 4, 2)``.) - -.. versionchanged:: 3.2 - Implement the Sequence ABC. - Support slicing and negative indices. - Test :class:`int` objects for membership in constant time instead of - iterating through all items. - -.. versionchanged:: 3.3 - Define '==' and '!=' to compare range objects based on the - sequence of values they define (instead of comparing based on - object identity). - -.. versionadded:: 3.3 - The :attr:`~range.start`, :attr:`~range.stop` and :attr:`~range.step` - attributes. - -.. seealso:: - - * The `linspace recipe `_ - shows how to implement a lazy version of range suitable for floating - point applications. - -.. index:: - single: string; text sequence type - single: str (built-in class); (see also string) - object: string - -.. _textseq: - -Text Sequence Type --- :class:`str` -=================================== - -Textual data in Python is handled with :class:`str` objects, or :dfn:`strings`. -Strings are immutable -:ref:`sequences ` of Unicode code points. String literals are -written in a variety of ways: - -* Single quotes: ``'allows embedded "double" quotes'`` -* Double quotes: ``"allows embedded 'single' quotes"``. -* Triple quoted: ``'''Three single quotes'''``, ``"""Three double quotes"""`` - -Triple quoted strings may span multiple lines - all associated whitespace will -be included in the string literal. - -String literals that are part of a single expression and have only whitespace -between them will be implicitly converted to a single string literal. That -is, ``("spam " "eggs") == "spam eggs"``. - -See :ref:`strings` for more about the various forms of string literal, -including supported escape sequences, and the ``r`` ("raw") prefix that -disables most escape sequence processing. - -Strings may also be created from other objects using the :class:`str` -constructor. - -Since there is no separate "character" type, indexing a string produces -strings of length 1. That is, for a non-empty string *s*, ``s[0] == s[0:1]``. - -.. index:: - object: io.StringIO - -There is also no mutable string type, but :meth:`str.join` or -:class:`io.StringIO` can be used to efficiently construct strings from -multiple fragments. - -.. versionchanged:: 3.3 - For backwards compatibility with the Python 2 series, the ``u`` prefix is - once again permitted on string literals. It has no effect on the meaning - of string literals and cannot be combined with the ``r`` prefix. - - -.. index:: - single: string; str (built-in class) - -.. class:: str(object='') - str(object=b'', encoding='utf-8', errors='strict') - - Return a :ref:`string ` version of *object*. If *object* is not - provided, returns the empty string. Otherwise, the behavior of ``str()`` - depends on whether *encoding* or *errors* is given, as follows. - - If neither *encoding* nor *errors* is given, ``str(object)`` returns - :meth:`object.__str__() `, which is the "informal" or nicely - printable string representation of *object*. For string objects, this is - the string itself. If *object* does not have a :meth:`~object.__str__` - method, then :func:`str` falls back to returning - :meth:`repr(object) `. - - .. index:: - single: buffer protocol; str (built-in class) - single: bytes; str (built-in class) - - If at least one of *encoding* or *errors* is given, *object* should be a - :term:`bytes-like object` (e.g. :class:`bytes` or :class:`bytearray`). In - this case, if *object* is a :class:`bytes` (or :class:`bytearray`) object, - then ``str(bytes, encoding, errors)`` is equivalent to - :meth:`bytes.decode(encoding, errors) `. Otherwise, the bytes - object underlying the buffer object is obtained before calling - :meth:`bytes.decode`. See :ref:`binaryseq` and - :ref:`bufferobjects` for information on buffer objects. - - Passing a :class:`bytes` object to :func:`str` without the *encoding* - or *errors* arguments falls under the first case of returning the informal - string representation (see also the :option:`-b` command-line option to - Python). For example:: - - >>> str(b'Zoot!') - "b'Zoot!'" - - For more information on the ``str`` class and its methods, see - :ref:`textseq` and the :ref:`string-methods` section below. To output - formatted strings, see the :ref:`f-strings` and :ref:`formatstrings` - sections. In addition, see the :ref:`stringservices` section. - - -.. index:: - pair: string; methods - -.. _string-methods: - -String Methods --------------- - -.. index:: - module: re - -Strings implement all of the :ref:`common ` sequence -operations, along with the additional methods described below. - -Strings also support two styles of string formatting, one providing a large -degree of flexibility and customization (see :meth:`str.format`, -:ref:`formatstrings` and :ref:`string-formatting`) and the other based on C -``printf`` style formatting that handles a narrower range of types and is -slightly harder to use correctly, but is often faster for the cases it can -handle (:ref:`old-string-formatting`). - -The :ref:`textservices` section of the standard library covers a number of -other modules that provide various text related utilities (including regular -expression support in the :mod:`re` module). - -.. method:: str.capitalize() - - Return a copy of the string with its first character capitalized and the - rest lowercased. - - .. versionchanged:: 3.8 - The first character is now put into titlecase rather than uppercase. - This means that characters like digraphs will only have their first - letter capitalized, instead of the full character. - -.. method:: str.casefold() - - Return a casefolded copy of the string. Casefolded strings may be used for - caseless matching. - - Casefolding is similar to lowercasing but more aggressive because it is - intended to remove all case distinctions in a string. For example, the German - lowercase letter ``'ß'`` is equivalent to ``"ss"``. Since it is already - lowercase, :meth:`lower` would do nothing to ``'ß'``; :meth:`casefold` - converts it to ``"ss"``. - - The casefolding algorithm is described in section 3.13 of the Unicode - Standard. - - .. versionadded:: 3.3 - - -.. method:: str.center(width[, fillchar]) - - Return centered in a string of length *width*. Padding is done using the - specified *fillchar* (default is an ASCII space). The original string is - returned if *width* is less than or equal to ``len(s)``. - - - -.. method:: str.count(sub[, start[, end]]) - - Return the number of non-overlapping occurrences of substring *sub* in the - range [*start*, *end*]. Optional arguments *start* and *end* are - interpreted as in slice notation. - - -.. method:: str.encode(encoding="utf-8", errors="strict") - - Return an encoded version of the string as a bytes object. Default encoding - is ``'utf-8'``. *errors* may be given to set a different error handling scheme. - The default for *errors* is ``'strict'``, meaning that encoding errors raise - a :exc:`UnicodeError`. Other possible - values are ``'ignore'``, ``'replace'``, ``'xmlcharrefreplace'``, - ``'backslashreplace'`` and any other name registered via - :func:`codecs.register_error`, see section :ref:`error-handlers`. For a - list of possible encodings, see section :ref:`standard-encodings`. - - By default, the *errors* argument is not checked for best performances, but - only used at the first encoding error. Enable the :ref:`Python Development - Mode `, or use a debug build to check *errors*. - - .. versionchanged:: 3.1 - Support for keyword arguments added. - - .. versionchanged:: 3.9 - The *errors* is now checked in development mode and in debug mode. - - -.. method:: str.endswith(suffix[, start[, end]]) - - Return ``True`` if the string ends with the specified *suffix*, otherwise return - ``False``. *suffix* can also be a tuple of suffixes to look for. With optional - *start*, test beginning at that position. With optional *end*, stop comparing - at that position. - - -.. method:: str.expandtabs(tabsize=8) - - Return a copy of the string where all tab characters are replaced by one or - more spaces, depending on the current column and the given tab size. Tab - positions occur every *tabsize* characters (default is 8, giving tab - positions at columns 0, 8, 16 and so on). To expand the string, the current - column is set to zero and the string is examined character by character. If - the character is a tab (``\t``), one or more space characters are inserted - in the result until the current column is equal to the next tab position. - (The tab character itself is not copied.) If the character is a newline - (``\n``) or return (``\r``), it is copied and the current column is reset to - zero. Any other character is copied unchanged and the current column is - incremented by one regardless of how the character is represented when - printed. - - >>> '01\t012\t0123\t01234'.expandtabs() - '01 012 0123 01234' - >>> '01\t012\t0123\t01234'.expandtabs(4) - '01 012 0123 01234' - - -.. method:: str.find(sub[, start[, end]]) - - Return the lowest index in the string where substring *sub* is found within - the slice ``s[start:end]``. Optional arguments *start* and *end* are - interpreted as in slice notation. Return ``-1`` if *sub* is not found. - - .. note:: - - The :meth:`~str.find` method should be used only if you need to know the - position of *sub*. To check if *sub* is a substring or not, use the - :keyword:`in` operator:: - - >>> 'Py' in 'Python' - True - - -.. method:: str.format(*args, **kwargs) - - Perform a string formatting operation. The string on which this method is - called can contain literal text or replacement fields delimited by braces - ``{}``. Each replacement field contains either the numeric index of a - positional argument, or the name of a keyword argument. Returns a copy of - the string where each replacement field is replaced with the string value of - the corresponding argument. - - >>> "The sum of 1 + 2 is {0}".format(1+2) - 'The sum of 1 + 2 is 3' - - See :ref:`formatstrings` for a description of the various formatting options - that can be specified in format strings. - - .. note:: - When formatting a number (:class:`int`, :class:`float`, :class:`complex`, - :class:`decimal.Decimal` and subclasses) with the ``n`` type - (ex: ``'{:n}'.format(1234)``), the function temporarily sets the - ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale to decode - ``decimal_point`` and ``thousands_sep`` fields of :c:func:`localeconv` if - they are non-ASCII or longer than 1 byte, and the ``LC_NUMERIC`` locale is - different than the ``LC_CTYPE`` locale. This temporary change affects - other threads. - - .. versionchanged:: 3.7 - When formatting a number with the ``n`` type, the function sets - temporarily the ``LC_CTYPE`` locale to the ``LC_NUMERIC`` locale in some - cases. - - -.. method:: str.format_map(mapping) - - Similar to ``str.format(**mapping)``, except that ``mapping`` is - used directly and not copied to a :class:`dict`. This is useful - if for example ``mapping`` is a dict subclass: - - >>> class Default(dict): - ... def __missing__(self, key): - ... return key - ... - >>> '{name} was born in {country}'.format_map(Default(name='Guido')) - 'Guido was born in country' - - .. versionadded:: 3.2 - - -.. method:: str.index(sub[, start[, end]]) - - Like :meth:`~str.find`, but raise :exc:`ValueError` when the substring is - not found. - - -.. method:: str.isalnum() - - Return ``True`` if all characters in the string are alphanumeric and there is at - least one character, ``False`` otherwise. A character ``c`` is alphanumeric if one - of the following returns ``True``: ``c.isalpha()``, ``c.isdecimal()``, - ``c.isdigit()``, or ``c.isnumeric()``. - - -.. method:: str.isalpha() - - Return ``True`` if all characters in the string are alphabetic and there is at least - one character, ``False`` otherwise. Alphabetic characters are those characters defined - in the Unicode character database as "Letter", i.e., those with general category - property being one of "Lm", "Lt", "Lu", "Ll", or "Lo". Note that this is different - from the "Alphabetic" property defined in the Unicode Standard. - - -.. method:: str.isascii() - - Return ``True`` if the string is empty or all characters in the string are ASCII, - ``False`` otherwise. - ASCII characters have code points in the range U+0000-U+007F. - - .. versionadded:: 3.7 - - -.. method:: str.isdecimal() - - Return ``True`` if all characters in the string are decimal - characters and there is at least one character, ``False`` - otherwise. Decimal characters are those that can be used to form - numbers in base 10, e.g. U+0660, ARABIC-INDIC DIGIT - ZERO. Formally a decimal character is a character in the Unicode - General Category "Nd". - - -.. method:: str.isdigit() - - Return ``True`` if all characters in the string are digits and there is at least one - character, ``False`` otherwise. Digits include decimal characters and digits that need - special handling, such as the compatibility superscript digits. - This covers digits which cannot be used to form numbers in base 10, - like the Kharosthi numbers. Formally, a digit is a character that has the - property value Numeric_Type=Digit or Numeric_Type=Decimal. - - -.. method:: str.isidentifier() - - Return ``True`` if the string is a valid identifier according to the language - definition, section :ref:`identifiers`. - - Call :func:`keyword.iskeyword` to test whether string ``s`` is a reserved - identifier, such as :keyword:`def` and :keyword:`class`. - - Example: - :: - - >>> from keyword import iskeyword - - >>> 'hello'.isidentifier(), iskeyword('hello') - True, False - >>> 'def'.isidentifier(), iskeyword('def') - True, True - - -.. method:: str.islower() - - Return ``True`` if all cased characters [4]_ in the string are lowercase and - there is at least one cased character, ``False`` otherwise. - - -.. method:: str.isnumeric() - - Return ``True`` if all characters in the string are numeric - characters, and there is at least one character, ``False`` - otherwise. Numeric characters include digit characters, and all characters - that have the Unicode numeric value property, e.g. U+2155, - VULGAR FRACTION ONE FIFTH. Formally, numeric characters are those with the property - value Numeric_Type=Digit, Numeric_Type=Decimal or Numeric_Type=Numeric. - - -.. method:: str.isprintable() - - Return ``True`` if all characters in the string are printable or the string is - empty, ``False`` otherwise. Nonprintable characters are those characters defined - in the Unicode character database as "Other" or "Separator", excepting the - ASCII space (0x20) which is considered printable. (Note that printable - characters in this context are those which should not be escaped when - :func:`repr` is invoked on a string. It has no bearing on the handling of - strings written to :data:`sys.stdout` or :data:`sys.stderr`.) - - -.. method:: str.isspace() - - Return ``True`` if there are only whitespace characters in the string and there is - at least one character, ``False`` otherwise. - - A character is *whitespace* if in the Unicode character database - (see :mod:`unicodedata`), either its general category is ``Zs`` - ("Separator, space"), or its bidirectional class is one of ``WS``, - ``B``, or ``S``. - - -.. method:: str.istitle() - - Return ``True`` if the string is a titlecased string and there is at least one - character, for example uppercase characters may only follow uncased characters - and lowercase characters only cased ones. Return ``False`` otherwise. - - -.. method:: str.isupper() - - Return ``True`` if all cased characters [4]_ in the string are uppercase and - there is at least one cased character, ``False`` otherwise. - - >>> 'BANANA'.isupper() - True - >>> 'banana'.isupper() - False - >>> 'baNana'.isupper() - False - >>> ' '.isupper() - False - - - -.. method:: str.join(iterable) - - Return a string which is the concatenation of the strings in *iterable*. - A :exc:`TypeError` will be raised if there are any non-string values in - *iterable*, including :class:`bytes` objects. The separator between - elements is the string providing this method. - - -.. method:: str.ljust(width[, fillchar]) - - Return the string left justified in a string of length *width*. Padding is - done using the specified *fillchar* (default is an ASCII space). The - original string is returned if *width* is less than or equal to ``len(s)``. - - -.. method:: str.lower() - - Return a copy of the string with all the cased characters [4]_ converted to - lowercase. - - The lowercasing algorithm used is described in section 3.13 of the Unicode - Standard. - - -.. method:: str.lstrip([chars]) - - Return a copy of the string with leading characters removed. The *chars* - argument is a string specifying the set of characters to be removed. If omitted - or ``None``, the *chars* argument defaults to removing whitespace. The *chars* - argument is not a prefix; rather, all combinations of its values are stripped:: - - >>> ' spacious '.lstrip() - 'spacious ' - >>> 'www.example.com'.lstrip('cmowz.') - 'example.com' - - -.. staticmethod:: str.maketrans(x[, y[, z]]) - - This static method returns a translation table usable for :meth:`str.translate`. - - If there is only one argument, it must be a dictionary mapping Unicode - ordinals (integers) or characters (strings of length 1) to Unicode ordinals, - strings (of arbitrary lengths) or ``None``. Character keys will then be - converted to ordinals. - - If there are two arguments, they must be strings of equal length, and in the - resulting dictionary, each character in x will be mapped to the character at - the same position in y. If there is a third argument, it must be a string, - whose characters will be mapped to ``None`` in the result. - - -.. method:: str.partition(sep) - - Split the string at the first occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself, and the part - after the separator. If the separator is not found, return a 3-tuple containing - the string itself, followed by two empty strings. - - -.. method:: str.replace(old, new[, count]) - - Return a copy of the string with all occurrences of substring *old* replaced by - *new*. If the optional argument *count* is given, only the first *count* - occurrences are replaced. - - -.. method:: str.rfind(sub[, start[, end]]) - - Return the highest index in the string where substring *sub* is found, such - that *sub* is contained within ``s[start:end]``. Optional arguments *start* - and *end* are interpreted as in slice notation. Return ``-1`` on failure. - - -.. method:: str.rindex(sub[, start[, end]]) - - Like :meth:`rfind` but raises :exc:`ValueError` when the substring *sub* is not - found. - - -.. method:: str.rjust(width[, fillchar]) - - Return the string right justified in a string of length *width*. Padding is - done using the specified *fillchar* (default is an ASCII space). The - original string is returned if *width* is less than or equal to ``len(s)``. - - -.. method:: str.rpartition(sep) - - Split the string at the last occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself, and the part - after the separator. If the separator is not found, return a 3-tuple containing - two empty strings, followed by the string itself. - - -.. method:: str.rsplit(sep=None, maxsplit=-1) - - Return a list of the words in the string, using *sep* as the delimiter string. - If *maxsplit* is given, at most *maxsplit* splits are done, the *rightmost* - ones. If *sep* is not specified or ``None``, any whitespace string is a - separator. Except for splitting from the right, :meth:`rsplit` behaves like - :meth:`split` which is described in detail below. - - -.. method:: str.rstrip([chars]) - - Return a copy of the string with trailing characters removed. The *chars* - argument is a string specifying the set of characters to be removed. If omitted - or ``None``, the *chars* argument defaults to removing whitespace. The *chars* - argument is not a suffix; rather, all combinations of its values are stripped:: - - >>> ' spacious '.rstrip() - ' spacious' - >>> 'mississippi'.rstrip('ipz') - 'mississ' - - -.. method:: str.split(sep=None, maxsplit=-1) - - Return a list of the words in the string, using *sep* as the delimiter - string. If *maxsplit* is given, at most *maxsplit* splits are done (thus, - the list will have at most ``maxsplit+1`` elements). If *maxsplit* is not - specified or ``-1``, then there is no limit on the number of splits - (all possible splits are made). - - If *sep* is given, consecutive delimiters are not grouped together and are - deemed to delimit empty strings (for example, ``'1,,2'.split(',')`` returns - ``['1', '', '2']``). The *sep* argument may consist of multiple characters - (for example, ``'1<>2<>3'.split('<>')`` returns ``['1', '2', '3']``). - Splitting an empty string with a specified separator returns ``['']``. - - For example:: - - >>> '1,2,3'.split(',') - ['1', '2', '3'] - >>> '1,2,3'.split(',', maxsplit=1) - ['1', '2,3'] - >>> '1,2,,3,'.split(',') - ['1', '2', '', '3', ''] - - If *sep* is not specified or is ``None``, a different splitting algorithm is - applied: runs of consecutive whitespace are regarded as a single separator, - and the result will contain no empty strings at the start or end if the - string has leading or trailing whitespace. Consequently, splitting an empty - string or a string consisting of just whitespace with a ``None`` separator - returns ``[]``. - - For example:: - - >>> '1 2 3'.split() - ['1', '2', '3'] - >>> '1 2 3'.split(maxsplit=1) - ['1', '2 3'] - >>> ' 1 2 3 '.split() - ['1', '2', '3'] - - -.. index:: - single: universal newlines; str.splitlines method - -.. method:: str.splitlines([keepends]) - - Return a list of the lines in the string, breaking at line boundaries. Line - breaks are not included in the resulting list unless *keepends* is given and - true. - - This method splits on the following line boundaries. In particular, the - boundaries are a superset of :term:`universal newlines`. - - +-----------------------+-----------------------------+ - | Representation | Description | - +=======================+=============================+ - | ``\n`` | Line Feed | - +-----------------------+-----------------------------+ - | ``\r`` | Carriage Return | - +-----------------------+-----------------------------+ - | ``\r\n`` | Carriage Return + Line Feed | - +-----------------------+-----------------------------+ - | ``\v`` or ``\x0b`` | Line Tabulation | - +-----------------------+-----------------------------+ - | ``\f`` or ``\x0c`` | Form Feed | - +-----------------------+-----------------------------+ - | ``\x1c`` | File Separator | - +-----------------------+-----------------------------+ - | ``\x1d`` | Group Separator | - +-----------------------+-----------------------------+ - | ``\x1e`` | Record Separator | - +-----------------------+-----------------------------+ - | ``\x85`` | Next Line (C1 Control Code) | - +-----------------------+-----------------------------+ - | ``\u2028`` | Line Separator | - +-----------------------+-----------------------------+ - | ``\u2029`` | Paragraph Separator | - +-----------------------+-----------------------------+ - - .. versionchanged:: 3.2 - - ``\v`` and ``\f`` added to list of line boundaries. - - For example:: - - >>> 'ab c\n\nde fg\rkl\r\n'.splitlines() - ['ab c', '', 'de fg', 'kl'] - >>> 'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) - ['ab c\n', '\n', 'de fg\r', 'kl\r\n'] - - Unlike :meth:`~str.split` when a delimiter string *sep* is given, this - method returns an empty list for the empty string, and a terminal line - break does not result in an extra line:: - - >>> "".splitlines() - [] - >>> "One line\n".splitlines() - ['One line'] - - For comparison, ``split('\n')`` gives:: - - >>> ''.split('\n') - [''] - >>> 'Two lines\n'.split('\n') - ['Two lines', ''] - - -.. method:: str.startswith(prefix[, start[, end]]) - - Return ``True`` if string starts with the *prefix*, otherwise return ``False``. - *prefix* can also be a tuple of prefixes to look for. With optional *start*, - test string beginning at that position. With optional *end*, stop comparing - string at that position. - - -.. method:: str.strip([chars]) - - Return a copy of the string with the leading and trailing characters removed. - The *chars* argument is a string specifying the set of characters to be removed. - If omitted or ``None``, the *chars* argument defaults to removing whitespace. - The *chars* argument is not a prefix or suffix; rather, all combinations of its - values are stripped:: - - >>> ' spacious '.strip() - 'spacious' - >>> 'www.example.com'.strip('cmowz.') - 'example' - - The outermost leading and trailing *chars* argument values are stripped - from the string. Characters are removed from the leading end until - reaching a string character that is not contained in the set of - characters in *chars*. A similar action takes place on the trailing end. - For example:: - - >>> comment_string = '#....... Section 3.2.1 Issue #32 .......' - >>> comment_string.strip('.#! ') - 'Section 3.2.1 Issue #32' - - -.. method:: str.swapcase() - - Return a copy of the string with uppercase characters converted to lowercase and - vice versa. Note that it is not necessarily true that - ``s.swapcase().swapcase() == s``. - - -.. method:: str.title() - - Return a titlecased version of the string where words start with an uppercase - character and the remaining characters are lowercase. - - For example:: - - >>> 'Hello world'.title() - 'Hello World' - - The algorithm uses a simple language-independent definition of a word as - groups of consecutive letters. The definition works in many contexts but - it means that apostrophes in contractions and possessives form word - boundaries, which may not be the desired result:: - - >>> "they're bill's friends from the UK".title() - "They'Re Bill'S Friends From The Uk" - - A workaround for apostrophes can be constructed using regular expressions:: - - >>> import re - >>> def titlecase(s): - ... return re.sub(r"[A-Za-z]+('[A-Za-z]+)?", - ... lambda mo: mo.group(0).capitalize(), - ... s) - ... - >>> titlecase("they're bill's friends.") - "They're Bill's Friends." - - -.. method:: str.translate(table) - - Return a copy of the string in which each character has been mapped through - the given translation table. The table must be an object that implements - indexing via :meth:`__getitem__`, typically a :term:`mapping` or - :term:`sequence`. When indexed by a Unicode ordinal (an integer), the - table object can do any of the following: return a Unicode ordinal or a - string, to map the character to one or more other characters; return - ``None``, to delete the character from the return string; or raise a - :exc:`LookupError` exception, to map the character to itself. - - You can use :meth:`str.maketrans` to create a translation map from - character-to-character mappings in different formats. - - See also the :mod:`codecs` module for a more flexible approach to custom - character mappings. - - -.. method:: str.upper() - - Return a copy of the string with all the cased characters [4]_ converted to - uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s`` - contains uncased characters or if the Unicode category of the resulting - character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, - titlecase). - - The uppercasing algorithm used is described in section 3.13 of the Unicode - Standard. - - -.. method:: str.zfill(width) - - Return a copy of the string left filled with ASCII ``'0'`` digits to - make a string of length *width*. A leading sign prefix (``'+'``/``'-'``) - is handled by inserting the padding *after* the sign character rather - than before. The original string is returned if *width* is less than - or equal to ``len(s)``. - - For example:: - - >>> "42".zfill(5) - '00042' - >>> "-42".zfill(5) - '-0042' - - - -.. _old-string-formatting: - -``printf``-style String Formatting ----------------------------------- - -.. index:: - single: formatting, string (%) - single: interpolation, string (%) - single: string; formatting, printf - single: string; interpolation, printf - single: printf-style formatting - single: sprintf-style formatting - single: % (percent); printf-style formatting - -.. note:: - - The formatting operations described here exhibit a variety of quirks that - lead to a number of common errors (such as failing to display tuples and - dictionaries correctly). Using the newer :ref:`formatted string literals - `, the :meth:`str.format` interface, or :ref:`template strings - ` may help avoid these errors. Each of these - alternatives provides their own trade-offs and benefits of simplicity, - flexibility, and/or extensibility. - -String objects have one unique built-in operation: the ``%`` operator (modulo). -This is also known as the string *formatting* or *interpolation* operator. -Given ``format % values`` (where *format* is a string), ``%`` conversion -specifications in *format* are replaced with zero or more elements of *values*. -The effect is similar to using the :c:func:`sprintf` in the C language. - -If *format* requires a single argument, *values* may be a single non-tuple -object. [5]_ Otherwise, *values* must be a tuple with exactly the number of -items specified by the format string, or a single mapping object (for example, a -dictionary). - -.. index:: - single: () (parentheses); in printf-style formatting - single: * (asterisk); in printf-style formatting - single: . (dot); in printf-style formatting - -A conversion specifier contains two or more characters and has the following -components, which must occur in this order: - -#. The ``'%'`` character, which marks the start of the specifier. - -#. Mapping key (optional), consisting of a parenthesised sequence of characters - (for example, ``(somename)``). - -#. Conversion flags (optional), which affect the result of some conversion - types. - -#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the - actual width is read from the next element of the tuple in *values*, and the - object to convert comes after the minimum field width and optional precision. - -#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If - specified as ``'*'`` (an asterisk), the actual precision is read from the next - element of the tuple in *values*, and the value to convert comes after the - precision. - -#. Length modifier (optional). - -#. Conversion type. - -When the right argument is a dictionary (or other mapping type), then the -formats in the string *must* include a parenthesised mapping key into that -dictionary inserted immediately after the ``'%'`` character. The mapping key -selects the value to be formatted from the mapping. For example: - - >>> print('%(language)s has %(number)03d quote types.' % - ... {'language': "Python", "number": 2}) - Python has 002 quote types. - -In this case no ``*`` specifiers may occur in a format (since they require a -sequential parameter list). - -The conversion flag characters are: - -.. index:: - single: # (hash); in printf-style formatting - single: - (minus); in printf-style formatting - single: + (plus); in printf-style formatting - single: space; in printf-style formatting - -+---------+---------------------------------------------------------------------+ -| Flag | Meaning | -+=========+=====================================================================+ -| ``'#'`` | The value conversion will use the "alternate form" (where defined | -| | below). | -+---------+---------------------------------------------------------------------+ -| ``'0'`` | The conversion will be zero padded for numeric values. | -+---------+---------------------------------------------------------------------+ -| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | -| | conversion if both are given). | -+---------+---------------------------------------------------------------------+ -| ``' '`` | (a space) A blank should be left before a positive number (or empty | -| | string) produced by a signed conversion. | -+---------+---------------------------------------------------------------------+ -| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | -| | (overrides a "space" flag). | -+---------+---------------------------------------------------------------------+ - -A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it -is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. - -The conversion types are: - -+------------+-----------------------------------------------------+-------+ -| Conversion | Meaning | Notes | -+============+=====================================================+=======+ -| ``'d'`` | Signed integer decimal. | | -+------------+-----------------------------------------------------+-------+ -| ``'i'`` | Signed integer decimal. | | -+------------+-----------------------------------------------------+-------+ -| ``'o'`` | Signed octal value. | \(1) | -+------------+-----------------------------------------------------+-------+ -| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(6) | -+------------+-----------------------------------------------------+-------+ -| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | -+------------+-----------------------------------------------------+-------+ -| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | -+------------+-----------------------------------------------------+-------+ -| ``'e'`` | Floating point exponential format (lowercase). | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'E'`` | Floating point exponential format (uppercase). | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'f'`` | Floating point decimal format. | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'F'`` | Floating point decimal format. | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | -| | format if exponent is less than -4 or not less than | | -| | precision, decimal format otherwise. | | -+------------+-----------------------------------------------------+-------+ -| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | -| | format if exponent is less than -4 or not less than | | -| | precision, decimal format otherwise. | | -+------------+-----------------------------------------------------+-------+ -| ``'c'`` | Single character (accepts integer or single | | -| | character string). | | -+------------+-----------------------------------------------------+-------+ -| ``'r'`` | String (converts any Python object using | \(5) | -| | :func:`repr`). | | -+------------+-----------------------------------------------------+-------+ -| ``'s'`` | String (converts any Python object using | \(5) | -| | :func:`str`). | | -+------------+-----------------------------------------------------+-------+ -| ``'a'`` | String (converts any Python object using | \(5) | -| | :func:`ascii`). | | -+------------+-----------------------------------------------------+-------+ -| ``'%'`` | No argument is converted, results in a ``'%'`` | | -| | character in the result. | | -+------------+-----------------------------------------------------+-------+ - -Notes: - -(1) - The alternate form causes a leading octal specifier (``'0o'``) to be - inserted before the first digit. - -(2) - The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether - the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. - -(3) - The alternate form causes the result to always contain a decimal point, even if - no digits follow it. - - The precision determines the number of digits after the decimal point and - defaults to 6. - -(4) - The alternate form causes the result to always contain a decimal point, and - trailing zeroes are not removed as they would otherwise be. - - The precision determines the number of significant digits before and after the - decimal point and defaults to 6. - -(5) - If precision is ``N``, the output is truncated to ``N`` characters. - -(6) - See :pep:`237`. - -Since Python strings have an explicit length, ``%s`` conversions do not assume -that ``'\0'`` is the end of the string. - -.. XXX Examples? - -.. versionchanged:: 3.1 - ``%f`` conversions for numbers whose absolute value is over 1e50 are no - longer replaced by ``%g`` conversions. - - -.. index:: - single: buffer protocol; binary sequence types - -.. _binaryseq: - -Binary Sequence Types --- :class:`bytes`, :class:`bytearray`, :class:`memoryview` -================================================================================= - -.. index:: - object: bytes - object: bytearray - object: memoryview - module: array - -The core built-in types for manipulating binary data are :class:`bytes` and -:class:`bytearray`. They are supported by :class:`memoryview` which uses -the :ref:`buffer protocol ` to access the memory of other -binary objects without needing to make a copy. - -The :mod:`array` module supports efficient storage of basic data types like -32-bit integers and IEEE754 double-precision floating values. - -.. _typebytes: - -Bytes Objects -------------- - -.. index:: object: bytes - -Bytes objects are immutable sequences of single bytes. Since many major -binary protocols are based on the ASCII text encoding, bytes objects offer -several methods that are only valid when working with ASCII compatible -data and are closely related to string objects in a variety of other ways. - -.. class:: bytes([source[, encoding[, errors]]]) - - Firstly, the syntax for bytes literals is largely the same as that for string - literals, except that a ``b`` prefix is added: - - * Single quotes: ``b'still allows embedded "double" quotes'`` - * Double quotes: ``b"still allows embedded 'single' quotes"``. - * Triple quoted: ``b'''3 single quotes'''``, ``b"""3 double quotes"""`` - - Only ASCII characters are permitted in bytes literals (regardless of the - declared source code encoding). Any binary values over 127 must be entered - into bytes literals using the appropriate escape sequence. - - As with string literals, bytes literals may also use a ``r`` prefix to disable - processing of escape sequences. See :ref:`strings` for more about the various - forms of bytes literal, including supported escape sequences. - - While bytes literals and representations are based on ASCII text, bytes - objects actually behave like immutable sequences of integers, with each - value in the sequence restricted such that ``0 <= x < 256`` (attempts to - violate this restriction will trigger :exc:`ValueError`). This is done - deliberately to emphasise that while many binary formats include ASCII based - elements and can be usefully manipulated with some text-oriented algorithms, - this is not generally the case for arbitrary binary data (blindly applying - text processing algorithms to binary data formats that are not ASCII - compatible will usually lead to data corruption). - - In addition to the literal forms, bytes objects can be created in a number of - other ways: - - * A zero-filled bytes object of a specified length: ``bytes(10)`` - * From an iterable of integers: ``bytes(range(20))`` - * Copying existing binary data via the buffer protocol: ``bytes(obj)`` - - Also see the :ref:`bytes ` built-in. - - Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal - numbers are a commonly used format for describing binary data. Accordingly, - the bytes type has an additional class method to read data in that format: - - .. classmethod:: fromhex(string) - - This :class:`bytes` class method returns a bytes object, decoding the - given string object. The string must contain two hexadecimal digits per - byte, with ASCII whitespace being ignored. - - >>> bytes.fromhex('2Ef0 F1f2 ') - b'.\xf0\xf1\xf2' - - .. versionchanged:: 3.7 - :meth:`bytes.fromhex` now skips all ASCII whitespace in the string, - not just spaces. - - A reverse conversion function exists to transform a bytes object into its - hexadecimal representation. - - .. method:: hex() - - Return a string object containing two hexadecimal digits for each - byte in the instance. - - >>> b'\xf0\xf1\xf2'.hex() - 'f0f1f2' - - If you want to make the hex string easier to read, you can specify a - single character separator *sep* parameter to include in the output. - By default between each byte. A second optional *bytes_per_sep* - parameter controls the spacing. Positive values calculate the - separator position from the right, negative values from the left. - - >>> value = b'\xf0\xf1\xf2' - >>> value.hex('-') - 'f0-f1-f2' - >>> value.hex('_', 2) - 'f0_f1f2' - >>> b'UUDDLRLRAB'.hex(' ', -4) - '55554444 4c524c52 4142' - - .. versionadded:: 3.5 - - .. versionchanged:: 3.8 - :meth:`bytes.hex` now supports optional *sep* and *bytes_per_sep* - parameters to insert separators between bytes in the hex output. - -Since bytes objects are sequences of integers (akin to a tuple), for a bytes -object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be a bytes -object of length 1. (This contrasts with text strings, where both indexing -and slicing will produce a string of length 1) - -The representation of bytes objects uses the literal format (``b'...'``) -since it is often more useful than e.g. ``bytes([46, 46, 46])``. You can -always convert a bytes object into a list of integers using ``list(b)``. - -.. note:: - For Python 2.x users: In the Python 2.x series, a variety of implicit - conversions between 8-bit strings (the closest thing 2.x offers to a - built-in binary data type) and Unicode strings were permitted. This was a - backwards compatibility workaround to account for the fact that Python - originally only supported 8-bit text, and Unicode text was a later - addition. In Python 3.x, those implicit conversions are gone - conversions - between 8-bit binary data and Unicode text must be explicit, and bytes and - string objects will always compare unequal. - - -.. _typebytearray: - -Bytearray Objects ------------------ - -.. index:: object: bytearray - -:class:`bytearray` objects are a mutable counterpart to :class:`bytes` -objects. - -.. class:: bytearray([source[, encoding[, errors]]]) - - There is no dedicated literal syntax for bytearray objects, instead - they are always created by calling the constructor: - - * Creating an empty instance: ``bytearray()`` - * Creating a zero-filled instance with a given length: ``bytearray(10)`` - * From an iterable of integers: ``bytearray(range(20))`` - * Copying existing binary data via the buffer protocol: ``bytearray(b'Hi!')`` - - As bytearray objects are mutable, they support the - :ref:`mutable ` sequence operations in addition to the - common bytes and bytearray operations described in :ref:`bytes-methods`. - - Also see the :ref:`bytearray ` built-in. - - Since 2 hexadecimal digits correspond precisely to a single byte, hexadecimal - numbers are a commonly used format for describing binary data. Accordingly, - the bytearray type has an additional class method to read data in that format: - - .. classmethod:: fromhex(string) - - This :class:`bytearray` class method returns bytearray object, decoding - the given string object. The string must contain two hexadecimal digits - per byte, with ASCII whitespace being ignored. - - >>> bytearray.fromhex('2Ef0 F1f2 ') - bytearray(b'.\xf0\xf1\xf2') - - .. versionchanged:: 3.7 - :meth:`bytearray.fromhex` now skips all ASCII whitespace in the string, - not just spaces. - - A reverse conversion function exists to transform a bytearray object into its - hexadecimal representation. - - .. method:: hex() - - Return a string object containing two hexadecimal digits for each - byte in the instance. - - >>> bytearray(b'\xf0\xf1\xf2').hex() - 'f0f1f2' - - .. versionadded:: 3.5 - -Since bytearray objects are sequences of integers (akin to a list), for a -bytearray object *b*, ``b[0]`` will be an integer, while ``b[0:1]`` will be -a bytearray object of length 1. (This contrasts with text strings, where -both indexing and slicing will produce a string of length 1) - -The representation of bytearray objects uses the bytes literal format -(``bytearray(b'...')``) since it is often more useful than e.g. -``bytearray([46, 46, 46])``. You can always convert a bytearray object into -a list of integers using ``list(b)``. - - -.. _bytes-methods: - -Bytes and Bytearray Operations ------------------------------- - -.. index:: pair: bytes; methods - pair: bytearray; methods - -Both bytes and bytearray objects support the :ref:`common ` -sequence operations. They interoperate not just with operands of the same -type, but with any :term:`bytes-like object`. Due to this flexibility, they can be -freely mixed in operations without causing errors. However, the return type -of the result may depend on the order of operands. - -.. note:: - - The methods on bytes and bytearray objects don't accept strings as their - arguments, just as the methods on strings don't accept bytes as their - arguments. For example, you have to write:: - - a = "abc" - b = a.replace("a", "f") - - and:: - - a = b"abc" - b = a.replace(b"a", b"f") - -Some bytes and bytearray operations assume the use of ASCII compatible -binary formats, and hence should be avoided when working with arbitrary -binary data. These restrictions are covered below. - -.. note:: - Using these ASCII based operations to manipulate binary data that is not - stored in an ASCII based format may lead to data corruption. - -The following methods on bytes and bytearray objects can be used with -arbitrary binary data. - -.. method:: bytes.count(sub[, start[, end]]) - bytearray.count(sub[, start[, end]]) - - Return the number of non-overlapping occurrences of subsequence *sub* in - the range [*start*, *end*]. Optional arguments *start* and *end* are - interpreted as in slice notation. - - The subsequence to search for may be any :term:`bytes-like object` or an - integer in the range 0 to 255. - - .. versionchanged:: 3.3 - Also accept an integer in the range 0 to 255 as the subsequence. - - -.. method:: bytes.decode(encoding="utf-8", errors="strict") - bytearray.decode(encoding="utf-8", errors="strict") - - Return a string decoded from the given bytes. Default encoding is - ``'utf-8'``. *errors* may be given to set a different - error handling scheme. The default for *errors* is ``'strict'``, meaning - that encoding errors raise a :exc:`UnicodeError`. Other possible values are - ``'ignore'``, ``'replace'`` and any other name registered via - :func:`codecs.register_error`, see section :ref:`error-handlers`. For a - list of possible encodings, see section :ref:`standard-encodings`. - - By default, the *errors* argument is not checked for best performances, but - only used at the first decoding error. Enable the :ref:`Python Development - Mode `, or use a debug build to check *errors*. - - .. note:: - - Passing the *encoding* argument to :class:`str` allows decoding any - :term:`bytes-like object` directly, without needing to make a temporary - bytes or bytearray object. - - .. versionchanged:: 3.1 - Added support for keyword arguments. - - .. versionchanged:: 3.9 - The *errors* is now checked in development mode and in debug mode. - - -.. method:: bytes.endswith(suffix[, start[, end]]) - bytearray.endswith(suffix[, start[, end]]) - - Return ``True`` if the binary data ends with the specified *suffix*, - otherwise return ``False``. *suffix* can also be a tuple of suffixes to - look for. With optional *start*, test beginning at that position. With - optional *end*, stop comparing at that position. - - The suffix(es) to search for may be any :term:`bytes-like object`. - - -.. method:: bytes.find(sub[, start[, end]]) - bytearray.find(sub[, start[, end]]) - - Return the lowest index in the data where the subsequence *sub* is found, - such that *sub* is contained in the slice ``s[start:end]``. Optional - arguments *start* and *end* are interpreted as in slice notation. Return - ``-1`` if *sub* is not found. - - The subsequence to search for may be any :term:`bytes-like object` or an - integer in the range 0 to 255. - - .. note:: - - The :meth:`~bytes.find` method should be used only if you need to know the - position of *sub*. To check if *sub* is a substring or not, use the - :keyword:`in` operator:: - - >>> b'Py' in b'Python' - True - - .. versionchanged:: 3.3 - Also accept an integer in the range 0 to 255 as the subsequence. - - -.. method:: bytes.index(sub[, start[, end]]) - bytearray.index(sub[, start[, end]]) - - Like :meth:`~bytes.find`, but raise :exc:`ValueError` when the - subsequence is not found. - - The subsequence to search for may be any :term:`bytes-like object` or an - integer in the range 0 to 255. - - .. versionchanged:: 3.3 - Also accept an integer in the range 0 to 255 as the subsequence. - - -.. method:: bytes.join(iterable) - bytearray.join(iterable) - - Return a bytes or bytearray object which is the concatenation of the - binary data sequences in *iterable*. A :exc:`TypeError` will be raised - if there are any values in *iterable* that are not :term:`bytes-like - objects `, including :class:`str` objects. The - separator between elements is the contents of the bytes or - bytearray object providing this method. - - -.. staticmethod:: bytes.maketrans(from, to) - bytearray.maketrans(from, to) - - This static method returns a translation table usable for - :meth:`bytes.translate` that will map each character in *from* into the - character at the same position in *to*; *from* and *to* must both be - :term:`bytes-like objects ` and have the same length. - - .. versionadded:: 3.1 - - -.. method:: bytes.partition(sep) - bytearray.partition(sep) - - Split the sequence at the first occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself or its - bytearray copy, and the part after the separator. - If the separator is not found, return a 3-tuple - containing a copy of the original sequence, followed by two empty bytes or - bytearray objects. - - The separator to search for may be any :term:`bytes-like object`. - - -.. method:: bytes.replace(old, new[, count]) - bytearray.replace(old, new[, count]) - - Return a copy of the sequence with all occurrences of subsequence *old* - replaced by *new*. If the optional argument *count* is given, only the - first *count* occurrences are replaced. - - The subsequence to search for and its replacement may be any - :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.rfind(sub[, start[, end]]) - bytearray.rfind(sub[, start[, end]]) - - Return the highest index in the sequence where the subsequence *sub* is - found, such that *sub* is contained within ``s[start:end]``. Optional - arguments *start* and *end* are interpreted as in slice notation. Return - ``-1`` on failure. - - The subsequence to search for may be any :term:`bytes-like object` or an - integer in the range 0 to 255. - - .. versionchanged:: 3.3 - Also accept an integer in the range 0 to 255 as the subsequence. - - -.. method:: bytes.rindex(sub[, start[, end]]) - bytearray.rindex(sub[, start[, end]]) - - Like :meth:`~bytes.rfind` but raises :exc:`ValueError` when the - subsequence *sub* is not found. - - The subsequence to search for may be any :term:`bytes-like object` or an - integer in the range 0 to 255. - - .. versionchanged:: 3.3 - Also accept an integer in the range 0 to 255 as the subsequence. - - -.. method:: bytes.rpartition(sep) - bytearray.rpartition(sep) - - Split the sequence at the last occurrence of *sep*, and return a 3-tuple - containing the part before the separator, the separator itself or its - bytearray copy, and the part after the separator. - If the separator is not found, return a 3-tuple - containing two empty bytes or bytearray objects, followed by a copy of the - original sequence. - - The separator to search for may be any :term:`bytes-like object`. - - -.. method:: bytes.startswith(prefix[, start[, end]]) - bytearray.startswith(prefix[, start[, end]]) - - Return ``True`` if the binary data starts with the specified *prefix*, - otherwise return ``False``. *prefix* can also be a tuple of prefixes to - look for. With optional *start*, test beginning at that position. With - optional *end*, stop comparing at that position. - - The prefix(es) to search for may be any :term:`bytes-like object`. - - -.. method:: bytes.translate(table, /, delete=b'') - bytearray.translate(table, /, delete=b'') - - Return a copy of the bytes or bytearray object where all bytes occurring in - the optional argument *delete* are removed, and the remaining bytes have - been mapped through the given translation table, which must be a bytes - object of length 256. - - You can use the :func:`bytes.maketrans` method to create a translation - table. - - Set the *table* argument to ``None`` for translations that only delete - characters:: - - >>> b'read this short text'.translate(None, b'aeiou') - b'rd ths shrt txt' - - .. versionchanged:: 3.6 - *delete* is now supported as a keyword argument. - - -The following methods on bytes and bytearray objects have default behaviours -that assume the use of ASCII compatible binary formats, but can still be used -with arbitrary binary data by passing appropriate arguments. Note that all of -the bytearray methods in this section do *not* operate in place, and instead -produce new objects. - -.. method:: bytes.center(width[, fillbyte]) - bytearray.center(width[, fillbyte]) - - Return a copy of the object centered in a sequence of length *width*. - Padding is done using the specified *fillbyte* (default is an ASCII - space). For :class:`bytes` objects, the original sequence is returned if - *width* is less than or equal to ``len(s)``. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -.. method:: bytes.ljust(width[, fillbyte]) - bytearray.ljust(width[, fillbyte]) - - Return a copy of the object left justified in a sequence of length *width*. - Padding is done using the specified *fillbyte* (default is an ASCII - space). For :class:`bytes` objects, the original sequence is returned if - *width* is less than or equal to ``len(s)``. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -.. method:: bytes.lstrip([chars]) - bytearray.lstrip([chars]) - - Return a copy of the sequence with specified leading bytes removed. The - *chars* argument is a binary sequence specifying the set of byte values to - be removed - the name refers to the fact this method is usually used with - ASCII characters. If omitted or ``None``, the *chars* argument defaults - to removing ASCII whitespace. The *chars* argument is not a prefix; - rather, all combinations of its values are stripped:: - - >>> b' spacious '.lstrip() - b'spacious ' - >>> b'www.example.com'.lstrip(b'cmowz.') - b'example.com' - - The binary sequence of byte values to remove may be any - :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -.. method:: bytes.rjust(width[, fillbyte]) - bytearray.rjust(width[, fillbyte]) - - Return a copy of the object right justified in a sequence of length *width*. - Padding is done using the specified *fillbyte* (default is an ASCII - space). For :class:`bytes` objects, the original sequence is returned if - *width* is less than or equal to ``len(s)``. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -.. method:: bytes.rsplit(sep=None, maxsplit=-1) - bytearray.rsplit(sep=None, maxsplit=-1) - - Split the binary sequence into subsequences of the same type, using *sep* - as the delimiter string. If *maxsplit* is given, at most *maxsplit* splits - are done, the *rightmost* ones. If *sep* is not specified or ``None``, - any subsequence consisting solely of ASCII whitespace is a separator. - Except for splitting from the right, :meth:`rsplit` behaves like - :meth:`split` which is described in detail below. - - -.. method:: bytes.rstrip([chars]) - bytearray.rstrip([chars]) - - Return a copy of the sequence with specified trailing bytes removed. The - *chars* argument is a binary sequence specifying the set of byte values to - be removed - the name refers to the fact this method is usually used with - ASCII characters. If omitted or ``None``, the *chars* argument defaults to - removing ASCII whitespace. The *chars* argument is not a suffix; rather, - all combinations of its values are stripped:: - - >>> b' spacious '.rstrip() - b' spacious' - >>> b'mississippi'.rstrip(b'ipz') - b'mississ' - - The binary sequence of byte values to remove may be any - :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -.. method:: bytes.split(sep=None, maxsplit=-1) - bytearray.split(sep=None, maxsplit=-1) - - Split the binary sequence into subsequences of the same type, using *sep* - as the delimiter string. If *maxsplit* is given and non-negative, at most - *maxsplit* splits are done (thus, the list will have at most ``maxsplit+1`` - elements). If *maxsplit* is not specified or is ``-1``, then there is no - limit on the number of splits (all possible splits are made). - - If *sep* is given, consecutive delimiters are not grouped together and are - deemed to delimit empty subsequences (for example, ``b'1,,2'.split(b',')`` - returns ``[b'1', b'', b'2']``). The *sep* argument may consist of a - multibyte sequence (for example, ``b'1<>2<>3'.split(b'<>')`` returns - ``[b'1', b'2', b'3']``). Splitting an empty sequence with a specified - separator returns ``[b'']`` or ``[bytearray(b'')]`` depending on the type - of object being split. The *sep* argument may be any - :term:`bytes-like object`. - - For example:: - - >>> b'1,2,3'.split(b',') - [b'1', b'2', b'3'] - >>> b'1,2,3'.split(b',', maxsplit=1) - [b'1', b'2,3'] - >>> b'1,2,,3,'.split(b',') - [b'1', b'2', b'', b'3', b''] - - If *sep* is not specified or is ``None``, a different splitting algorithm - is applied: runs of consecutive ASCII whitespace are regarded as a single - separator, and the result will contain no empty strings at the start or - end if the sequence has leading or trailing whitespace. Consequently, - splitting an empty sequence or a sequence consisting solely of ASCII - whitespace without a specified separator returns ``[]``. - - For example:: - - - >>> b'1 2 3'.split() - [b'1', b'2', b'3'] - >>> b'1 2 3'.split(maxsplit=1) - [b'1', b'2 3'] - >>> b' 1 2 3 '.split() - [b'1', b'2', b'3'] - - -.. method:: bytes.strip([chars]) - bytearray.strip([chars]) - - Return a copy of the sequence with specified leading and trailing bytes - removed. The *chars* argument is a binary sequence specifying the set of - byte values to be removed - the name refers to the fact this method is - usually used with ASCII characters. If omitted or ``None``, the *chars* - argument defaults to removing ASCII whitespace. The *chars* argument is - not a prefix or suffix; rather, all combinations of its values are - stripped:: - - >>> b' spacious '.strip() - b'spacious' - >>> b'www.example.com'.strip(b'cmowz.') - b'example' - - The binary sequence of byte values to remove may be any - :term:`bytes-like object`. - - .. note:: - - The bytearray version of this method does *not* operate in place - - it always produces a new object, even if no changes were made. - - -The following methods on bytes and bytearray objects assume the use of ASCII -compatible binary formats and should not be applied to arbitrary binary data. -Note that all of the bytearray methods in this section do *not* operate in -place, and instead produce new objects. - -.. method:: bytes.capitalize() - bytearray.capitalize() - - Return a copy of the sequence with each byte interpreted as an ASCII - character, and the first byte capitalized and the rest lowercased. - Non-ASCII byte values are passed through unchanged. - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.expandtabs(tabsize=8) - bytearray.expandtabs(tabsize=8) - - Return a copy of the sequence where all ASCII tab characters are replaced - by one or more ASCII spaces, depending on the current column and the given - tab size. Tab positions occur every *tabsize* bytes (default is 8, - giving tab positions at columns 0, 8, 16 and so on). To expand the - sequence, the current column is set to zero and the sequence is examined - byte by byte. If the byte is an ASCII tab character (``b'\t'``), one or - more space characters are inserted in the result until the current column - is equal to the next tab position. (The tab character itself is not - copied.) If the current byte is an ASCII newline (``b'\n'``) or - carriage return (``b'\r'``), it is copied and the current column is reset - to zero. Any other byte value is copied unchanged and the current column - is incremented by one regardless of how the byte value is represented when - printed:: - - >>> b'01\t012\t0123\t01234'.expandtabs() - b'01 012 0123 01234' - >>> b'01\t012\t0123\t01234'.expandtabs(4) - b'01 012 0123 01234' - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.isalnum() - bytearray.isalnum() - - Return ``True`` if all bytes in the sequence are alphabetical ASCII characters - or ASCII decimal digits and the sequence is not empty, ``False`` otherwise. - Alphabetic ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. ASCII decimal - digits are those byte values in the sequence ``b'0123456789'``. - - For example:: - - >>> b'ABCabc1'.isalnum() - True - >>> b'ABC abc1'.isalnum() - False - - -.. method:: bytes.isalpha() - bytearray.isalpha() - - Return ``True`` if all bytes in the sequence are alphabetic ASCII characters - and the sequence is not empty, ``False`` otherwise. Alphabetic ASCII - characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - For example:: - - >>> b'ABCabc'.isalpha() - True - >>> b'ABCabc1'.isalpha() - False - - -.. method:: bytes.isascii() - bytearray.isascii() - - Return ``True`` if the sequence is empty or all bytes in the sequence are ASCII, - ``False`` otherwise. - ASCII bytes are in the range 0-0x7F. - - .. versionadded:: 3.7 - - -.. method:: bytes.isdigit() - bytearray.isdigit() - - Return ``True`` if all bytes in the sequence are ASCII decimal digits - and the sequence is not empty, ``False`` otherwise. ASCII decimal digits are - those byte values in the sequence ``b'0123456789'``. - - For example:: - - >>> b'1234'.isdigit() - True - >>> b'1.23'.isdigit() - False - - -.. method:: bytes.islower() - bytearray.islower() - - Return ``True`` if there is at least one lowercase ASCII character - in the sequence and no uppercase ASCII characters, ``False`` otherwise. - - For example:: - - >>> b'hello world'.islower() - True - >>> b'Hello world'.islower() - False - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - -.. method:: bytes.isspace() - bytearray.isspace() - - Return ``True`` if all bytes in the sequence are ASCII whitespace and the - sequence is not empty, ``False`` otherwise. ASCII whitespace characters are - those byte values in the sequence ``b' \t\n\r\x0b\f'`` (space, tab, newline, - carriage return, vertical tab, form feed). - - -.. method:: bytes.istitle() - bytearray.istitle() - - Return ``True`` if the sequence is ASCII titlecase and the sequence is not - empty, ``False`` otherwise. See :meth:`bytes.title` for more details on the - definition of "titlecase". - - For example:: - - >>> b'Hello World'.istitle() - True - >>> b'Hello world'.istitle() - False - - -.. method:: bytes.isupper() - bytearray.isupper() - - Return ``True`` if there is at least one uppercase alphabetic ASCII character - in the sequence and no lowercase ASCII characters, ``False`` otherwise. - - For example:: - - >>> b'HELLO WORLD'.isupper() - True - >>> b'Hello world'.isupper() - False - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - -.. method:: bytes.lower() - bytearray.lower() - - Return a copy of the sequence with all the uppercase ASCII characters - converted to their corresponding lowercase counterpart. - - For example:: - - >>> b'Hello World'.lower() - b'hello world' - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. index:: - single: universal newlines; bytes.splitlines method - single: universal newlines; bytearray.splitlines method - -.. method:: bytes.splitlines(keepends=False) - bytearray.splitlines(keepends=False) - - Return a list of the lines in the binary sequence, breaking at ASCII - line boundaries. This method uses the :term:`universal newlines` approach - to splitting lines. Line breaks are not included in the resulting list - unless *keepends* is given and true. - - For example:: - - >>> b'ab c\n\nde fg\rkl\r\n'.splitlines() - [b'ab c', b'', b'de fg', b'kl'] - >>> b'ab c\n\nde fg\rkl\r\n'.splitlines(keepends=True) - [b'ab c\n', b'\n', b'de fg\r', b'kl\r\n'] - - Unlike :meth:`~bytes.split` when a delimiter string *sep* is given, this - method returns an empty list for the empty string, and a terminal line - break does not result in an extra line:: - - >>> b"".split(b'\n'), b"Two lines\n".split(b'\n') - ([b''], [b'Two lines', b'']) - >>> b"".splitlines(), b"One line\n".splitlines() - ([], [b'One line']) - - -.. method:: bytes.swapcase() - bytearray.swapcase() - - Return a copy of the sequence with all the lowercase ASCII characters - converted to their corresponding uppercase counterpart and vice-versa. - - For example:: - - >>> b'Hello World'.swapcase() - b'hELLO wORLD' - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - Unlike :func:`str.swapcase()`, it is always the case that - ``bin.swapcase().swapcase() == bin`` for the binary versions. Case - conversions are symmetrical in ASCII, even though that is not generally - true for arbitrary Unicode code points. - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.title() - bytearray.title() - - Return a titlecased version of the binary sequence where words start with - an uppercase ASCII character and the remaining characters are lowercase. - Uncased byte values are left unmodified. - - For example:: - - >>> b'Hello world'.title() - b'Hello World' - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - All other byte values are uncased. - - The algorithm uses a simple language-independent definition of a word as - groups of consecutive letters. The definition works in many contexts but - it means that apostrophes in contractions and possessives form word - boundaries, which may not be the desired result:: - - >>> b"they're bill's friends from the UK".title() - b"They'Re Bill'S Friends From The Uk" - - A workaround for apostrophes can be constructed using regular expressions:: - - >>> import re - >>> def titlecase(s): - ... return re.sub(rb"[A-Za-z]+('[A-Za-z]+)?", - ... lambda mo: mo.group(0)[0:1].upper() + - ... mo.group(0)[1:].lower(), - ... s) - ... - >>> titlecase(b"they're bill's friends.") - b"They're Bill's Friends." - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.upper() - bytearray.upper() - - Return a copy of the sequence with all the lowercase ASCII characters - converted to their corresponding uppercase counterpart. - - For example:: - - >>> b'Hello World'.upper() - b'HELLO WORLD' - - Lowercase ASCII characters are those byte values in the sequence - ``b'abcdefghijklmnopqrstuvwxyz'``. Uppercase ASCII characters - are those byte values in the sequence ``b'ABCDEFGHIJKLMNOPQRSTUVWXYZ'``. - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. method:: bytes.zfill(width) - bytearray.zfill(width) - - Return a copy of the sequence left filled with ASCII ``b'0'`` digits to - make a sequence of length *width*. A leading sign prefix (``b'+'``/ - ``b'-'``) is handled by inserting the padding *after* the sign character - rather than before. For :class:`bytes` objects, the original sequence is - returned if *width* is less than or equal to ``len(seq)``. - - For example:: - - >>> b"42".zfill(5) - b'00042' - >>> b"-42".zfill(5) - b'-0042' - - .. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - - -.. _bytes-formatting: - -``printf``-style Bytes Formatting ----------------------------------- - -.. index:: - single: formatting; bytes (%) - single: formatting; bytearray (%) - single: interpolation; bytes (%) - single: interpolation; bytearray (%) - single: bytes; formatting - single: bytearray; formatting - single: bytes; interpolation - single: bytearray; interpolation - single: printf-style formatting - single: sprintf-style formatting - single: % (percent); printf-style formatting - -.. note:: - - The formatting operations described here exhibit a variety of quirks that - lead to a number of common errors (such as failing to display tuples and - dictionaries correctly). If the value being printed may be a tuple or - dictionary, wrap it in a tuple. - -Bytes objects (``bytes``/``bytearray``) have one unique built-in operation: -the ``%`` operator (modulo). -This is also known as the bytes *formatting* or *interpolation* operator. -Given ``format % values`` (where *format* is a bytes object), ``%`` conversion -specifications in *format* are replaced with zero or more elements of *values*. -The effect is similar to using the :c:func:`sprintf` in the C language. - -If *format* requires a single argument, *values* may be a single non-tuple -object. [5]_ Otherwise, *values* must be a tuple with exactly the number of -items specified by the format bytes object, or a single mapping object (for -example, a dictionary). - -.. index:: - single: () (parentheses); in printf-style formatting - single: * (asterisk); in printf-style formatting - single: . (dot); in printf-style formatting - -A conversion specifier contains two or more characters and has the following -components, which must occur in this order: - -#. The ``'%'`` character, which marks the start of the specifier. - -#. Mapping key (optional), consisting of a parenthesised sequence of characters - (for example, ``(somename)``). - -#. Conversion flags (optional), which affect the result of some conversion - types. - -#. Minimum field width (optional). If specified as an ``'*'`` (asterisk), the - actual width is read from the next element of the tuple in *values*, and the - object to convert comes after the minimum field width and optional precision. - -#. Precision (optional), given as a ``'.'`` (dot) followed by the precision. If - specified as ``'*'`` (an asterisk), the actual precision is read from the next - element of the tuple in *values*, and the value to convert comes after the - precision. - -#. Length modifier (optional). - -#. Conversion type. - -When the right argument is a dictionary (or other mapping type), then the -formats in the bytes object *must* include a parenthesised mapping key into that -dictionary inserted immediately after the ``'%'`` character. The mapping key -selects the value to be formatted from the mapping. For example: - - >>> print(b'%(language)s has %(number)03d quote types.' % - ... {b'language': b"Python", b"number": 2}) - b'Python has 002 quote types.' - -In this case no ``*`` specifiers may occur in a format (since they require a -sequential parameter list). - -The conversion flag characters are: - -.. index:: - single: # (hash); in printf-style formatting - single: - (minus); in printf-style formatting - single: + (plus); in printf-style formatting - single: space; in printf-style formatting - -+---------+---------------------------------------------------------------------+ -| Flag | Meaning | -+=========+=====================================================================+ -| ``'#'`` | The value conversion will use the "alternate form" (where defined | -| | below). | -+---------+---------------------------------------------------------------------+ -| ``'0'`` | The conversion will be zero padded for numeric values. | -+---------+---------------------------------------------------------------------+ -| ``'-'`` | The converted value is left adjusted (overrides the ``'0'`` | -| | conversion if both are given). | -+---------+---------------------------------------------------------------------+ -| ``' '`` | (a space) A blank should be left before a positive number (or empty | -| | string) produced by a signed conversion. | -+---------+---------------------------------------------------------------------+ -| ``'+'`` | A sign character (``'+'`` or ``'-'``) will precede the conversion | -| | (overrides a "space" flag). | -+---------+---------------------------------------------------------------------+ - -A length modifier (``h``, ``l``, or ``L``) may be present, but is ignored as it -is not necessary for Python -- so e.g. ``%ld`` is identical to ``%d``. - -The conversion types are: - -+------------+-----------------------------------------------------+-------+ -| Conversion | Meaning | Notes | -+============+=====================================================+=======+ -| ``'d'`` | Signed integer decimal. | | -+------------+-----------------------------------------------------+-------+ -| ``'i'`` | Signed integer decimal. | | -+------------+-----------------------------------------------------+-------+ -| ``'o'`` | Signed octal value. | \(1) | -+------------+-----------------------------------------------------+-------+ -| ``'u'`` | Obsolete type -- it is identical to ``'d'``. | \(8) | -+------------+-----------------------------------------------------+-------+ -| ``'x'`` | Signed hexadecimal (lowercase). | \(2) | -+------------+-----------------------------------------------------+-------+ -| ``'X'`` | Signed hexadecimal (uppercase). | \(2) | -+------------+-----------------------------------------------------+-------+ -| ``'e'`` | Floating point exponential format (lowercase). | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'E'`` | Floating point exponential format (uppercase). | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'f'`` | Floating point decimal format. | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'F'`` | Floating point decimal format. | \(3) | -+------------+-----------------------------------------------------+-------+ -| ``'g'`` | Floating point format. Uses lowercase exponential | \(4) | -| | format if exponent is less than -4 or not less than | | -| | precision, decimal format otherwise. | | -+------------+-----------------------------------------------------+-------+ -| ``'G'`` | Floating point format. Uses uppercase exponential | \(4) | -| | format if exponent is less than -4 or not less than | | -| | precision, decimal format otherwise. | | -+------------+-----------------------------------------------------+-------+ -| ``'c'`` | Single byte (accepts integer or single | | -| | byte objects). | | -+------------+-----------------------------------------------------+-------+ -| ``'b'`` | Bytes (any object that follows the | \(5) | -| | :ref:`buffer protocol ` or has | | -| | :meth:`__bytes__`). | | -+------------+-----------------------------------------------------+-------+ -| ``'s'`` | ``'s'`` is an alias for ``'b'`` and should only | \(6) | -| | be used for Python2/3 code bases. | | -+------------+-----------------------------------------------------+-------+ -| ``'a'`` | Bytes (converts any Python object using | \(5) | -| | ``repr(obj).encode('ascii','backslashreplace)``). | | -+------------+-----------------------------------------------------+-------+ -| ``'r'`` | ``'r'`` is an alias for ``'a'`` and should only | \(7) | -| | be used for Python2/3 code bases. | | -+------------+-----------------------------------------------------+-------+ -| ``'%'`` | No argument is converted, results in a ``'%'`` | | -| | character in the result. | | -+------------+-----------------------------------------------------+-------+ - -Notes: - -(1) - The alternate form causes a leading octal specifier (``'0o'``) to be - inserted before the first digit. - -(2) - The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether - the ``'x'`` or ``'X'`` format was used) to be inserted before the first digit. - -(3) - The alternate form causes the result to always contain a decimal point, even if - no digits follow it. - - The precision determines the number of digits after the decimal point and - defaults to 6. - -(4) - The alternate form causes the result to always contain a decimal point, and - trailing zeroes are not removed as they would otherwise be. - - The precision determines the number of significant digits before and after the - decimal point and defaults to 6. - -(5) - If precision is ``N``, the output is truncated to ``N`` characters. - -(6) - ``b'%s'`` is deprecated, but will not be removed during the 3.x series. - -(7) - ``b'%r'`` is deprecated, but will not be removed during the 3.x series. - -(8) - See :pep:`237`. - -.. note:: - - The bytearray version of this method does *not* operate in place - it - always produces a new object, even if no changes were made. - -.. seealso:: - - :pep:`461` - Adding % formatting to bytes and bytearray - -.. versionadded:: 3.5 - -.. _typememoryview: - -Memory Views ------------- - -:class:`memoryview` objects allow Python code to access the internal data -of an object that supports the :ref:`buffer protocol ` without -copying. - -.. class:: memoryview(obj) - - Create a :class:`memoryview` that references *obj*. *obj* must support the - buffer protocol. Built-in objects that support the buffer protocol include - :class:`bytes` and :class:`bytearray`. - - A :class:`memoryview` has the notion of an *element*, which is the - atomic memory unit handled by the originating object *obj*. For many - simple types such as :class:`bytes` and :class:`bytearray`, an element - is a single byte, but other types such as :class:`array.array` may have - bigger elements. - - ``len(view)`` is equal to the length of :class:`~memoryview.tolist`. - If ``view.ndim = 0``, the length is 1. If ``view.ndim = 1``, the length - is equal to the number of elements in the view. For higher dimensions, - the length is equal to the length of the nested list representation of - the view. The :class:`~memoryview.itemsize` attribute will give you the - number of bytes in a single element. - - A :class:`memoryview` supports slicing and indexing to expose its data. - One-dimensional slicing will result in a subview:: - - >>> v = memoryview(b'abcefg') - >>> v[1] - 98 - >>> v[-1] - 103 - >>> v[1:4] - - >>> bytes(v[1:4]) - b'bce' - - If :class:`~memoryview.format` is one of the native format specifiers - from the :mod:`struct` module, indexing with an integer or a tuple of - integers is also supported and returns a single *element* with - the correct type. One-dimensional memoryviews can be indexed - with an integer or a one-integer tuple. Multi-dimensional memoryviews - can be indexed with tuples of exactly *ndim* integers where *ndim* is - the number of dimensions. Zero-dimensional memoryviews can be indexed - with the empty tuple. - - Here is an example with a non-byte format:: - - >>> import array - >>> a = array.array('l', [-11111111, 22222222, -33333333, 44444444]) - >>> m = memoryview(a) - >>> m[0] - -11111111 - >>> m[-1] - 44444444 - >>> m[::2].tolist() - [-11111111, -33333333] - - If the underlying object is writable, the memoryview supports - one-dimensional slice assignment. Resizing is not allowed:: - - >>> data = bytearray(b'abcefg') - >>> v = memoryview(data) - >>> v.readonly - False - >>> v[0] = ord(b'z') - >>> data - bytearray(b'zbcefg') - >>> v[1:4] = b'123' - >>> data - bytearray(b'z123fg') - >>> v[2:3] = b'spam' - Traceback (most recent call last): - File "", line 1, in - ValueError: memoryview assignment: lvalue and rvalue have different structures - >>> v[2:6] = b'spam' - >>> data - bytearray(b'z1spam') - - One-dimensional memoryviews of hashable (read-only) types with formats - 'B', 'b' or 'c' are also hashable. The hash is defined as - ``hash(m) == hash(m.tobytes())``:: - - >>> v = memoryview(b'abcefg') - >>> hash(v) == hash(b'abcefg') - True - >>> hash(v[2:4]) == hash(b'ce') - True - >>> hash(v[::-2]) == hash(b'abcefg'[::-2]) - True - - .. versionchanged:: 3.3 - One-dimensional memoryviews can now be sliced. - One-dimensional memoryviews with formats 'B', 'b' or 'c' are now hashable. - - .. versionchanged:: 3.4 - memoryview is now registered automatically with - :class:`collections.abc.Sequence` - - .. versionchanged:: 3.5 - memoryviews can now be indexed with tuple of integers. - - :class:`memoryview` has several methods: - - .. method:: __eq__(exporter) - - A memoryview and a :pep:`3118` exporter are equal if their shapes are - equivalent and if all corresponding values are equal when the operands' - respective format codes are interpreted using :mod:`struct` syntax. - - For the subset of :mod:`struct` format strings currently supported by - :meth:`tolist`, ``v`` and ``w`` are equal if ``v.tolist() == w.tolist()``:: - - >>> import array - >>> a = array.array('I', [1, 2, 3, 4, 5]) - >>> b = array.array('d', [1.0, 2.0, 3.0, 4.0, 5.0]) - >>> c = array.array('b', [5, 3, 1]) - >>> x = memoryview(a) - >>> y = memoryview(b) - >>> x == a == y == b - True - >>> x.tolist() == a.tolist() == y.tolist() == b.tolist() - True - >>> z = y[::-2] - >>> z == c - True - >>> z.tolist() == c.tolist() - True - - If either format string is not supported by the :mod:`struct` module, - then the objects will always compare as unequal (even if the format - strings and buffer contents are identical):: - - >>> from ctypes import BigEndianStructure, c_long - >>> class BEPoint(BigEndianStructure): - ... _fields_ = [("x", c_long), ("y", c_long)] - ... - >>> point = BEPoint(100, 200) - >>> a = memoryview(point) - >>> b = memoryview(point) - >>> a == point - False - >>> a == b - False - - Note that, as with floating point numbers, ``v is w`` does *not* imply - ``v == w`` for memoryview objects. - - .. versionchanged:: 3.3 - Previous versions compared the raw memory disregarding the item format - and the logical array structure. - - .. method:: tobytes(order=None) - - Return the data in the buffer as a bytestring. This is equivalent to - calling the :class:`bytes` constructor on the memoryview. :: - - >>> m = memoryview(b"abc") - >>> m.tobytes() - b'abc' - >>> bytes(m) - b'abc' - - For non-contiguous arrays the result is equal to the flattened list - representation with all elements converted to bytes. :meth:`tobytes` - supports all format strings, including those that are not in - :mod:`struct` module syntax. - - .. versionadded:: 3.8 - *order* can be {'C', 'F', 'A'}. When *order* is 'C' or 'F', the data - of the original array is converted to C or Fortran order. For contiguous - views, 'A' returns an exact copy of the physical memory. In particular, - in-memory Fortran order is preserved. For non-contiguous views, the - data is converted to C first. *order=None* is the same as *order='C'*. - - .. method:: hex() - - Return a string object containing two hexadecimal digits for each - byte in the buffer. :: - - >>> m = memoryview(b"abc") - >>> m.hex() - '616263' - - .. versionadded:: 3.5 - - .. method:: tolist() - - Return the data in the buffer as a list of elements. :: - - >>> memoryview(b'abc').tolist() - [97, 98, 99] - >>> import array - >>> a = array.array('d', [1.1, 2.2, 3.3]) - >>> m = memoryview(a) - >>> m.tolist() - [1.1, 2.2, 3.3] - - .. versionchanged:: 3.3 - :meth:`tolist` now supports all single character native formats in - :mod:`struct` module syntax as well as multi-dimensional - representations. - - .. method:: toreadonly() - - Return a readonly version of the memoryview object. The original - memoryview object is unchanged. :: - - >>> m = memoryview(bytearray(b'abc')) - >>> mm = m.toreadonly() - >>> mm.tolist() - [89, 98, 99] - >>> mm[0] = 42 - Traceback (most recent call last): - File "", line 1, in - TypeError: cannot modify read-only memory - >>> m[0] = 43 - >>> mm.tolist() - [43, 98, 99] - - .. versionadded:: 3.8 - - .. method:: release() - - Release the underlying buffer exposed by the memoryview object. Many - objects take special actions when a view is held on them (for example, - a :class:`bytearray` would temporarily forbid resizing); therefore, - calling release() is handy to remove these restrictions (and free any - dangling resources) as soon as possible. - - After this method has been called, any further operation on the view - raises a :class:`ValueError` (except :meth:`release()` itself which can - be called multiple times):: - - >>> m = memoryview(b'abc') - >>> m.release() - >>> m[0] - Traceback (most recent call last): - File "", line 1, in - ValueError: operation forbidden on released memoryview object - - The context management protocol can be used for a similar effect, - using the ``with`` statement:: - - >>> with memoryview(b'abc') as m: - ... m[0] - ... - 97 - >>> m[0] - Traceback (most recent call last): - File "", line 1, in - ValueError: operation forbidden on released memoryview object - - .. versionadded:: 3.2 - - .. method:: cast(format[, shape]) - - Cast a memoryview to a new format or shape. *shape* defaults to - ``[byte_length//new_itemsize]``, which means that the result view - will be one-dimensional. The return value is a new memoryview, but - the buffer itself is not copied. Supported casts are 1D -> C-:term:`contiguous` - and C-contiguous -> 1D. - - The destination format is restricted to a single element native format in - :mod:`struct` syntax. One of the formats must be a byte format - ('B', 'b' or 'c'). The byte length of the result must be the same - as the original length. - - Cast 1D/long to 1D/unsigned bytes:: - - >>> import array - >>> a = array.array('l', [1,2,3]) - >>> x = memoryview(a) - >>> x.format - 'l' - >>> x.itemsize - 8 - >>> len(x) - 3 - >>> x.nbytes - 24 - >>> y = x.cast('B') - >>> y.format - 'B' - >>> y.itemsize - 1 - >>> len(y) - 24 - >>> y.nbytes - 24 - - Cast 1D/unsigned bytes to 1D/char:: - - >>> b = bytearray(b'zyz') - >>> x = memoryview(b) - >>> x[0] = b'a' - Traceback (most recent call last): - File "", line 1, in - ValueError: memoryview: invalid value for format "B" - >>> y = x.cast('c') - >>> y[0] = b'a' - >>> b - bytearray(b'ayz') - - Cast 1D/bytes to 3D/ints to 1D/signed char:: - - >>> import struct - >>> buf = struct.pack("i"*12, *list(range(12))) - >>> x = memoryview(buf) - >>> y = x.cast('i', shape=[2,2,3]) - >>> y.tolist() - [[[0, 1, 2], [3, 4, 5]], [[6, 7, 8], [9, 10, 11]]] - >>> y.format - 'i' - >>> y.itemsize - 4 - >>> len(y) - 2 - >>> y.nbytes - 48 - >>> z = y.cast('b') - >>> z.format - 'b' - >>> z.itemsize - 1 - >>> len(z) - 48 - >>> z.nbytes - 48 - - Cast 1D/unsigned long to 2D/unsigned long:: - - >>> buf = struct.pack("L"*6, *list(range(6))) - >>> x = memoryview(buf) - >>> y = x.cast('L', shape=[2,3]) - >>> len(y) - 2 - >>> y.nbytes - 48 - >>> y.tolist() - [[0, 1, 2], [3, 4, 5]] - - .. versionadded:: 3.3 - - .. versionchanged:: 3.5 - The source format is no longer restricted when casting to a byte view. - - There are also several readonly attributes available: - - .. attribute:: obj - - The underlying object of the memoryview:: - - >>> b = bytearray(b'xyz') - >>> m = memoryview(b) - >>> m.obj is b - True - - .. versionadded:: 3.3 - - .. attribute:: nbytes - - ``nbytes == product(shape) * itemsize == len(m.tobytes())``. This is - the amount of space in bytes that the array would use in a contiguous - representation. It is not necessarily equal to ``len(m)``:: - - >>> import array - >>> a = array.array('i', [1,2,3,4,5]) - >>> m = memoryview(a) - >>> len(m) - 5 - >>> m.nbytes - 20 - >>> y = m[::2] - >>> len(y) - 3 - >>> y.nbytes - 12 - >>> len(y.tobytes()) - 12 - - Multi-dimensional arrays:: - - >>> import struct - >>> buf = struct.pack("d"*12, *[1.5*x for x in range(12)]) - >>> x = memoryview(buf) - >>> y = x.cast('d', shape=[3,4]) - >>> y.tolist() - [[0.0, 1.5, 3.0, 4.5], [6.0, 7.5, 9.0, 10.5], [12.0, 13.5, 15.0, 16.5]] - >>> len(y) - 3 - >>> y.nbytes - 96 - - .. versionadded:: 3.3 - - .. attribute:: readonly - - A bool indicating whether the memory is read only. - - .. attribute:: format - - A string containing the format (in :mod:`struct` module style) for each - element in the view. A memoryview can be created from exporters with - arbitrary format strings, but some methods (e.g. :meth:`tolist`) are - restricted to native single element formats. - - .. versionchanged:: 3.3 - format ``'B'`` is now handled according to the struct module syntax. - This means that ``memoryview(b'abc')[0] == b'abc'[0] == 97``. - - .. attribute:: itemsize - - The size in bytes of each element of the memoryview:: - - >>> import array, struct - >>> m = memoryview(array.array('H', [32000, 32001, 32002])) - >>> m.itemsize - 2 - >>> m[0] - 32000 - >>> struct.calcsize('H') == m.itemsize - True - - .. attribute:: ndim - - An integer indicating how many dimensions of a multi-dimensional array the - memory represents. - - .. attribute:: shape - - A tuple of integers the length of :attr:`ndim` giving the shape of the - memory as an N-dimensional array. - - .. versionchanged:: 3.3 - An empty tuple instead of ``None`` when ndim = 0. - - .. attribute:: strides - - A tuple of integers the length of :attr:`ndim` giving the size in bytes to - access each element for each dimension of the array. - - .. versionchanged:: 3.3 - An empty tuple instead of ``None`` when ndim = 0. - - .. attribute:: suboffsets - - Used internally for PIL-style arrays. The value is informational only. - - .. attribute:: c_contiguous - - A bool indicating whether the memory is C-:term:`contiguous`. - - .. versionadded:: 3.3 - - .. attribute:: f_contiguous - - A bool indicating whether the memory is Fortran :term:`contiguous`. - - .. versionadded:: 3.3 - - .. attribute:: contiguous - - A bool indicating whether the memory is :term:`contiguous`. - - .. versionadded:: 3.3 - - -.. _types-set: - -Set Types --- :class:`set`, :class:`frozenset` -============================================== - -.. index:: object: set - -A :dfn:`set` object is an unordered collection of distinct :term:`hashable` objects. -Common uses include membership testing, removing duplicates from a sequence, and -computing mathematical operations such as intersection, union, difference, and -symmetric difference. -(For other containers see the built-in :class:`dict`, :class:`list`, -and :class:`tuple` classes, and the :mod:`collections` module.) - -Like other collections, sets support ``x in set``, ``len(set)``, and ``for x in -set``. Being an unordered collection, sets do not record element position or -order of insertion. Accordingly, sets do not support indexing, slicing, or -other sequence-like behavior. - -There are currently two built-in set types, :class:`set` and :class:`frozenset`. -The :class:`set` type is mutable --- the contents can be changed using methods -like :meth:`~set.add` and :meth:`~set.remove`. Since it is mutable, it has no -hash value and cannot be used as either a dictionary key or as an element of -another set. The :class:`frozenset` type is immutable and :term:`hashable` --- -its contents cannot be altered after it is created; it can therefore be used as -a dictionary key or as an element of another set. - -Non-empty sets (not frozensets) can be created by placing a comma-separated list -of elements within braces, for example: ``{'jack', 'sjoerd'}``, in addition to the -:class:`set` constructor. - -The constructors for both classes work the same: - -.. class:: set([iterable]) - frozenset([iterable]) - - Return a new set or frozenset object whose elements are taken from - *iterable*. The elements of a set must be :term:`hashable`. To - represent sets of sets, the inner sets must be :class:`frozenset` - objects. If *iterable* is not specified, a new empty set is - returned. - - Instances of :class:`set` and :class:`frozenset` provide the following - operations: - - .. describe:: len(s) - - Return the number of elements in set *s* (cardinality of *s*). - - .. describe:: x in s - - Test *x* for membership in *s*. - - .. describe:: x not in s - - Test *x* for non-membership in *s*. - - .. method:: isdisjoint(other) - - Return ``True`` if the set has no elements in common with *other*. Sets are - disjoint if and only if their intersection is the empty set. - - .. method:: issubset(other) - set <= other - - Test whether every element in the set is in *other*. - - .. method:: set < other - - Test whether the set is a proper subset of *other*, that is, - ``set <= other and set != other``. - - .. method:: issuperset(other) - set >= other - - Test whether every element in *other* is in the set. - - .. method:: set > other - - Test whether the set is a proper superset of *other*, that is, ``set >= - other and set != other``. - - .. method:: union(*others) - set | other | ... - - Return a new set with elements from the set and all others. - - .. method:: intersection(*others) - set & other & ... - - Return a new set with elements common to the set and all others. - - .. method:: difference(*others) - set - other - ... - - Return a new set with elements in the set that are not in the others. - - .. method:: symmetric_difference(other) - set ^ other - - Return a new set with elements in either the set or *other* but not both. - - .. method:: copy() - - Return a shallow copy of the set. - - - Note, the non-operator versions of :meth:`union`, :meth:`intersection`, - :meth:`difference`, and :meth:`symmetric_difference`, :meth:`issubset`, and - :meth:`issuperset` methods will accept any iterable as an argument. In - contrast, their operator based counterparts require their arguments to be - sets. This precludes error-prone constructions like ``set('abc') & 'cbs'`` - in favor of the more readable ``set('abc').intersection('cbs')``. - - Both :class:`set` and :class:`frozenset` support set to set comparisons. Two - sets are equal if and only if every element of each set is contained in the - other (each is a subset of the other). A set is less than another set if and - only if the first set is a proper subset of the second set (is a subset, but - is not equal). A set is greater than another set if and only if the first set - is a proper superset of the second set (is a superset, but is not equal). - - Instances of :class:`set` are compared to instances of :class:`frozenset` - based on their members. For example, ``set('abc') == frozenset('abc')`` - returns ``True`` and so does ``set('abc') in set([frozenset('abc')])``. - - The subset and equality comparisons do not generalize to a total ordering - function. For example, any two nonempty disjoint sets are not equal and are not - subsets of each other, so *all* of the following return ``False``: ``ab``. - - Since sets only define partial ordering (subset relationships), the output of - the :meth:`list.sort` method is undefined for lists of sets. - - Set elements, like dictionary keys, must be :term:`hashable`. - - Binary operations that mix :class:`set` instances with :class:`frozenset` - return the type of the first operand. For example: ``frozenset('ab') | - set('bc')`` returns an instance of :class:`frozenset`. - - The following table lists operations available for :class:`set` that do not - apply to immutable instances of :class:`frozenset`: - - .. method:: update(*others) - set |= other | ... - - Update the set, adding elements from all others. - - .. method:: intersection_update(*others) - set &= other & ... - - Update the set, keeping only elements found in it and all others. - - .. method:: difference_update(*others) - set -= other | ... - - Update the set, removing elements found in others. - - .. method:: symmetric_difference_update(other) - set ^= other - - Update the set, keeping only elements found in either set, but not in both. - - .. method:: add(elem) - - Add element *elem* to the set. - - .. method:: remove(elem) - - Remove element *elem* from the set. Raises :exc:`KeyError` if *elem* is - not contained in the set. - - .. method:: discard(elem) - - Remove element *elem* from the set if it is present. - - .. method:: pop() - - Remove and return an arbitrary element from the set. Raises - :exc:`KeyError` if the set is empty. - - .. method:: clear() - - Remove all elements from the set. - - - Note, the non-operator versions of the :meth:`update`, - :meth:`intersection_update`, :meth:`difference_update`, and - :meth:`symmetric_difference_update` methods will accept any iterable as an - argument. - - Note, the *elem* argument to the :meth:`__contains__`, :meth:`remove`, and - :meth:`discard` methods may be a set. To support searching for an equivalent - frozenset, a temporary one is created from *elem*. - - -.. _typesmapping: - -Mapping Types --- :class:`dict` -=============================== - -.. index:: - object: mapping - object: dictionary - triple: operations on; mapping; types - triple: operations on; dictionary; type - statement: del - builtin: len - -A :term:`mapping` object maps :term:`hashable` values to arbitrary objects. -Mappings are mutable objects. There is currently only one standard mapping -type, the :dfn:`dictionary`. (For other containers see the built-in -:class:`list`, :class:`set`, and :class:`tuple` classes, and the -:mod:`collections` module.) - -A dictionary's keys are *almost* arbitrary values. Values that are not -:term:`hashable`, that is, values containing lists, dictionaries or other -mutable types (that are compared by value rather than by object identity) may -not be used as keys. Numeric types used for keys obey the normal rules for -numeric comparison: if two numbers compare equal (such as ``1`` and ``1.0``) -then they can be used interchangeably to index the same dictionary entry. (Note -however, that since computers store floating-point numbers as approximations it -is usually unwise to use them as dictionary keys.) - -Dictionaries can be created by placing a comma-separated list of ``key: value`` -pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: -'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. - -.. class:: dict(**kwarg) - dict(mapping, **kwarg) - dict(iterable, **kwarg) - - Return a new dictionary initialized from an optional positional argument - and a possibly empty set of keyword arguments. - - If no positional argument is given, an empty dictionary is created. - If a positional argument is given and it is a mapping object, a dictionary - is created with the same key-value pairs as the mapping object. Otherwise, - the positional argument must be an :term:`iterable` object. Each item in - the iterable must itself be an iterable with exactly two objects. The - first object of each item becomes a key in the new dictionary, and the - second object the corresponding value. If a key occurs more than once, the - last value for that key becomes the corresponding value in the new - dictionary. - - If keyword arguments are given, the keyword arguments and their values are - added to the dictionary created from the positional argument. If a key - being added is already present, the value from the keyword argument - replaces the value from the positional argument. - - To illustrate, the following examples all return a dictionary equal to - ``{"one": 1, "two": 2, "three": 3}``:: - - >>> a = dict(one=1, two=2, three=3) - >>> b = {'one': 1, 'two': 2, 'three': 3} - >>> c = dict(zip(['one', 'two', 'three'], [1, 2, 3])) - >>> d = dict([('two', 2), ('one', 1), ('three', 3)]) - >>> e = dict({'three': 3, 'one': 1, 'two': 2}) - >>> f = dict({'one': 1, 'three': 3}, two=2) - >>> a == b == c == d == e == f - True - - Providing keyword arguments as in the first example only works for keys that - are valid Python identifiers. Otherwise, any valid keys can be used. - - - These are the operations that dictionaries support (and therefore, custom - mapping types should support too): - - .. describe:: list(d) - - Return a list of all the keys used in the dictionary *d*. - - .. describe:: len(d) - - Return the number of items in the dictionary *d*. - - .. describe:: d[key] - - Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is - not in the map. - - .. index:: __missing__() - - If a subclass of dict defines a method :meth:`__missing__` and *key* - is not present, the ``d[key]`` operation calls that method with the key *key* - as argument. The ``d[key]`` operation then returns or raises whatever is - returned or raised by the ``__missing__(key)`` call. - No other operations or methods invoke :meth:`__missing__`. If - :meth:`__missing__` is not defined, :exc:`KeyError` is raised. - :meth:`__missing__` must be a method; it cannot be an instance variable:: - - >>> class Counter(dict): - ... def __missing__(self, key): - ... return 0 - >>> c = Counter() - >>> c['red'] - 0 - >>> c['red'] += 1 - >>> c['red'] - 1 - - The example above shows part of the implementation of - :class:`collections.Counter`. A different ``__missing__`` method is used - by :class:`collections.defaultdict`. - - .. describe:: d[key] = value - - Set ``d[key]`` to *value*. - - .. describe:: del d[key] - - Remove ``d[key]`` from *d*. Raises a :exc:`KeyError` if *key* is not in the - map. - - .. describe:: key in d - - Return ``True`` if *d* has a key *key*, else ``False``. - - .. describe:: key not in d - - Equivalent to ``not key in d``. - - .. describe:: iter(d) - - Return an iterator over the keys of the dictionary. This is a shortcut - for ``iter(d.keys())``. - - .. method:: clear() - - Remove all items from the dictionary. - - .. method:: copy() - - Return a shallow copy of the dictionary. - - .. classmethod:: fromkeys(iterable[, value]) - - Create a new dictionary with keys from *iterable* and values set to *value*. - - :meth:`fromkeys` is a class method that returns a new dictionary. *value* - defaults to ``None``. All of the values refer to just a single instance, - so it generally doesn't make sense for *value* to be a mutable object - such as an empty list. To get distinct values, use a :ref:`dict - comprehension ` instead. - - .. method:: get(key[, default]) - - Return the value for *key* if *key* is in the dictionary, else *default*. - If *default* is not given, it defaults to ``None``, so that this method - never raises a :exc:`KeyError`. - - .. method:: items() - - Return a new view of the dictionary's items (``(key, value)`` pairs). - See the :ref:`documentation of view objects `. - - .. method:: keys() - - Return a new view of the dictionary's keys. See the :ref:`documentation - of view objects `. - - .. method:: pop(key[, default]) - - If *key* is in the dictionary, remove it and return its value, else return - *default*. If *default* is not given and *key* is not in the dictionary, - a :exc:`KeyError` is raised. - - .. method:: popitem() - - Remove and return a ``(key, value)`` pair from the dictionary. - Pairs are returned in :abbr:`LIFO (last-in, first-out)` order. - - :meth:`popitem` is useful to destructively iterate over a dictionary, as - often used in set algorithms. If the dictionary is empty, calling - :meth:`popitem` raises a :exc:`KeyError`. - - .. versionchanged:: 3.7 - LIFO order is now guaranteed. In prior versions, :meth:`popitem` would - return an arbitrary key/value pair. - - .. describe:: reversed(d) - - Return a reverse iterator over the keys of the dictionary. This is a - shortcut for ``reversed(d.keys())``. - - .. versionadded:: 3.8 - - .. method:: setdefault(key[, default]) - - If *key* is in the dictionary, return its value. If not, insert *key* - with a value of *default* and return *default*. *default* defaults to - ``None``. - - .. method:: update([other]) - - Update the dictionary with the key/value pairs from *other*, overwriting - existing keys. Return ``None``. - - :meth:`update` accepts either another dictionary object or an iterable of - key/value pairs (as tuples or other iterables of length two). If keyword - arguments are specified, the dictionary is then updated with those - key/value pairs: ``d.update(red=1, blue=2)``. - - .. method:: values() - - Return a new view of the dictionary's values. See the - :ref:`documentation of view objects `. - - An equality comparison between one ``dict.values()`` view and another - will always return ``False``. This also applies when comparing - ``dict.values()`` to itself:: - - >>> d = {'a': 1} - >>> d.values() == d.values() - False - - Dictionaries compare equal if and only if they have the same ``(key, - value)`` pairs (regardless of ordering). Order comparisons ('<', '<=', '>=', '>') raise - :exc:`TypeError`. - - Dictionaries preserve insertion order. Note that updating a key does not - affect the order. Keys added after deletion are inserted at the end. :: - - >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} - >>> d - {'one': 1, 'two': 2, 'three': 3, 'four': 4} - >>> list(d) - ['one', 'two', 'three', 'four'] - >>> list(d.values()) - [1, 2, 3, 4] - >>> d["one"] = 42 - >>> d - {'one': 42, 'two': 2, 'three': 3, 'four': 4} - >>> del d["two"] - >>> d["two"] = None - >>> d - {'one': 42, 'three': 3, 'four': 4, 'two': None} - - .. versionchanged:: 3.7 - Dictionary order is guaranteed to be insertion order. This behavior was - an implementation detail of CPython from 3.6. - - Dictionaries and dictionary views are reversible. :: - - >>> d = {"one": 1, "two": 2, "three": 3, "four": 4} - >>> d - {'one': 1, 'two': 2, 'three': 3, 'four': 4} - >>> list(reversed(d)) - ['four', 'three', 'two', 'one'] - >>> list(reversed(d.values())) - [4, 3, 2, 1] - >>> list(reversed(d.items())) - [('four', 4), ('three', 3), ('two', 2), ('one', 1)] - - .. versionchanged:: 3.8 - Dictionaries are now reversible. - - -.. seealso:: - :class:`types.MappingProxyType` can be used to create a read-only view - of a :class:`dict`. - - -.. _dict-views: - -Dictionary view objects ------------------------ - -The objects returned by :meth:`dict.keys`, :meth:`dict.values` and -:meth:`dict.items` are *view objects*. They provide a dynamic view on the -dictionary's entries, which means that when the dictionary changes, the view -reflects these changes. - -Dictionary views can be iterated over to yield their respective data, and -support membership tests: - -.. describe:: len(dictview) - - Return the number of entries in the dictionary. - -.. describe:: iter(dictview) - - Return an iterator over the keys, values or items (represented as tuples of - ``(key, value)``) in the dictionary. - - Keys and values are iterated over in insertion order. - This allows the creation of ``(value, key)`` pairs - using :func:`zip`: ``pairs = zip(d.values(), d.keys())``. Another way to - create the same list is ``pairs = [(v, k) for (k, v) in d.items()]``. - - Iterating views while adding or deleting entries in the dictionary may raise - a :exc:`RuntimeError` or fail to iterate over all entries. - - .. versionchanged:: 3.7 - Dictionary order is guaranteed to be insertion order. - -.. describe:: x in dictview - - Return ``True`` if *x* is in the underlying dictionary's keys, values or - items (in the latter case, *x* should be a ``(key, value)`` tuple). - -.. describe:: reversed(dictview) - - Return a reverse iterator over the keys, values or items of the dictionary. - The view will be iterated in reverse order of the insertion. - - .. versionchanged:: 3.8 - Dictionary views are now reversible. - - -Keys views are set-like since their entries are unique and hashable. If all -values are hashable, so that ``(key, value)`` pairs are unique and hashable, -then the items view is also set-like. (Values views are not treated as set-like -since the entries are generally not unique.) For set-like views, all of the -operations defined for the abstract base class :class:`collections.abc.Set` are -available (for example, ``==``, ``<``, or ``^``). - -An example of dictionary view usage:: - - >>> dishes = {'eggs': 2, 'sausage': 1, 'bacon': 1, 'spam': 500} - >>> keys = dishes.keys() - >>> values = dishes.values() - - >>> # iteration - >>> n = 0 - >>> for val in values: - ... n += val - >>> print(n) - 504 - - >>> # keys and values are iterated over in the same order (insertion order) - >>> list(keys) - ['eggs', 'sausage', 'bacon', 'spam'] - >>> list(values) - [2, 1, 1, 500] - - >>> # view objects are dynamic and reflect dict changes - >>> del dishes['eggs'] - >>> del dishes['sausage'] - >>> list(keys) - ['bacon', 'spam'] - - >>> # set operations - >>> keys & {'eggs', 'bacon', 'salad'} - {'bacon'} - >>> keys ^ {'sausage', 'juice'} - {'juice', 'sausage', 'bacon', 'spam'} - - -.. _typecontextmanager: - -Context Manager Types -===================== - -.. index:: - single: context manager - single: context management protocol - single: protocol; context management - -Python's :keyword:`with` statement supports the concept of a runtime context -defined by a context manager. This is implemented using a pair of methods -that allow user-defined classes to define a runtime context that is entered -before the statement body is executed and exited when the statement ends: - - -.. method:: contextmanager.__enter__() - - Enter the runtime context and return either this object or another object - related to the runtime context. The value returned by this method is bound to - the identifier in the :keyword:`!as` clause of :keyword:`with` statements using - this context manager. - - An example of a context manager that returns itself is a :term:`file object`. - File objects return themselves from __enter__() to allow :func:`open` to be - used as the context expression in a :keyword:`with` statement. - - An example of a context manager that returns a related object is the one - returned by :func:`decimal.localcontext`. These managers set the active - decimal context to a copy of the original decimal context and then return the - copy. This allows changes to be made to the current decimal context in the body - of the :keyword:`with` statement without affecting code outside the - :keyword:`!with` statement. - - -.. method:: contextmanager.__exit__(exc_type, exc_val, exc_tb) - - Exit the runtime context and return a Boolean flag indicating if any exception - that occurred should be suppressed. If an exception occurred while executing the - body of the :keyword:`with` statement, the arguments contain the exception type, - value and traceback information. Otherwise, all three arguments are ``None``. - - Returning a true value from this method will cause the :keyword:`with` statement - to suppress the exception and continue execution with the statement immediately - following the :keyword:`!with` statement. Otherwise the exception continues - propagating after this method has finished executing. Exceptions that occur - during execution of this method will replace any exception that occurred in the - body of the :keyword:`!with` statement. - - The exception passed in should never be reraised explicitly - instead, this - method should return a false value to indicate that the method completed - successfully and does not want to suppress the raised exception. This allows - context management code to easily detect whether or not an :meth:`__exit__` - method has actually failed. - -Python defines several context managers to support easy thread synchronisation, -prompt closure of files or other objects, and simpler manipulation of the active -decimal arithmetic context. The specific types are not treated specially beyond -their implementation of the context management protocol. See the -:mod:`contextlib` module for some examples. - -Python's :term:`generator`\s and the :class:`contextlib.contextmanager` decorator -provide a convenient way to implement these protocols. If a generator function is -decorated with the :class:`contextlib.contextmanager` decorator, it will return a -context manager implementing the necessary :meth:`__enter__` and -:meth:`__exit__` methods, rather than the iterator produced by an undecorated -generator function. - -Note that there is no specific slot for any of these methods in the type -structure for Python objects in the Python/C API. Extension types wanting to -define these methods must provide them as a normal Python accessible method. -Compared to the overhead of setting up the runtime context, the overhead of a -single class dictionary lookup is negligible. - - -.. _typesother: - -Other Built-in Types -==================== - -The interpreter supports several other kinds of objects. Most of these support -only one or two operations. - - -.. _typesmodules: - -Modules -------- - -The only special operation on a module is attribute access: ``m.name``, where -*m* is a module and *name* accesses a name defined in *m*'s symbol table. -Module attributes can be assigned to. (Note that the :keyword:`import` -statement is not, strictly speaking, an operation on a module object; ``import -foo`` does not require a module object named *foo* to exist, rather it requires -an (external) *definition* for a module named *foo* somewhere.) - -A special attribute of every module is :attr:`~object.__dict__`. This is the -dictionary containing the module's symbol table. Modifying this dictionary will -actually change the module's symbol table, but direct assignment to the -:attr:`~object.__dict__` attribute is not possible (you can write -``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write -``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is -not recommended. - -Modules built into the interpreter are written like this: ````. If loaded from a file, they are written as ````. - - -.. _typesobjects: - -Classes and Class Instances ---------------------------- - -See :ref:`objects` and :ref:`class` for these. - - -.. _typesfunctions: - -Functions ---------- - -Function objects are created by function definitions. The only operation on a -function object is to call it: ``func(argument-list)``. - -There are really two flavors of function objects: built-in functions and -user-defined functions. Both support the same operation (to call the function), -but the implementation is different, hence the different object types. - -See :ref:`function` for more information. - - -.. _typesmethods: - -Methods -------- - -.. index:: object: method - -Methods are functions that are called using the attribute notation. There are -two flavors: built-in methods (such as :meth:`append` on lists) and class -instance methods. Built-in methods are described with the types that support -them. - -If you access a method (a function defined in a class namespace) through an -instance, you get a special object: a :dfn:`bound method` (also called -:dfn:`instance method`) object. When called, it will add the ``self`` argument -to the argument list. Bound methods have two special read-only attributes: -``m.__self__`` is the object on which the method operates, and ``m.__func__`` is -the function implementing the method. Calling ``m(arg-1, arg-2, ..., arg-n)`` -is completely equivalent to calling ``m.__func__(m.__self__, arg-1, arg-2, ..., -arg-n)``. - -Like function objects, bound method objects support getting arbitrary -attributes. However, since method attributes are actually stored on the -underlying function object (``meth.__func__``), setting method attributes on -bound methods is disallowed. Attempting to set an attribute on a method -results in an :exc:`AttributeError` being raised. In order to set a method -attribute, you need to explicitly set it on the underlying function object:: - - >>> class C: - ... def method(self): - ... pass - ... - >>> c = C() - >>> c.method.whoami = 'my name is method' # can't set on the method - Traceback (most recent call last): - File "", line 1, in - AttributeError: 'method' object has no attribute 'whoami' - >>> c.method.__func__.whoami = 'my name is method' - >>> c.method.whoami - 'my name is method' - -See :ref:`types` for more information. - - -.. index:: object; code, code object - -.. _bltin-code-objects: - -Code Objects ------------- - -.. index:: - builtin: compile - single: __code__ (function object attribute) - -Code objects are used by the implementation to represent "pseudo-compiled" -executable Python code such as a function body. They differ from function -objects because they don't contain a reference to their global execution -environment. Code objects are returned by the built-in :func:`compile` function -and can be extracted from function objects through their :attr:`__code__` -attribute. See also the :mod:`code` module. - -.. index:: - builtin: exec - builtin: eval - -A code object can be executed or evaluated by passing it (instead of a source -string) to the :func:`exec` or :func:`eval` built-in functions. - -See :ref:`types` for more information. - - -.. _bltin-type-objects: - -Type Objects ------------- - -.. index:: - builtin: type - module: types - -Type objects represent the various object types. An object's type is accessed -by the built-in function :func:`type`. There are no special operations on -types. The standard module :mod:`types` defines names for all standard built-in -types. - -Types are written like this: ````. - - -.. _bltin-null-object: - -The Null Object ---------------- - -This object is returned by functions that don't explicitly return a value. It -supports no special operations. There is exactly one null object, named -``None`` (a built-in name). ``type(None)()`` produces the same singleton. - -It is written as ``None``. - - -.. index:: single: ...; ellipsis literal -.. _bltin-ellipsis-object: - -The Ellipsis Object -------------------- - -This object is commonly used by slicing (see :ref:`slicings`). It supports no -special operations. There is exactly one ellipsis object, named -:const:`Ellipsis` (a built-in name). ``type(Ellipsis)()`` produces the -:const:`Ellipsis` singleton. - -It is written as ``Ellipsis`` or ``...``. - - -.. _bltin-notimplemented-object: - -The NotImplemented Object -------------------------- - -This object is returned from comparisons and binary operations when they are -asked to operate on types they don't support. See :ref:`comparisons` for more -information. There is exactly one ``NotImplemented`` object. -``type(NotImplemented)()`` produces the singleton instance. - -It is written as ``NotImplemented``. - - -.. _bltin-boolean-values: - -Boolean Values --------------- - -Boolean values are the two constant objects ``False`` and ``True``. They are -used to represent truth values (although other values can also be considered -false or true). In numeric contexts (for example when used as the argument to -an arithmetic operator), they behave like the integers 0 and 1, respectively. -The built-in function :func:`bool` can be used to convert any value to a -Boolean, if the value can be interpreted as a truth value (see section -:ref:`truth` above). - -.. index:: - single: False - single: True - pair: Boolean; values - -They are written as ``False`` and ``True``, respectively. - - -.. _typesinternal: - -Internal Objects ----------------- - -See :ref:`types` for this information. It describes stack frame objects, -traceback objects, and slice objects. - - -.. _specialattrs: - -Special Attributes -================== - -The implementation adds a few special read-only attributes to several object -types, where they are relevant. Some of these are not reported by the -:func:`dir` built-in function. - - -.. attribute:: object.__dict__ - - A dictionary or other mapping object used to store an object's (writable) - attributes. - - -.. attribute:: instance.__class__ - - The class to which a class instance belongs. - - -.. attribute:: class.__bases__ - - The tuple of base classes of a class object. - - -.. attribute:: definition.__name__ - - The name of the class, function, method, descriptor, or - generator instance. - - -.. attribute:: definition.__qualname__ - - The :term:`qualified name` of the class, function, method, descriptor, - or generator instance. - - .. versionadded:: 3.3 - - -.. attribute:: class.__mro__ - - This attribute is a tuple of classes that are considered when looking for - base classes during method resolution. - - -.. method:: class.mro() - - This method can be overridden by a metaclass to customize the method - resolution order for its instances. It is called at class instantiation, and - its result is stored in :attr:`~class.__mro__`. - - -.. method:: class.__subclasses__ - - Each class keeps a list of weak references to its immediate subclasses. This - method returns a list of all those references still alive. - Example:: - - >>> int.__subclasses__() - [] - - -.. rubric:: Footnotes - -.. [1] Additional information on these special methods may be found in the Python - Reference Manual (:ref:`customization`). - -.. [2] As a consequence, the list ``[1, 2]`` is considered equal to ``[1.0, 2.0]``, and - similarly for tuples. - -.. [3] They must have since the parser can't tell the type of the operands. - -.. [4] Cased characters are those with general category property being one of - "Lu" (Letter, uppercase), "Ll" (Letter, lowercase), or "Lt" (Letter, titlecase). - -.. [5] To format only a tuple you should therefore provide a singleton tuple whose only - element is the tuple to be formatted. diff --git a/Doc/library/sys.rst.bak b/Doc/library/sys.rst.bak deleted file mode 100644 index d28b3565c1c633..00000000000000 --- a/Doc/library/sys.rst.bak +++ /dev/null @@ -1,1652 +0,0 @@ -:mod:`sys` --- System-specific parameters and functions -======================================================= - -.. module:: sys - :synopsis: Access system-specific parameters and functions. - --------------- - -This module provides access to some variables used or maintained by the -interpreter and to functions that interact strongly with the interpreter. It is -always available. - - -.. data:: abiflags - - On POSIX systems where Python was built with the standard ``configure`` - script, this contains the ABI flags as specified by :pep:`3149`. - - .. versionchanged:: 3.8 - Default flags became an empty string (``m`` flag for pymalloc has been - removed). - - .. versionadded:: 3.2 - - -.. function:: addaudithook(hook) - - Append the callable *hook* to the list of active auditing hooks for the - current interpreter. - - When an auditing event is raised through the :func:`sys.audit` function, each - hook will be called in the order it was added with the event name and the - tuple of arguments. Native hooks added by :c:func:`PySys_AddAuditHook` are - called first, followed by hooks added in the current interpreter. - - .. audit-event:: sys.addaudithook "" sys.addaudithook - - Raise an auditing event ``sys.addaudithook`` with no arguments. If any - existing hooks raise an exception derived from :class:`RuntimeError`, the - new hook will not be added and the exception suppressed. As a result, - callers cannot assume that their hook has been added unless they control - all existing hooks. - - .. versionadded:: 3.8 - - .. versionchanged:: 3.8.1 - - Exceptions derived from :class:`Exception` but not :class:`RuntimeError` - are no longer suppressed. - - .. impl-detail:: - - When tracing is enabled (see :func:`settrace`), Python hooks are only - traced if the callable has a ``__cantrace__`` member that is set to a - true value. Otherwise, trace functions will skip the hook. - - -.. data:: argv - - The list of command line arguments passed to a Python script. ``argv[0]`` is the - script name (it is operating system dependent whether this is a full pathname or - not). If the command was executed using the :option:`-c` command line option to - the interpreter, ``argv[0]`` is set to the string ``'-c'``. If no script name - was passed to the Python interpreter, ``argv[0]`` is the empty string. - - To loop over the standard input, or the list of files given on the - command line, see the :mod:`fileinput` module. - - .. note:: - On Unix, command line arguments are passed by bytes from OS. Python decodes - them with filesystem encoding and "surrogateescape" error handler. - When you need original bytes, you can get it by - ``[os.fsencode(arg) for arg in sys.argv]``. - - -.. _auditing: - -.. function:: audit(event, *args) - - .. index:: single: auditing - - Raise an auditing event with any active hooks. The event name is a string - identifying the event and its associated schema, which is the number and - types of arguments. The schema for a given event is considered public and - stable API and should not be modified between releases. - - This function will raise the first exception raised by any hook. In general, - these errors should not be handled and should terminate the process as - quickly as possible. - - Hooks are added using the :func:`sys.addaudithook` or - :c:func:`PySys_AddAuditHook` functions. - - The native equivalent of this function is :c:func:`PySys_Audit`. Using the - native function is preferred when possible. - - See the :ref:`audit events table ` for all events raised by - CPython. - - .. versionadded:: 3.8 - - -.. data:: base_exec_prefix - - Set during Python startup, before ``site.py`` is run, to the same value as - :data:`exec_prefix`. If not running in a - :ref:`virtual environment `, the values will stay the same; if - ``site.py`` finds that a virtual environment is in use, the values of - :data:`prefix` and :data:`exec_prefix` will be changed to point to the - virtual environment, whereas :data:`base_prefix` and - :data:`base_exec_prefix` will remain pointing to the base Python - installation (the one which the virtual environment was created from). - - .. versionadded:: 3.3 - - -.. data:: base_prefix - - Set during Python startup, before ``site.py`` is run, to the same value as - :data:`prefix`. If not running in a :ref:`virtual environment `, the values - will stay the same; if ``site.py`` finds that a virtual environment is in - use, the values of :data:`prefix` and :data:`exec_prefix` will be changed to - point to the virtual environment, whereas :data:`base_prefix` and - :data:`base_exec_prefix` will remain pointing to the base Python - installation (the one which the virtual environment was created from). - - .. versionadded:: 3.3 - - -.. data:: byteorder - - An indicator of the native byte order. This will have the value ``'big'`` on - big-endian (most-significant byte first) platforms, and ``'little'`` on - little-endian (least-significant byte first) platforms. - - -.. data:: builtin_module_names - - A tuple of strings giving the names of all modules that are compiled into this - Python interpreter. (This information is not available in any other way --- - ``modules.keys()`` only lists the imported modules.) - - -.. function:: call_tracing(func, args) - - Call ``func(*args)``, while tracing is enabled. The tracing state is saved, - and restored afterwards. This is intended to be called from a debugger from - a checkpoint, to recursively debug some other code. - - -.. data:: copyright - - A string containing the copyright pertaining to the Python interpreter. - - -.. function:: _clear_type_cache() - - Clear the internal type cache. The type cache is used to speed up attribute - and method lookups. Use the function *only* to drop unnecessary references - during reference leak debugging. - - This function should be used for internal and specialized purposes only. - - -.. function:: _current_frames() - - Return a dictionary mapping each thread's identifier to the topmost stack frame - currently active in that thread at the time the function is called. Note that - functions in the :mod:`traceback` module can build the call stack given such a - frame. - - This is most useful for debugging deadlock: this function does not require the - deadlocked threads' cooperation, and such threads' call stacks are frozen for as - long as they remain deadlocked. The frame returned for a non-deadlocked thread - may bear no relationship to that thread's current activity by the time calling - code examines the frame. - - This function should be used for internal and specialized purposes only. - - .. audit-event:: sys._current_frames "" sys._current_frames - - -.. function:: breakpointhook() - - This hook function is called by built-in :func:`breakpoint`. By default, - it drops you into the :mod:`pdb` debugger, but it can be set to any other - function so that you can choose which debugger gets used. - - The signature of this function is dependent on what it calls. For example, - the default binding (e.g. ``pdb.set_trace()``) expects no arguments, but - you might bind it to a function that expects additional arguments - (positional and/or keyword). The built-in ``breakpoint()`` function passes - its ``*args`` and ``**kws`` straight through. Whatever - ``breakpointhooks()`` returns is returned from ``breakpoint()``. - - The default implementation first consults the environment variable - :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function - returns immediately; i.e. it is a no-op. If the environment variable is - not set, or is set to the empty string, ``pdb.set_trace()`` is called. - Otherwise this variable should name a function to run, using Python's - dotted-import nomenclature, e.g. ``package.subpackage.module.function``. - In this case, ``package.subpackage.module`` would be imported and the - resulting module must have a callable named ``function()``. This is run, - passing in ``*args`` and ``**kws``, and whatever ``function()`` returns, - ``sys.breakpointhook()`` returns to the built-in :func:`breakpoint` - function. - - Note that if anything goes wrong while importing the callable named by - :envvar:`PYTHONBREAKPOINT`, a :exc:`RuntimeWarning` is reported and the - breakpoint is ignored. - - Also note that if ``sys.breakpointhook()`` is overridden programmatically, - :envvar:`PYTHONBREAKPOINT` is *not* consulted. - - .. versionadded:: 3.7 - -.. function:: _debugmallocstats() - - Print low-level information to stderr about the state of CPython's memory - allocator. - - If Python is configured --with-pydebug, it also performs some expensive - internal consistency checks. - - .. versionadded:: 3.3 - - .. impl-detail:: - - This function is specific to CPython. The exact output format is not - defined here, and may change. - - -.. data:: dllhandle - - Integer specifying the handle of the Python DLL. - - .. availability:: Windows. - - -.. function:: displayhook(value) - - If *value* is not ``None``, this function prints ``repr(value)`` to - ``sys.stdout``, and saves *value* in ``builtins._``. If ``repr(value)`` is - not encodable to ``sys.stdout.encoding`` with ``sys.stdout.errors`` error - handler (which is probably ``'strict'``), encode it to - ``sys.stdout.encoding`` with ``'backslashreplace'`` error handler. - - ``sys.displayhook`` is called on the result of evaluating an :term:`expression` - entered in an interactive Python session. The display of these values can be - customized by assigning another one-argument function to ``sys.displayhook``. - - Pseudo-code:: - - def displayhook(value): - if value is None: - return - # Set '_' to None to avoid recursion - builtins._ = None - text = repr(value) - try: - sys.stdout.write(text) - except UnicodeEncodeError: - bytes = text.encode(sys.stdout.encoding, 'backslashreplace') - if hasattr(sys.stdout, 'buffer'): - sys.stdout.buffer.write(bytes) - else: - text = bytes.decode(sys.stdout.encoding, 'strict') - sys.stdout.write(text) - sys.stdout.write("\n") - builtins._ = value - - .. versionchanged:: 3.2 - Use ``'backslashreplace'`` error handler on :exc:`UnicodeEncodeError`. - - -.. data:: dont_write_bytecode - - If this is true, Python won't try to write ``.pyc`` files on the - import of source modules. This value is initially set to ``True`` or - ``False`` depending on the :option:`-B` command line option and the - :envvar:`PYTHONDONTWRITEBYTECODE` environment variable, but you can set it - yourself to control bytecode file generation. - - -.. data:: pycache_prefix - - If this is set (not ``None``), Python will write bytecode-cache ``.pyc`` - files to (and read them from) a parallel directory tree rooted at this - directory, rather than from ``__pycache__`` directories in the source code - tree. Any ``__pycache__`` directories in the source code tree will be ignored - and new `.pyc` files written within the pycache prefix. Thus if you use - :mod:`compileall` as a pre-build step, you must ensure you run it with the - same pycache prefix (if any) that you will use at runtime. - - A relative path is interpreted relative to the current working directory. - - This value is initially set based on the value of the :option:`-X` - ``pycache_prefix=PATH`` command-line option or the - :envvar:`PYTHONPYCACHEPREFIX` environment variable (command-line takes - precedence). If neither are set, it is ``None``. - - .. versionadded:: 3.8 - - -.. function:: excepthook(type, value, traceback) - - This function prints out a given traceback and exception to ``sys.stderr``. - - When an exception is raised and uncaught, the interpreter calls - ``sys.excepthook`` with three arguments, the exception class, exception - instance, and a traceback object. In an interactive session this happens just - before control is returned to the prompt; in a Python program this happens just - before the program exits. The handling of such top-level exceptions can be - customized by assigning another three-argument function to ``sys.excepthook``. - - .. audit-event:: sys.excepthook hook,type,value,traceback sys.excepthook - - Raise an auditing event ``sys.excepthook`` with arguments ``hook``, - ``type``, ``value``, ``traceback`` when an uncaught exception occurs. - If no hook has been set, ``hook`` may be ``None``. If any hook raises - an exception derived from :class:`RuntimeError` the call to the hook will - be suppressed. Otherwise, the audit hook exception will be reported as - unraisable and ``sys.excepthook`` will be called. - - .. seealso:: - - The :func:`sys.unraisablehook` function handles unraisable exceptions - and the :func:`threading.excepthook` function handles exception raised - by :func:`threading.Thread.run`. - - -.. data:: __breakpointhook__ - __displayhook__ - __excepthook__ - __unraisablehook__ - - These objects contain the original values of ``breakpointhook``, - ``displayhook``, ``excepthook``, and ``unraisablehook`` at the start of the - program. They are saved so that ``breakpointhook``, ``displayhook`` and - ``excepthook``, ``unraisablehook`` can be restored in case they happen to - get replaced with broken or alternative objects. - - .. versionadded:: 3.7 - __breakpointhook__ - - -.. function:: exc_info() - - This function returns a tuple of three values that give information about the - exception that is currently being handled. The information returned is specific - both to the current thread and to the current stack frame. If the current stack - frame is not handling an exception, the information is taken from the calling - stack frame, or its caller, and so on until a stack frame is found that is - handling an exception. Here, "handling an exception" is defined as "executing - an except clause." For any stack frame, only information about the exception - being currently handled is accessible. - - .. index:: object: traceback - - If no exception is being handled anywhere on the stack, a tuple containing - three ``None`` values is returned. Otherwise, the values returned are - ``(type, value, traceback)``. Their meaning is: *type* gets the type of the - exception being handled (a subclass of :exc:`BaseException`); *value* gets - the exception instance (an instance of the exception type); *traceback* gets - a :ref:`traceback object ` which encapsulates the call - stack at the point where the exception originally occurred. - - -.. data:: exec_prefix - - A string giving the site-specific directory prefix where the platform-dependent - Python files are installed; by default, this is also ``'/usr/local'``. This can - be set at build time with the ``--exec-prefix`` argument to the - :program:`configure` script. Specifically, all configuration files (e.g. the - :file:`pyconfig.h` header file) are installed in the directory - :file:`{exec_prefix}/lib/python{X.Y}/config`, and shared library modules are - installed in :file:`{exec_prefix}/lib/python{X.Y}/lib-dynload`, where *X.Y* - is the version number of Python, for example ``3.2``. - - .. note:: - - If a :ref:`virtual environment ` is in effect, this - value will be changed in ``site.py`` to point to the virtual environment. - The value for the Python installation will still be available, via - :data:`base_exec_prefix`. - - -.. data:: executable - - A string giving the absolute path of the executable binary for the Python - interpreter, on systems where this makes sense. If Python is unable to retrieve - the real path to its executable, :data:`sys.executable` will be an empty string - or ``None``. - - -.. function:: exit([arg]) - - Exit from Python. This is implemented by raising the :exc:`SystemExit` - exception, so cleanup actions specified by finally clauses of :keyword:`try` - statements are honored, and it is possible to intercept the exit attempt at - an outer level. - - The optional argument *arg* can be an integer giving the exit status - (defaulting to zero), or another type of object. If it is an integer, zero - is considered "successful termination" and any nonzero value is considered - "abnormal termination" by shells and the like. Most systems require it to be - in the range 0--127, and produce undefined results otherwise. Some systems - have a convention for assigning specific meanings to specific exit codes, but - these are generally underdeveloped; Unix programs generally use 2 for command - line syntax errors and 1 for all other kind of errors. If another type of - object is passed, ``None`` is equivalent to passing zero, and any other - object is printed to :data:`stderr` and results in an exit code of 1. In - particular, ``sys.exit("some error message")`` is a quick way to exit a - program when an error occurs. - - Since :func:`exit` ultimately "only" raises an exception, it will only exit - the process when called from the main thread, and the exception is not - intercepted. - - .. versionchanged:: 3.6 - If an error occurs in the cleanup after the Python interpreter - has caught :exc:`SystemExit` (such as an error flushing buffered data - in the standard streams), the exit status is changed to 120. - - -.. data:: flags - - The :term:`named tuple` *flags* exposes the status of command line - flags. The attributes are read only. - - ============================= ================================================================ - attribute flag - ============================= ================================================================ - :const:`debug` :option:`-d` - :const:`inspect` :option:`-i` - :const:`interactive` :option:`-i` - :const:`isolated` :option:`-I` - :const:`optimize` :option:`-O` or :option:`-OO` - :const:`dont_write_bytecode` :option:`-B` - :const:`no_user_site` :option:`-s` - :const:`no_site` :option:`-S` - :const:`ignore_environment` :option:`-E` - :const:`verbose` :option:`-v` - :const:`bytes_warning` :option:`-b` - :const:`quiet` :option:`-q` - :const:`hash_randomization` :option:`-R` - :const:`dev_mode` :option:`-X dev <-X>` (:ref:`Python Development Mode `) - :const:`utf8_mode` :option:`-X utf8 <-X>` - ============================= ================================================================ - - .. versionchanged:: 3.2 - Added ``quiet`` attribute for the new :option:`-q` flag. - - .. versionadded:: 3.2.3 - The ``hash_randomization`` attribute. - - .. versionchanged:: 3.3 - Removed obsolete ``division_warning`` attribute. - - .. versionchanged:: 3.4 - Added ``isolated`` attribute for :option:`-I` ``isolated`` flag. - - .. versionchanged:: 3.7 - Added the ``dev_mode`` attribute for the new :ref:`Python Development - Mode ` and the ``utf8_mode`` attribute for the new :option:`-X` - ``utf8`` flag. - - -.. data:: float_info - - A :term:`named tuple` holding information about the float type. It - contains low level information about the precision and internal - representation. The values correspond to the various floating-point - constants defined in the standard header file :file:`float.h` for the 'C' - programming language; see section 5.2.4.2.2 of the 1999 ISO/IEC C standard - [C99]_, 'Characteristics of floating types', for details. - - .. tabularcolumns:: |l|l|L| - - +---------------------+----------------+--------------------------------------------------+ - | attribute | float.h macro | explanation | - +=====================+================+==================================================+ - | :const:`epsilon` | DBL_EPSILON | difference between 1.0 and the least value | - | | | greater than 1.0 that is representable as a float| - | | | | - | | | See also :func:`math.ulp`. | - +---------------------+----------------+--------------------------------------------------+ - | :const:`dig` | DBL_DIG | maximum number of decimal digits that can be | - | | | faithfully represented in a float; see below | - +---------------------+----------------+--------------------------------------------------+ - | :const:`mant_dig` | DBL_MANT_DIG | float precision: the number of base-``radix`` | - | | | digits in the significand of a float | - +---------------------+----------------+--------------------------------------------------+ - | :const:`max` | DBL_MAX | maximum representable positive finite float | - +---------------------+----------------+--------------------------------------------------+ - | :const:`max_exp` | DBL_MAX_EXP | maximum integer *e* such that ``radix**(e-1)`` is| - | | | a representable finite float | - +---------------------+----------------+--------------------------------------------------+ - | :const:`max_10_exp` | DBL_MAX_10_EXP | maximum integer *e* such that ``10**e`` is in the| - | | | range of representable finite floats | - +---------------------+----------------+--------------------------------------------------+ - | :const:`min` | DBL_MIN | minimum representable positive *normalized* float| - | | | | - | | | Use :func:`math.ulp(0.0) ` to get the | - | | | smallest positive *denormalized* representable | - | | | float. | - +---------------------+----------------+--------------------------------------------------+ - | :const:`min_exp` | DBL_MIN_EXP | minimum integer *e* such that ``radix**(e-1)`` is| - | | | a normalized float | - +---------------------+----------------+--------------------------------------------------+ - | :const:`min_10_exp` | DBL_MIN_10_EXP | minimum integer *e* such that ``10**e`` is a | - | | | normalized float | - +---------------------+----------------+--------------------------------------------------+ - | :const:`radix` | FLT_RADIX | radix of exponent representation | - +---------------------+----------------+--------------------------------------------------+ - | :const:`rounds` | FLT_ROUNDS | integer constant representing the rounding mode | - | | | used for arithmetic operations. This reflects | - | | | the value of the system FLT_ROUNDS macro at | - | | | interpreter startup time. See section 5.2.4.2.2 | - | | | of the C99 standard for an explanation of the | - | | | possible values and their meanings. | - +---------------------+----------------+--------------------------------------------------+ - - The attribute :attr:`sys.float_info.dig` needs further explanation. If - ``s`` is any string representing a decimal number with at most - :attr:`sys.float_info.dig` significant digits, then converting ``s`` to a - float and back again will recover a string representing the same decimal - value:: - - >>> import sys - >>> sys.float_info.dig - 15 - >>> s = '3.14159265358979' # decimal string with 15 significant digits - >>> format(float(s), '.15g') # convert to float and back -> same value - '3.14159265358979' - - But for strings with more than :attr:`sys.float_info.dig` significant digits, - this isn't always true:: - - >>> s = '9876543211234567' # 16 significant digits is too many! - >>> format(float(s), '.16g') # conversion changes value - '9876543211234568' - -.. data:: float_repr_style - - A string indicating how the :func:`repr` function behaves for - floats. If the string has value ``'short'`` then for a finite - float ``x``, ``repr(x)`` aims to produce a short string with the - property that ``float(repr(x)) == x``. This is the usual behaviour - in Python 3.1 and later. Otherwise, ``float_repr_style`` has value - ``'legacy'`` and ``repr(x)`` behaves in the same way as it did in - versions of Python prior to 3.1. - - .. versionadded:: 3.1 - - -.. function:: getallocatedblocks() - - Return the number of memory blocks currently allocated by the interpreter, - regardless of their size. This function is mainly useful for tracking - and debugging memory leaks. Because of the interpreter's internal - caches, the result can vary from call to call; you may have to call - :func:`_clear_type_cache()` and :func:`gc.collect()` to get more - predictable results. - - If a Python build or implementation cannot reasonably compute this - information, :func:`getallocatedblocks()` is allowed to return 0 instead. - - .. versionadded:: 3.4 - - -.. function:: getandroidapilevel() - - Return the build time API version of Android as an integer. - - .. availability:: Android. - - .. versionadded:: 3.7 - - -.. function:: getdefaultencoding() - - Return the name of the current default string encoding used by the Unicode - implementation. - - -.. function:: getdlopenflags() - - Return the current value of the flags that are used for - :c:func:`dlopen` calls. Symbolic names for the flag values can be - found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. - :data:`os.RTLD_LAZY`). - - .. availability:: Unix. - - -.. function:: getfilesystemencoding() - - Return the name of the encoding used to convert between Unicode - filenames and bytes filenames. For best compatibility, str should be - used for filenames in all cases, although representing filenames as bytes - is also supported. Functions accepting or returning filenames should support - either str or bytes and internally convert to the system's preferred - representation. - - This encoding is always ASCII-compatible. - - :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that - the correct encoding and errors mode are used. - - * In the UTF-8 mode, the encoding is ``utf-8`` on any platform. - - * On macOS, the encoding is ``'utf-8'``. - - * On Unix, the encoding is the locale encoding. - - * On Windows, the encoding may be ``'utf-8'`` or ``'mbcs'``, depending - on user configuration. - - * On Android, the encoding is ``'utf-8'``. - - * On VxWorks, the encoding is ``'utf-8'``. - - .. versionchanged:: 3.2 - :func:`getfilesystemencoding` result cannot be ``None`` anymore. - - .. versionchanged:: 3.6 - Windows is no longer guaranteed to return ``'mbcs'``. See :pep:`529` - and :func:`_enablelegacywindowsfsencoding` for more information. - - .. versionchanged:: 3.7 - Return 'utf-8' in the UTF-8 mode. - - -.. function:: getfilesystemencodeerrors() - - Return the name of the error mode used to convert between Unicode filenames - and bytes filenames. The encoding name is returned from - :func:`getfilesystemencoding`. - - :func:`os.fsencode` and :func:`os.fsdecode` should be used to ensure that - the correct encoding and errors mode are used. - - .. versionadded:: 3.6 - -.. function:: getrefcount(object) - - Return the reference count of the *object*. The count returned is generally one - higher than you might expect, because it includes the (temporary) reference as - an argument to :func:`getrefcount`. - - -.. function:: getrecursionlimit() - - Return the current value of the recursion limit, the maximum depth of the Python - interpreter stack. This limit prevents infinite recursion from causing an - overflow of the C stack and crashing Python. It can be set by - :func:`setrecursionlimit`. - - -.. function:: getsizeof(object[, default]) - - Return the size of an object in bytes. The object can be any type of - object. All built-in objects will return correct results, but this - does not have to hold true for third-party extensions as it is implementation - specific. - - Only the memory consumption directly attributed to the object is - accounted for, not the memory consumption of objects it refers to. - - If given, *default* will be returned if the object does not provide means to - retrieve the size. Otherwise a :exc:`TypeError` will be raised. - - :func:`getsizeof` calls the object's ``__sizeof__`` method and adds an - additional garbage collector overhead if the object is managed by the garbage - collector. - - See `recursive sizeof recipe `_ - for an example of using :func:`getsizeof` recursively to find the size of - containers and all their contents. - -.. function:: getswitchinterval() - - Return the interpreter's "thread switch interval"; see - :func:`setswitchinterval`. - - .. versionadded:: 3.2 - - -.. function:: _getframe([depth]) - - Return a frame object from the call stack. If optional integer *depth* is - given, return the frame object that many calls below the top of the stack. If - that is deeper than the call stack, :exc:`ValueError` is raised. The default - for *depth* is zero, returning the frame at the top of the call stack. - - .. audit-event:: sys._getframe "" sys._getframe - - .. impl-detail:: - - This function should be used for internal and specialized purposes only. - It is not guaranteed to exist in all implementations of Python. - - -.. function:: getprofile() - - .. index:: - single: profile function - single: profiler - - Get the profiler function as set by :func:`setprofile`. - - -.. function:: gettrace() - - .. index:: - single: trace function - single: debugger - - Get the trace function as set by :func:`settrace`. - - .. impl-detail:: - - The :func:`gettrace` function is intended only for implementing debuggers, - profilers, coverage tools and the like. Its behavior is part of the - implementation platform, rather than part of the language definition, and - thus may not be available in all Python implementations. - - -.. function:: getwindowsversion() - - Return a named tuple describing the Windows version - currently running. The named elements are *major*, *minor*, - *build*, *platform*, *service_pack*, *service_pack_minor*, - *service_pack_major*, *suite_mask*, *product_type* and - *platform_version*. *service_pack* contains a string, - *platform_version* a 3-tuple and all other values are - integers. The components can also be accessed by name, so - ``sys.getwindowsversion()[0]`` is equivalent to - ``sys.getwindowsversion().major``. For compatibility with prior - versions, only the first 5 elements are retrievable by indexing. - - *platform* will be :const:`2 (VER_PLATFORM_WIN32_NT)`. - - *product_type* may be one of the following values: - - +---------------------------------------+---------------------------------+ - | Constant | Meaning | - +=======================================+=================================+ - | :const:`1 (VER_NT_WORKSTATION)` | The system is a workstation. | - +---------------------------------------+---------------------------------+ - | :const:`2 (VER_NT_DOMAIN_CONTROLLER)` | The system is a domain | - | | controller. | - +---------------------------------------+---------------------------------+ - | :const:`3 (VER_NT_SERVER)` | The system is a server, but not | - | | a domain controller. | - +---------------------------------------+---------------------------------+ - - This function wraps the Win32 :c:func:`GetVersionEx` function; see the - Microsoft documentation on :c:func:`OSVERSIONINFOEX` for more information - about these fields. - - *platform_version* returns the accurate major version, minor version and - build number of the current operating system, rather than the version that - is being emulated for the process. It is intended for use in logging rather - than for feature detection. - - .. availability:: Windows. - - .. versionchanged:: 3.2 - Changed to a named tuple and added *service_pack_minor*, - *service_pack_major*, *suite_mask*, and *product_type*. - - .. versionchanged:: 3.6 - Added *platform_version* - - -.. function:: get_asyncgen_hooks() - - Returns an *asyncgen_hooks* object, which is similar to a - :class:`~collections.namedtuple` of the form `(firstiter, finalizer)`, - where *firstiter* and *finalizer* are expected to be either ``None`` or - functions which take an :term:`asynchronous generator iterator` as an - argument, and are used to schedule finalization of an asynchronous - generator by an event loop. - - .. versionadded:: 3.6 - See :pep:`525` for more details. - - .. note:: - This function has been added on a provisional basis (see :pep:`411` - for details.) - - -.. function:: get_coroutine_origin_tracking_depth() - - Get the current coroutine origin tracking depth, as set by - :func:`set_coroutine_origin_tracking_depth`. - - .. versionadded:: 3.7 - - .. note:: - This function has been added on a provisional basis (see :pep:`411` - for details.) Use it only for debugging purposes. - - -.. data:: hash_info - - A :term:`named tuple` giving parameters of the numeric hash - implementation. For more details about hashing of numeric types, see - :ref:`numeric-hash`. - - +---------------------+--------------------------------------------------+ - | attribute | explanation | - +=====================+==================================================+ - | :const:`width` | width in bits used for hash values | - +---------------------+--------------------------------------------------+ - | :const:`modulus` | prime modulus P used for numeric hash scheme | - +---------------------+--------------------------------------------------+ - | :const:`inf` | hash value returned for a positive infinity | - +---------------------+--------------------------------------------------+ - | :const:`nan` | hash value returned for a nan | - +---------------------+--------------------------------------------------+ - | :const:`imag` | multiplier used for the imaginary part of a | - | | complex number | - +---------------------+--------------------------------------------------+ - | :const:`algorithm` | name of the algorithm for hashing of str, bytes, | - | | and memoryview | - +---------------------+--------------------------------------------------+ - | :const:`hash_bits` | internal output size of the hash algorithm | - +---------------------+--------------------------------------------------+ - | :const:`seed_bits` | size of the seed key of the hash algorithm | - +---------------------+--------------------------------------------------+ - - - .. versionadded:: 3.2 - - .. versionchanged:: 3.4 - Added *algorithm*, *hash_bits* and *seed_bits* - - -.. data:: hexversion - - The version number encoded as a single integer. This is guaranteed to increase - with each version, including proper support for non-production releases. For - example, to test that the Python interpreter is at least version 1.5.2, use:: - - if sys.hexversion >= 0x010502F0: - # use some advanced feature - ... - else: - # use an alternative implementation or warn the user - ... - - This is called ``hexversion`` since it only really looks meaningful when viewed - as the result of passing it to the built-in :func:`hex` function. The - :term:`named tuple` :data:`sys.version_info` may be used for a more - human-friendly encoding of the same information. - - More details of ``hexversion`` can be found at :ref:`apiabiversion`. - - -.. data:: implementation - - An object containing information about the implementation of the - currently running Python interpreter. The following attributes are - required to exist in all Python implementations. - - *name* is the implementation's identifier, e.g. ``'cpython'``. The actual - string is defined by the Python implementation, but it is guaranteed to be - lower case. - - *version* is a named tuple, in the same format as - :data:`sys.version_info`. It represents the version of the Python - *implementation*. This has a distinct meaning from the specific - version of the Python *language* to which the currently running - interpreter conforms, which ``sys.version_info`` represents. For - example, for PyPy 1.8 ``sys.implementation.version`` might be - ``sys.version_info(1, 8, 0, 'final', 0)``, whereas ``sys.version_info`` - would be ``sys.version_info(2, 7, 2, 'final', 0)``. For CPython they - are the same value, since it is the reference implementation. - - *hexversion* is the implementation version in hexadecimal format, like - :data:`sys.hexversion`. - - *cache_tag* is the tag used by the import machinery in the filenames of - cached modules. By convention, it would be a composite of the - implementation's name and version, like ``'cpython-33'``. However, a - Python implementation may use some other value if appropriate. If - ``cache_tag`` is set to ``None``, it indicates that module caching should - be disabled. - - :data:`sys.implementation` may contain additional attributes specific to - the Python implementation. These non-standard attributes must start with - an underscore, and are not described here. Regardless of its contents, - :data:`sys.implementation` will not change during a run of the interpreter, - nor between implementation versions. (It may change between Python - language versions, however.) See :pep:`421` for more information. - - .. versionadded:: 3.3 - - .. note:: - - The addition of new required attributes must go through the normal PEP - process. See :pep:`421` for more information. - -.. data:: int_info - - A :term:`named tuple` that holds information about Python's internal - representation of integers. The attributes are read only. - - .. tabularcolumns:: |l|L| - - +-------------------------+----------------------------------------------+ - | Attribute | Explanation | - +=========================+==============================================+ - | :const:`bits_per_digit` | number of bits held in each digit. Python | - | | integers are stored internally in base | - | | ``2**int_info.bits_per_digit`` | - +-------------------------+----------------------------------------------+ - | :const:`sizeof_digit` | size in bytes of the C type used to | - | | represent a digit | - +-------------------------+----------------------------------------------+ - - .. versionadded:: 3.1 - - -.. data:: __interactivehook__ - - When this attribute exists, its value is automatically called (with no - arguments) when the interpreter is launched in :ref:`interactive mode - `. This is done after the :envvar:`PYTHONSTARTUP` file is - read, so that you can set this hook there. The :mod:`site` module - :ref:`sets this `. - - .. audit-event:: cpython.run_interactivehook hook sys.__interactivehook__ - - Raises an :ref:`auditing event ` - ``cpython.run_interactivehook`` with the hook object as the argument when - the hook is called on startup. - - .. versionadded:: 3.4 - - -.. function:: intern(string) - - Enter *string* in the table of "interned" strings and return the interned string - -- which is *string* itself or a copy. Interning strings is useful to gain a - little performance on dictionary lookup -- if the keys in a dictionary are - interned, and the lookup key is interned, the key comparisons (after hashing) - can be done by a pointer compare instead of a string compare. Normally, the - names used in Python programs are automatically interned, and the dictionaries - used to hold module, class or instance attributes have interned keys. - - Interned strings are not immortal; you must keep a reference to the return - value of :func:`intern` around to benefit from it. - - -.. function:: is_finalizing() - - Return :const:`True` if the Python interpreter is - :term:`shutting down `, :const:`False` otherwise. - - .. versionadded:: 3.5 - - -.. data:: last_type - last_value - last_traceback - - These three variables are not always defined; they are set when an exception is - not handled and the interpreter prints an error message and a stack traceback. - Their intended use is to allow an interactive user to import a debugger module - and engage in post-mortem debugging without having to re-execute the command - that caused the error. (Typical use is ``import pdb; pdb.pm()`` to enter the - post-mortem debugger; see :mod:`pdb` module for - more information.) - - The meaning of the variables is the same as that of the return values from - :func:`exc_info` above. - - -.. data:: maxsize - - An integer giving the maximum value a variable of type :c:type:`Py_ssize_t` can - take. It's usually ``2**31 - 1`` on a 32-bit platform and ``2**63 - 1`` on a - 64-bit platform. - - -.. data:: maxunicode - - An integer giving the value of the largest Unicode code point, - i.e. ``1114111`` (``0x10FFFF`` in hexadecimal). - - .. versionchanged:: 3.3 - Before :pep:`393`, ``sys.maxunicode`` used to be either ``0xFFFF`` - or ``0x10FFFF``, depending on the configuration option that specified - whether Unicode characters were stored as UCS-2 or UCS-4. - - -.. data:: meta_path - - A list of :term:`meta path finder` objects that have their - :meth:`~importlib.abc.MetaPathFinder.find_spec` methods called to see if one - of the objects can find the module to be imported. The - :meth:`~importlib.abc.MetaPathFinder.find_spec` method is called with at - least the absolute name of the module being imported. If the module to be - imported is contained in a package, then the parent package's :attr:`__path__` - attribute is passed in as a second argument. The method returns a - :term:`module spec`, or ``None`` if the module cannot be found. - - .. seealso:: - - :class:`importlib.abc.MetaPathFinder` - The abstract base class defining the interface of finder objects on - :data:`meta_path`. - :class:`importlib.machinery.ModuleSpec` - The concrete class which - :meth:`~importlib.abc.MetaPathFinder.find_spec` should return - instances of. - - .. versionchanged:: 3.4 - - :term:`Module specs ` were introduced in Python 3.4, by - :pep:`451`. Earlier versions of Python looked for a method called - :meth:`~importlib.abc.MetaPathFinder.find_module`. - This is still called as a fallback if a :data:`meta_path` entry doesn't - have a :meth:`~importlib.abc.MetaPathFinder.find_spec` method. - -.. data:: modules - - This is a dictionary that maps module names to modules which have already been - loaded. This can be manipulated to force reloading of modules and other tricks. - However, replacing the dictionary will not necessarily work as expected and - deleting essential items from the dictionary may cause Python to fail. - - -.. data:: path - - .. index:: triple: module; search; path - - A list of strings that specifies the search path for modules. Initialized from - the environment variable :envvar:`PYTHONPATH`, plus an installation-dependent - default. - - As initialized upon program startup, the first item of this list, ``path[0]``, - is the directory containing the script that was used to invoke the Python - interpreter. If the script directory is not available (e.g. if the interpreter - is invoked interactively or if the script is read from standard input), - ``path[0]`` is the empty string, which directs Python to search modules in the - current directory first. Notice that the script directory is inserted *before* - the entries inserted as a result of :envvar:`PYTHONPATH`. - - A program is free to modify this list for its own purposes. Only strings - and bytes should be added to :data:`sys.path`; all other data types are - ignored during import. - - - .. seealso:: - Module :mod:`site` This describes how to use .pth files to extend - :data:`sys.path`. - - -.. data:: path_hooks - - A list of callables that take a path argument to try to create a - :term:`finder` for the path. If a finder can be created, it is to be - returned by the callable, else raise :exc:`ImportError`. - - Originally specified in :pep:`302`. - - -.. data:: path_importer_cache - - A dictionary acting as a cache for :term:`finder` objects. The keys are - paths that have been passed to :data:`sys.path_hooks` and the values are - the finders that are found. If a path is a valid file system path but no - finder is found on :data:`sys.path_hooks` then ``None`` is - stored. - - Originally specified in :pep:`302`. - - .. versionchanged:: 3.3 - ``None`` is stored instead of :class:`imp.NullImporter` when no finder - is found. - - -.. data:: platform - - This string contains a platform identifier that can be used to append - platform-specific components to :data:`sys.path`, for instance. - - For Unix systems, except on Linux and AIX, this is the lowercased OS name as - returned by ``uname -s`` with the first part of the version as returned by - ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, *at the time - when Python was built*. Unless you want to test for a specific system - version, it is therefore recommended to use the following idiom:: - - if sys.platform.startswith('freebsd'): - # FreeBSD-specific code here... - elif sys.platform.startswith('linux'): - # Linux-specific code here... - elif sys.platform.startswith('aix'): - # AIX-specific code here... - - For other systems, the values are: - - ================ =========================== - System ``platform`` value - ================ =========================== - AIX ``'aix'`` - Linux ``'linux'`` - Windows ``'win32'`` - Windows/Cygwin ``'cygwin'`` - macOS ``'darwin'`` - ================ =========================== - - .. versionchanged:: 3.3 - On Linux, :attr:`sys.platform` doesn't contain the major version anymore. - It is always ``'linux'``, instead of ``'linux2'`` or ``'linux3'``. Since - older Python versions include the version number, it is recommended to - always use the ``startswith`` idiom presented above. - - .. versionchanged:: 3.8 - On AIX, :attr:`sys.platform` doesn't contain the major version anymore. - It is always ``'aix'``, instead of ``'aix5'`` or ``'aix7'``. Since - older Python versions include the version number, it is recommended to - always use the ``startswith`` idiom presented above. - - .. seealso:: - - :attr:`os.name` has a coarser granularity. :func:`os.uname` gives - system-dependent version information. - - The :mod:`platform` module provides detailed checks for the - system's identity. - - -.. data:: prefix - - A string giving the site-specific directory prefix where the platform - independent Python files are installed; by default, this is the string - ``'/usr/local'``. This can be set at build time with the ``--prefix`` - argument to the :program:`configure` script. The main collection of Python - library modules is installed in the directory :file:`{prefix}/lib/python{X.Y}` - while the platform independent header files (all except :file:`pyconfig.h`) are - stored in :file:`{prefix}/include/python{X.Y}`, where *X.Y* is the version - number of Python, for example ``3.2``. - - .. note:: If a :ref:`virtual environment ` is in effect, this - value will be changed in ``site.py`` to point to the virtual - environment. The value for the Python installation will still be - available, via :data:`base_prefix`. - - -.. data:: ps1 - ps2 - - .. index:: - single: interpreter prompts - single: prompts, interpreter - single: >>>; interpreter prompt - single: ...; interpreter prompt - - Strings specifying the primary and secondary prompt of the interpreter. These - are only defined if the interpreter is in interactive mode. Their initial - values in this case are ``'>>> '`` and ``'... '``. If a non-string object is - assigned to either variable, its :func:`str` is re-evaluated each time the - interpreter prepares to read a new interactive command; this can be used to - implement a dynamic prompt. - - -.. function:: setdlopenflags(n) - - Set the flags used by the interpreter for :c:func:`dlopen` calls, such as when - the interpreter loads extension modules. Among other things, this will enable a - lazy resolving of symbols when importing a module, if called as - ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as - ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values - can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. - :data:`os.RTLD_LAZY`). - - .. availability:: Unix. - -.. function:: setprofile(profilefunc) - - .. index:: - single: profile function - single: profiler - - Set the system's profile function, which allows you to implement a Python source - code profiler in Python. See chapter :ref:`profile` for more information on the - Python profiler. The system's profile function is called similarly to the - system's trace function (see :func:`settrace`), but it is called with different events, - for example it isn't called for each executed line of code (only on call and return, - but the return event is reported even when an exception has been set). The function is - thread-specific, but there is no way for the profiler to know about context switches between - threads, so it does not make sense to use this in the presence of multiple threads. Also, - its return value is not used, so it can simply return ``None``. Error in the profile - function will cause itself unset. - - Profile functions should have three arguments: *frame*, *event*, and - *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, - ``'return'``, ``'c_call'``, ``'c_return'``, or ``'c_exception'``. *arg* depends - on the event type. - - .. audit-event:: sys.setprofile "" sys.setprofile - - The events have the following meaning: - - ``'call'`` - A function is called (or some other code block entered). The - profile function is called; *arg* is ``None``. - - ``'return'`` - A function (or other code block) is about to return. The profile - function is called; *arg* is the value that will be returned, or ``None`` - if the event is caused by an exception being raised. - - ``'c_call'`` - A C function is about to be called. This may be an extension function or - a built-in. *arg* is the C function object. - - ``'c_return'`` - A C function has returned. *arg* is the C function object. - - ``'c_exception'`` - A C function has raised an exception. *arg* is the C function object. - -.. function:: setrecursionlimit(limit) - - Set the maximum depth of the Python interpreter stack to *limit*. This limit - prevents infinite recursion from causing an overflow of the C stack and crashing - Python. - - The highest possible limit is platform-dependent. A user may need to set the - limit higher when they have a program that requires deep recursion and a platform - that supports a higher limit. This should be done with care, because a too-high - limit can lead to a crash. - - If the new limit is too low at the current recursion depth, a - :exc:`RecursionError` exception is raised. - - .. versionchanged:: 3.5.1 - A :exc:`RecursionError` exception is now raised if the new limit is too - low at the current recursion depth. - - -.. function:: setswitchinterval(interval) - - Set the interpreter's thread switch interval (in seconds). This floating-point - value determines the ideal duration of the "timeslices" allocated to - concurrently running Python threads. Please note that the actual value - can be higher, especially if long-running internal functions or methods - are used. Also, which thread becomes scheduled at the end of the interval - is the operating system's decision. The interpreter doesn't have its - own scheduler. - - .. versionadded:: 3.2 - - -.. function:: settrace(tracefunc) - - .. index:: - single: trace function - single: debugger - - Set the system's trace function, which allows you to implement a Python - source code debugger in Python. The function is thread-specific; for a - debugger to support multiple threads, it must register a trace function using - :func:`settrace` for each thread being debugged or use :func:`threading.settrace`. - - Trace functions should have three arguments: *frame*, *event*, and - *arg*. *frame* is the current stack frame. *event* is a string: ``'call'``, - ``'line'``, ``'return'``, ``'exception'`` or ``'opcode'``. *arg* depends on - the event type. - - The trace function is invoked (with *event* set to ``'call'``) whenever a new - local scope is entered; it should return a reference to a local trace - function to be used for the new scope, or ``None`` if the scope shouldn't be - traced. - - The local trace function should return a reference to itself (or to another - function for further tracing in that scope), or ``None`` to turn off tracing - in that scope. - - If there is any error occurred in the trace function, it will be unset, just - like ``settrace(None)`` is called. - - The events have the following meaning: - - ``'call'`` - A function is called (or some other code block entered). The - global trace function is called; *arg* is ``None``; the return value - specifies the local trace function. - - ``'line'`` - The interpreter is about to execute a new line of code or re-execute the - condition of a loop. The local trace function is called; *arg* is - ``None``; the return value specifies the new local trace function. See - :file:`Objects/lnotab_notes.txt` for a detailed explanation of how this - works. - Per-line events may be disabled for a frame by setting - :attr:`f_trace_lines` to :const:`False` on that frame. - - ``'return'`` - A function (or other code block) is about to return. The local trace - function is called; *arg* is the value that will be returned, or ``None`` - if the event is caused by an exception being raised. The trace function's - return value is ignored. - - ``'exception'`` - An exception has occurred. The local trace function is called; *arg* is a - tuple ``(exception, value, traceback)``; the return value specifies the - new local trace function. - - ``'opcode'`` - The interpreter is about to execute a new opcode (see :mod:`dis` for - opcode details). The local trace function is called; *arg* is - ``None``; the return value specifies the new local trace function. - Per-opcode events are not emitted by default: they must be explicitly - requested by setting :attr:`f_trace_opcodes` to :const:`True` on the - frame. - - Note that as an exception is propagated down the chain of callers, an - ``'exception'`` event is generated at each level. - - For more fine-grained usage, it's possible to set a trace function by - assigning ``frame.f_trace = tracefunc`` explicitly, rather than relying on - it being set indirectly via the return value from an already installed - trace function. This is also required for activating the trace function on - the current frame, which :func:`settrace` doesn't do. Note that in order - for this to work, a global tracing function must have been installed - with :func:`settrace` in order to enable the runtime tracing machinery, - but it doesn't need to be the same tracing function (e.g. it could be a - low overhead tracing function that simply returns ``None`` to disable - itself immediately on each frame). - - For more information on code and frame objects, refer to :ref:`types`. - - .. audit-event:: sys.settrace "" sys.settrace - - .. impl-detail:: - - The :func:`settrace` function is intended only for implementing debuggers, - profilers, coverage tools and the like. Its behavior is part of the - implementation platform, rather than part of the language definition, and - thus may not be available in all Python implementations. - - .. versionchanged:: 3.7 - - ``'opcode'`` event type added; :attr:`f_trace_lines` and - :attr:`f_trace_opcodes` attributes added to frames - -.. function:: set_asyncgen_hooks(firstiter, finalizer) - - Accepts two optional keyword arguments which are callables that accept an - :term:`asynchronous generator iterator` as an argument. The *firstiter* - callable will be called when an asynchronous generator is iterated for the - first time. The *finalizer* will be called when an asynchronous generator - is about to be garbage collected. - - .. audit-event:: sys.set_asyncgen_hooks_firstiter "" sys.set_asyncgen_hooks - - .. audit-event:: sys.set_asyncgen_hooks_finalizer "" sys.set_asyncgen_hooks - - Two auditing events are raised because the underlying API consists of two - calls, each of which must raise its own event. - - .. versionadded:: 3.6 - See :pep:`525` for more details, and for a reference example of a - *finalizer* method see the implementation of - ``asyncio.Loop.shutdown_asyncgens`` in - :source:`Lib/asyncio/base_events.py` - - .. note:: - This function has been added on a provisional basis (see :pep:`411` - for details.) - -.. function:: set_coroutine_origin_tracking_depth(depth) - - Allows enabling or disabling coroutine origin tracking. When - enabled, the ``cr_origin`` attribute on coroutine objects will - contain a tuple of (filename, line number, function name) tuples - describing the traceback where the coroutine object was created, - with the most recent call first. When disabled, ``cr_origin`` will - be None. - - To enable, pass a *depth* value greater than zero; this sets the - number of frames whose information will be captured. To disable, - pass set *depth* to zero. - - This setting is thread-specific. - - .. versionadded:: 3.7 - - .. note:: - This function has been added on a provisional basis (see :pep:`411` - for details.) Use it only for debugging purposes. - -.. function:: _enablelegacywindowsfsencoding() - - Changes the default filesystem encoding and errors mode to 'mbcs' and - 'replace' respectively, for consistency with versions of Python prior to 3.6. - - This is equivalent to defining the :envvar:`PYTHONLEGACYWINDOWSFSENCODING` - environment variable before launching Python. - - .. availability:: Windows. - - .. versionadded:: 3.6 - See :pep:`529` for more details. - -.. data:: stdin - stdout - stderr - - :term:`File objects ` used by the interpreter for standard - input, output and errors: - - * ``stdin`` is used for all interactive input (including calls to - :func:`input`); - * ``stdout`` is used for the output of :func:`print` and :term:`expression` - statements and for the prompts of :func:`input`; - * The interpreter's own prompts and its error messages go to ``stderr``. - - These streams are regular :term:`text files ` like those - returned by the :func:`open` function. Their parameters are chosen as - follows: - - * The character encoding is platform-dependent. Non-Windows - platforms use the locale encoding (see - :meth:`locale.getpreferredencoding()`). - - On Windows, UTF-8 is used for the console device. Non-character - devices such as disk files and pipes use the system locale - encoding (i.e. the ANSI codepage). Non-console character - devices such as NUL (i.e. where ``isatty()`` returns ``True``) use the - value of the console input and output codepages at startup, - respectively for stdin and stdout/stderr. This defaults to the - system locale encoding if the process is not initially attached - to a console. - - The special behaviour of the console can be overridden - by setting the environment variable PYTHONLEGACYWINDOWSSTDIO - before starting Python. In that case, the console codepages are - used as for any other character device. - - Under all platforms, you can override the character encoding by - setting the :envvar:`PYTHONIOENCODING` environment variable before - starting Python or by using the new :option:`-X` ``utf8`` command - line option and :envvar:`PYTHONUTF8` environment variable. However, - for the Windows console, this only applies when - :envvar:`PYTHONLEGACYWINDOWSSTDIO` is also set. - - * When interactive, the ``stdout`` stream is line-buffered. Otherwise, - it is block-buffered like regular text files. The ``stderr`` stream - is line-buffered in both cases. You can make both streams unbuffered - by passing the :option:`-u` command-line option or setting the - :envvar:`PYTHONUNBUFFERED` environment variable. - - .. versionchanged:: 3.9 - Non-interactive ``stderr`` is now line-buffered instead of fully - buffered. - - .. note:: - - To write or read binary data from/to the standard streams, use the - underlying binary :data:`~io.TextIOBase.buffer` object. For example, to - write bytes to :data:`stdout`, use ``sys.stdout.buffer.write(b'abc')``. - - However, if you are writing a library (and do not control in which - context its code will be executed), be aware that the standard streams - may be replaced with file-like objects like :class:`io.StringIO` which - do not support the :attr:`~io.BufferedIOBase.buffer` attribute. - - -.. data:: __stdin__ - __stdout__ - __stderr__ - - These objects contain the original values of ``stdin``, ``stderr`` and - ``stdout`` at the start of the program. They are used during finalization, - and could be useful to print to the actual standard stream no matter if the - ``sys.std*`` object has been redirected. - - It can also be used to restore the actual files to known working file objects - in case they have been overwritten with a broken object. However, the - preferred way to do this is to explicitly save the previous stream before - replacing it, and restore the saved object. - - .. note:: - Under some conditions ``stdin``, ``stdout`` and ``stderr`` as well as the - original values ``__stdin__``, ``__stdout__`` and ``__stderr__`` can be - ``None``. It is usually the case for Windows GUI apps that aren't connected - to a console and Python apps started with :program:`pythonw`. - - -.. data:: thread_info - - A :term:`named tuple` holding information about the thread - implementation. - - .. tabularcolumns:: |l|p{0.7\linewidth}| - - +------------------+---------------------------------------------------------+ - | Attribute | Explanation | - +==================+=========================================================+ - | :const:`name` | Name of the thread implementation: | - | | | - | | * ``'nt'``: Windows threads | - | | * ``'pthread'``: POSIX threads | - | | * ``'solaris'``: Solaris threads | - +------------------+---------------------------------------------------------+ - | :const:`lock` | Name of the lock implementation: | - | | | - | | * ``'semaphore'``: a lock uses a semaphore | - | | * ``'mutex+cond'``: a lock uses a mutex | - | | and a condition variable | - | | * ``None`` if this information is unknown | - +------------------+---------------------------------------------------------+ - | :const:`version` | Name and version of the thread library. It is a string, | - | | or ``None`` if this information is unknown. | - +------------------+---------------------------------------------------------+ - - .. versionadded:: 3.3 - - -.. data:: tracebacklimit - - When this variable is set to an integer value, it determines the maximum number - of levels of traceback information printed when an unhandled exception occurs. - The default is ``1000``. When set to ``0`` or less, all traceback information - is suppressed and only the exception type and value are printed. - - -.. function:: unraisablehook(unraisable, /) - - Handle an unraisable exception. - - Called when an exception has occurred but there is no way for Python to - handle it. For example, when a destructor raises an exception or during - garbage collection (:func:`gc.collect`). - - The *unraisable* argument has the following attributes: - - * *exc_type*: Exception type. - * *exc_value*: Exception value, can be ``None``. - * *exc_traceback*: Exception traceback, can be ``None``. - * *err_msg*: Error message, can be ``None``. - * *object*: Object causing the exception, can be ``None``. - - The default hook formats *err_msg* and *object* as: - ``f'{err_msg}: {object!r}'``; use "Exception ignored in" error message - if *err_msg* is ``None``. - - :func:`sys.unraisablehook` can be overridden to control how unraisable - exceptions are handled. - - Storing *exc_value* using a custom hook can create a reference cycle. It - should be cleared explicitly to break the reference cycle when the - exception is no longer needed. - - Storing *object* using a custom hook can resurrect it if it is set to an - object which is being finalized. Avoid storing *object* after the custom - hook completes to avoid resurrecting objects. - - See also :func:`excepthook` which handles uncaught exceptions. - - .. audit-event:: sys.unraisablehook hook,unraisable sys.unraisablehook - - Raise an auditing event ``sys.unraisablehook`` with arguments - ``hook``, ``unraisable`` when an exception that cannot be handled occurs. - The ``unraisable`` object is the same as what will be passed to the hook. - If no hook has been set, ``hook`` may be ``None``. - - .. versionadded:: 3.8 - -.. data:: version - - A string containing the version number of the Python interpreter plus additional - information on the build number and compiler used. This string is displayed - when the interactive interpreter is started. Do not extract version information - out of it, rather, use :data:`version_info` and the functions provided by the - :mod:`platform` module. - - -.. data:: api_version - - The C API version for this interpreter. Programmers may find this useful when - debugging version conflicts between Python and extension modules. - - -.. data:: version_info - - A tuple containing the five components of the version number: *major*, *minor*, - *micro*, *releaselevel*, and *serial*. All values except *releaselevel* are - integers; the release level is ``'alpha'``, ``'beta'``, ``'candidate'``, or - ``'final'``. The ``version_info`` value corresponding to the Python version 2.0 - is ``(2, 0, 0, 'final', 0)``. The components can also be accessed by name, - so ``sys.version_info[0]`` is equivalent to ``sys.version_info.major`` - and so on. - - .. versionchanged:: 3.1 - Added named component attributes. - -.. data:: warnoptions - - This is an implementation detail of the warnings framework; do not modify this - value. Refer to the :mod:`warnings` module for more information on the warnings - framework. - - -.. data:: winver - - The version number used to form registry keys on Windows platforms. This is - stored as string resource 1000 in the Python DLL. The value is normally the - first three characters of :const:`version`. It is provided in the :mod:`sys` - module for informational purposes; modifying this value has no effect on the - registry keys used by Python. - - .. availability:: Windows. - - -.. data:: _xoptions - - A dictionary of the various implementation-specific flags passed through - the :option:`-X` command-line option. Option names are either mapped to - their values, if given explicitly, or to :const:`True`. Example: - - .. code-block:: shell-session - - $ ./python -Xa=b -Xc - Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50) - [GCC 4.4.3] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - >>> import sys - >>> sys._xoptions - {'a': 'b', 'c': True} - - .. impl-detail:: - - This is a CPython-specific way of accessing options passed through - :option:`-X`. Other implementations may export them through other - means, or not at all. - - .. versionadded:: 3.2 - - -.. rubric:: Citations - -.. [C99] ISO/IEC 9899:1999. "Programming languages -- C." A public draft of this standard is available at http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf\ . diff --git a/Doc/library/typing.rst.bak b/Doc/library/typing.rst.bak deleted file mode 100644 index 323dac20822010..00000000000000 --- a/Doc/library/typing.rst.bak +++ /dev/null @@ -1,1374 +0,0 @@ -:mod:`typing` --- Support for type hints -======================================== - -.. module:: typing - :synopsis: Support for type hints (see :pep:`484`). - -.. versionadded:: 3.5 - -**Source code:** :source:`Lib/typing.py` - -.. note:: - - The Python runtime does not enforce function and variable type annotations. - They can be used by third party tools such as type checkers, IDEs, linters, - etc. - --------------- - -This module provides runtime support for type hints as specified by -:pep:`484`, :pep:`526`, :pep:`544`, :pep:`586`, :pep:`589`, and :pep:`591`. -The most fundamental support consists of the types :data:`Any`, :data:`Union`, -:data:`Tuple`, :data:`Callable`, :class:`TypeVar`, and -:class:`Generic`. For full specification please see :pep:`484`. For -a simplified introduction to type hints see :pep:`483`. - - -The function below takes and returns a string and is annotated as follows:: - - def greeting(name: str) -> str: - return 'Hello ' + name - -In the function ``greeting``, the argument ``name`` is expected to be of type -:class:`str` and the return type :class:`str`. Subtypes are accepted as -arguments. - -Type aliases ------------- - -A type alias is defined by assigning the type to the alias. In this example, -``Vector`` and ``List[float]`` will be treated as interchangeable synonyms:: - - from typing import List - Vector = List[float] - - def scale(scalar: float, vector: Vector) -> Vector: - return [scalar * num for num in vector] - - # typechecks; a list of floats qualifies as a Vector. - new_vector = scale(2.0, [1.0, -4.2, 5.4]) - -Type aliases are useful for simplifying complex type signatures. For example:: - - from typing import Dict, Tuple, Sequence - - ConnectionOptions = Dict[str, str] - Address = Tuple[str, int] - Server = Tuple[Address, ConnectionOptions] - - def broadcast_message(message: str, servers: Sequence[Server]) -> None: - ... - - # The static type checker will treat the previous type signature as - # being exactly equivalent to this one. - def broadcast_message( - message: str, - servers: Sequence[Tuple[Tuple[str, int], Dict[str, str]]]) -> None: - ... - -Note that ``None`` as a type hint is a special case and is replaced by -``type(None)``. - -.. _distinct: - -NewType -------- - -Use the :func:`NewType` helper function to create distinct types:: - - from typing import NewType - - UserId = NewType('UserId', int) - some_id = UserId(524313) - -The static type checker will treat the new type as if it were a subclass -of the original type. This is useful in helping catch logical errors:: - - def get_user_name(user_id: UserId) -> str: - ... - - # typechecks - user_a = get_user_name(UserId(42351)) - - # does not typecheck; an int is not a UserId - user_b = get_user_name(-1) - -You may still perform all ``int`` operations on a variable of type ``UserId``, -but the result will always be of type ``int``. This lets you pass in a -``UserId`` wherever an ``int`` might be expected, but will prevent you from -accidentally creating a ``UserId`` in an invalid way:: - - # 'output' is of type 'int', not 'UserId' - output = UserId(23413) + UserId(54341) - -Note that these checks are enforced only by the static type checker. At runtime, -the statement ``Derived = NewType('Derived', Base)`` will make ``Derived`` a -function that immediately returns whatever parameter you pass it. That means -the expression ``Derived(some_value)`` does not create a new class or introduce -any overhead beyond that of a regular function call. - -More precisely, the expression ``some_value is Derived(some_value)`` is always -true at runtime. - -This also means that it is not possible to create a subtype of ``Derived`` -since it is an identity function at runtime, not an actual type:: - - from typing import NewType - - UserId = NewType('UserId', int) - - # Fails at runtime and does not typecheck - class AdminUserId(UserId): pass - -However, it is possible to create a :func:`NewType` based on a 'derived' ``NewType``:: - - from typing import NewType - - UserId = NewType('UserId', int) - - ProUserId = NewType('ProUserId', UserId) - -and typechecking for ``ProUserId`` will work as expected. - -See :pep:`484` for more details. - -.. note:: - - Recall that the use of a type alias declares two types to be *equivalent* to - one another. Doing ``Alias = Original`` will make the static type checker - treat ``Alias`` as being *exactly equivalent* to ``Original`` in all cases. - This is useful when you want to simplify complex type signatures. - - In contrast, ``NewType`` declares one type to be a *subtype* of another. - Doing ``Derived = NewType('Derived', Original)`` will make the static type - checker treat ``Derived`` as a *subclass* of ``Original``, which means a - value of type ``Original`` cannot be used in places where a value of type - ``Derived`` is expected. This is useful when you want to prevent logic - errors with minimal runtime cost. - -.. versionadded:: 3.5.2 - -Callable --------- - -Frameworks expecting callback functions of specific signatures might be -type hinted using ``Callable[[Arg1Type, Arg2Type], ReturnType]``. - -For example:: - - from typing import Callable - - def feeder(get_next_item: Callable[[], str]) -> None: - # Body - - def async_query(on_success: Callable[[int], None], - on_error: Callable[[int, Exception], None]) -> None: - # Body - -It is possible to declare the return type of a callable without specifying -the call signature by substituting a literal ellipsis -for the list of arguments in the type hint: ``Callable[..., ReturnType]``. - -.. _generics: - -Generics --------- - -Since type information about objects kept in containers cannot be statically -inferred in a generic way, abstract base classes have been extended to support -subscription to denote expected types for container elements. - -:: - - from typing import Mapping, Sequence - - def notify_by_email(employees: Sequence[Employee], - overrides: Mapping[str, str]) -> None: ... - -Generics can be parameterized by using a new factory available in typing -called :class:`TypeVar`. - -:: - - from typing import Sequence, TypeVar - - T = TypeVar('T') # Declare type variable - - def first(l: Sequence[T]) -> T: # Generic function - return l[0] - - -User-defined generic types --------------------------- - -A user-defined class can be defined as a generic class. - -:: - - from typing import TypeVar, Generic - from logging import Logger - - T = TypeVar('T') - - class LoggedVar(Generic[T]): - def __init__(self, value: T, name: str, logger: Logger) -> None: - self.name = name - self.logger = logger - self.value = value - - def set(self, new: T) -> None: - self.log('Set ' + repr(self.value)) - self.value = new - - def get(self) -> T: - self.log('Get ' + repr(self.value)) - return self.value - - def log(self, message: str) -> None: - self.logger.info('%s: %s', self.name, message) - -``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a -single type parameter ``T`` . This also makes ``T`` valid as a type within the -class body. - -The :class:`Generic` base class defines :meth:`__class_getitem__` so that -``LoggedVar[t]`` is valid as a type:: - - from typing import Iterable - - def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None: - for var in vars: - var.set(0) - -A generic type can have any number of type variables, and type variables may -be constrained:: - - from typing import TypeVar, Generic - ... - - T = TypeVar('T') - S = TypeVar('S', int, str) - - class StrangePair(Generic[T, S]): - ... - -Each type variable argument to :class:`Generic` must be distinct. -This is thus invalid:: - - from typing import TypeVar, Generic - ... - - T = TypeVar('T') - - class Pair(Generic[T, T]): # INVALID - ... - -You can use multiple inheritance with :class:`Generic`:: - - from typing import TypeVar, Generic, Sized - - T = TypeVar('T') - - class LinkedList(Sized, Generic[T]): - ... - -When inheriting from generic classes, some type variables could be fixed:: - - from typing import TypeVar, Mapping - - T = TypeVar('T') - - class MyDict(Mapping[str, T]): - ... - -In this case ``MyDict`` has a single parameter, ``T``. - -Using a generic class without specifying type parameters assumes -:data:`Any` for each position. In the following example, ``MyIterable`` is -not generic but implicitly inherits from ``Iterable[Any]``:: - - from typing import Iterable - - class MyIterable(Iterable): # Same as Iterable[Any] - -User defined generic type aliases are also supported. Examples:: - - from typing import TypeVar, Iterable, Tuple, Union - S = TypeVar('S') - Response = Union[Iterable[S], int] - - # Return type here is same as Union[Iterable[str], int] - def response(query: str) -> Response[str]: - ... - - T = TypeVar('T', int, float, complex) - Vec = Iterable[Tuple[T, T]] - - def inproduct(v: Vec[T]) -> T: # Same as Iterable[Tuple[T, T]] - return sum(x*y for x, y in v) - -.. versionchanged:: 3.7 - :class:`Generic` no longer has a custom metaclass. - -A user-defined generic class can have ABCs as base classes without a metaclass -conflict. Generic metaclasses are not supported. The outcome of parameterizing -generics is cached, and most types in the typing module are hashable and -comparable for equality. - - -The :data:`Any` type --------------------- - -A special kind of type is :data:`Any`. A static type checker will treat -every type as being compatible with :data:`Any` and :data:`Any` as being -compatible with every type. - -This means that it is possible to perform any operation or method call on a -value of type on :data:`Any` and assign it to any variable:: - - from typing import Any - - a = None # type: Any - a = [] # OK - a = 2 # OK - - s = '' # type: str - s = a # OK - - def foo(item: Any) -> int: - # Typechecks; 'item' could be any type, - # and that type might have a 'bar' method - item.bar() - ... - -Notice that no typechecking is performed when assigning a value of type -:data:`Any` to a more precise type. For example, the static type checker did -not report an error when assigning ``a`` to ``s`` even though ``s`` was -declared to be of type :class:`str` and receives an :class:`int` value at -runtime! - -Furthermore, all functions without a return type or parameter types will -implicitly default to using :data:`Any`:: - - def legacy_parser(text): - ... - return data - - # A static type checker will treat the above - # as having the same signature as: - def legacy_parser(text: Any) -> Any: - ... - return data - -This behavior allows :data:`Any` to be used as an *escape hatch* when you -need to mix dynamically and statically typed code. - -Contrast the behavior of :data:`Any` with the behavior of :class:`object`. -Similar to :data:`Any`, every type is a subtype of :class:`object`. However, -unlike :data:`Any`, the reverse is not true: :class:`object` is *not* a -subtype of every other type. - -That means when the type of a value is :class:`object`, a type checker will -reject almost all operations on it, and assigning it to a variable (or using -it as a return value) of a more specialized type is a type error. For example:: - - def hash_a(item: object) -> int: - # Fails; an object does not have a 'magic' method. - item.magic() - ... - - def hash_b(item: Any) -> int: - # Typechecks - item.magic() - ... - - # Typechecks, since ints and strs are subclasses of object - hash_a(42) - hash_a("foo") - - # Typechecks, since Any is compatible with all types - hash_b(42) - hash_b("foo") - -Use :class:`object` to indicate that a value could be any type in a typesafe -manner. Use :data:`Any` to indicate that a value is dynamically typed. - - -Nominal vs structural subtyping -------------------------------- - -Initially :pep:`484` defined Python static type system as using -*nominal subtyping*. This means that a class ``A`` is allowed where -a class ``B`` is expected if and only if ``A`` is a subclass of ``B``. - -This requirement previously also applied to abstract base classes, such as -:class:`Iterable`. The problem with this approach is that a class had -to be explicitly marked to support them, which is unpythonic and unlike -what one would normally do in idiomatic dynamically typed Python code. -For example, this conforms to the :pep:`484`:: - - from typing import Sized, Iterable, Iterator - - class Bucket(Sized, Iterable[int]): - ... - def __len__(self) -> int: ... - def __iter__(self) -> Iterator[int]: ... - -:pep:`544` allows to solve this problem by allowing users to write -the above code without explicit base classes in the class definition, -allowing ``Bucket`` to be implicitly considered a subtype of both ``Sized`` -and ``Iterable[int]`` by static type checkers. This is known as -*structural subtyping* (or static duck-typing):: - - from typing import Iterator, Iterable - - class Bucket: # Note: no base classes - ... - def __len__(self) -> int: ... - def __iter__(self) -> Iterator[int]: ... - - def collect(items: Iterable[int]) -> int: ... - result = collect(Bucket()) # Passes type check - -Moreover, by subclassing a special class :class:`Protocol`, a user -can define new custom protocols to fully enjoy structural subtyping -(see examples below). - - -Classes, functions, and decorators ----------------------------------- - -The module defines the following classes, functions and decorators: - -.. class:: TypeVar - - Type variable. - - Usage:: - - T = TypeVar('T') # Can be anything - A = TypeVar('A', str, bytes) # Must be str or bytes - - Type variables exist primarily for the benefit of static type - checkers. They serve as the parameters for generic types as well - as for generic function definitions. See class Generic for more - information on generic types. Generic functions work as follows:: - - def repeat(x: T, n: int) -> Sequence[T]: - """Return a list containing n references to x.""" - return [x]*n - - def longest(x: A, y: A) -> A: - """Return the longest of two strings.""" - return x if len(x) >= len(y) else y - - The latter example's signature is essentially the overloading - of ``(str, str) -> str`` and ``(bytes, bytes) -> bytes``. Also note - that if the arguments are instances of some subclass of :class:`str`, - the return type is still plain :class:`str`. - - At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`. In general, - :func:`isinstance` and :func:`issubclass` should not be used with types. - - Type variables may be marked covariant or contravariant by passing - ``covariant=True`` or ``contravariant=True``. See :pep:`484` for more - details. By default type variables are invariant. Alternatively, - a type variable may specify an upper bound using ``bound=``. - This means that an actual type substituted (explicitly or implicitly) - for the type variable must be a subclass of the boundary type, - see :pep:`484`. - -.. class:: Generic - - Abstract base class for generic types. - - A generic type is typically declared by inheriting from an - instantiation of this class with one or more type variables. - For example, a generic mapping type might be defined as:: - - class Mapping(Generic[KT, VT]): - def __getitem__(self, key: KT) -> VT: - ... - # Etc. - - This class can then be used as follows:: - - X = TypeVar('X') - Y = TypeVar('Y') - - def lookup_name(mapping: Mapping[X, Y], key: X, default: Y) -> Y: - try: - return mapping[key] - except KeyError: - return default - -.. class:: Protocol(Generic) - - Base class for protocol classes. Protocol classes are defined like this:: - - class Proto(Protocol): - def meth(self) -> int: - ... - - Such classes are primarily used with static type checkers that recognize - structural subtyping (static duck-typing), for example:: - - class C: - def meth(self) -> int: - return 0 - - def func(x: Proto) -> int: - return x.meth() - - func(C()) # Passes static type check - - See :pep:`544` for details. Protocol classes decorated with - :func:`runtime_checkable` (described later) act as simple-minded runtime - protocols that check only the presence of given attributes, ignoring their - type signatures. - - Protocol classes can be generic, for example:: - - class GenProto(Protocol[T]): - def meth(self) -> T: - ... - - .. versionadded:: 3.8 - -.. class:: Type(Generic[CT_co]) - - A variable annotated with ``C`` may accept a value of type ``C``. In - contrast, a variable annotated with ``Type[C]`` may accept values that are - classes themselves -- specifically, it will accept the *class object* of - ``C``. For example:: - - a = 3 # Has type 'int' - b = int # Has type 'Type[int]' - c = type(a) # Also has type 'Type[int]' - - Note that ``Type[C]`` is covariant:: - - class User: ... - class BasicUser(User): ... - class ProUser(User): ... - class TeamUser(User): ... - - # Accepts User, BasicUser, ProUser, TeamUser, ... - def make_new_user(user_class: Type[User]) -> User: - # ... - return user_class() - - The fact that ``Type[C]`` is covariant implies that all subclasses of - ``C`` should implement the same constructor signature and class method - signatures as ``C``. The type checker should flag violations of this, - but should also allow constructor calls in subclasses that match the - constructor calls in the indicated base class. How the type checker is - required to handle this particular case may change in future revisions of - :pep:`484`. - - The only legal parameters for :class:`Type` are classes, :data:`Any`, - :ref:`type variables `, and unions of any of these types. - For example:: - - def new_non_team_user(user_class: Type[Union[BaseUser, ProUser]]): ... - - ``Type[Any]`` is equivalent to ``Type`` which in turn is equivalent - to ``type``, which is the root of Python's metaclass hierarchy. - - .. versionadded:: 3.5.2 - -.. class:: Iterable(Generic[T_co]) - - A generic version of :class:`collections.abc.Iterable`. - -.. class:: Iterator(Iterable[T_co]) - - A generic version of :class:`collections.abc.Iterator`. - -.. class:: Reversible(Iterable[T_co]) - - A generic version of :class:`collections.abc.Reversible`. - -.. class:: SupportsInt - - An ABC with one abstract method ``__int__``. - -.. class:: SupportsFloat - - An ABC with one abstract method ``__float__``. - -.. class:: SupportsComplex - - An ABC with one abstract method ``__complex__``. - -.. class:: SupportsBytes - - An ABC with one abstract method ``__bytes__``. - -.. class:: SupportsIndex - - An ABC with one abstract method ``__index__``. - - .. versionadded:: 3.8 - -.. class:: SupportsAbs - - An ABC with one abstract method ``__abs__`` that is covariant - in its return type. - -.. class:: SupportsRound - - An ABC with one abstract method ``__round__`` - that is covariant in its return type. - -.. class:: Container(Generic[T_co]) - - A generic version of :class:`collections.abc.Container`. - -.. class:: Hashable - - An alias to :class:`collections.abc.Hashable` - -.. class:: Sized - - An alias to :class:`collections.abc.Sized` - -.. class:: Collection(Sized, Iterable[T_co], Container[T_co]) - - A generic version of :class:`collections.abc.Collection` - - .. versionadded:: 3.6.0 - -.. class:: AbstractSet(Sized, Collection[T_co]) - - A generic version of :class:`collections.abc.Set`. - -.. class:: MutableSet(AbstractSet[T]) - - A generic version of :class:`collections.abc.MutableSet`. - -.. class:: Mapping(Sized, Collection[KT], Generic[VT_co]) - - A generic version of :class:`collections.abc.Mapping`. - This type can be used as follows:: - - def get_position_in_index(word_list: Mapping[str, int], word: str) -> int: - return word_list[word] - -.. class:: MutableMapping(Mapping[KT, VT]) - - A generic version of :class:`collections.abc.MutableMapping`. - -.. class:: Sequence(Reversible[T_co], Collection[T_co]) - - A generic version of :class:`collections.abc.Sequence`. - -.. class:: MutableSequence(Sequence[T]) - - A generic version of :class:`collections.abc.MutableSequence`. - -.. class:: ByteString(Sequence[int]) - - A generic version of :class:`collections.abc.ByteString`. - - This type represents the types :class:`bytes`, :class:`bytearray`, - and :class:`memoryview`. - - As a shorthand for this type, :class:`bytes` can be used to - annotate arguments of any of the types mentioned above. - -.. class:: Deque(deque, MutableSequence[T]) - - A generic version of :class:`collections.deque`. - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.1 - -.. class:: List(list, MutableSequence[T]) - - Generic version of :class:`list`. - Useful for annotating return types. To annotate arguments it is preferred - to use an abstract collection type such as :class:`Sequence` or - :class:`Iterable`. - - This type may be used as follows:: - - T = TypeVar('T', int, float) - - def vec2(x: T, y: T) -> List[T]: - return [x, y] - - def keep_positives(vector: Sequence[T]) -> List[T]: - return [item for item in vector if item > 0] - -.. class:: Set(set, MutableSet[T]) - - A generic version of :class:`builtins.set `. - Useful for annotating return types. To annotate arguments it is preferred - to use an abstract collection type such as :class:`AbstractSet`. - -.. class:: FrozenSet(frozenset, AbstractSet[T_co]) - - A generic version of :class:`builtins.frozenset `. - -.. class:: MappingView(Sized, Iterable[T_co]) - - A generic version of :class:`collections.abc.MappingView`. - -.. class:: KeysView(MappingView[KT_co], AbstractSet[KT_co]) - - A generic version of :class:`collections.abc.KeysView`. - -.. class:: ItemsView(MappingView, Generic[KT_co, VT_co]) - - A generic version of :class:`collections.abc.ItemsView`. - -.. class:: ValuesView(MappingView[VT_co]) - - A generic version of :class:`collections.abc.ValuesView`. - -.. class:: Awaitable(Generic[T_co]) - - A generic version of :class:`collections.abc.Awaitable`. - - .. versionadded:: 3.5.2 - -.. class:: Coroutine(Awaitable[V_co], Generic[T_co T_contra, V_co]) - - A generic version of :class:`collections.abc.Coroutine`. - The variance and order of type variables - correspond to those of :class:`Generator`, for example:: - - from typing import List, Coroutine - c = None # type: Coroutine[List[str], str, int] - ... - x = c.send('hi') # type: List[str] - async def bar() -> None: - x = await c # type: int - - .. versionadded:: 3.5.3 - -.. class:: AsyncIterable(Generic[T_co]) - - A generic version of :class:`collections.abc.AsyncIterable`. - - .. versionadded:: 3.5.2 - -.. class:: AsyncIterator(AsyncIterable[T_co]) - - A generic version of :class:`collections.abc.AsyncIterator`. - - .. versionadded:: 3.5.2 - -.. class:: ContextManager(Generic[T_co]) - - A generic version of :class:`contextlib.AbstractContextManager`. - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.0 - -.. class:: AsyncContextManager(Generic[T_co]) - - A generic version of :class:`contextlib.AbstractAsyncContextManager`. - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.2 - -.. class:: Dict(dict, MutableMapping[KT, VT]) - - A generic version of :class:`dict`. - Useful for annotating return types. To annotate arguments it is preferred - to use an abstract collection type such as :class:`Mapping`. - - This type can be used as follows:: - - def count_words(text: str) -> Dict[str, int]: - ... - -.. class:: DefaultDict(collections.defaultdict, MutableMapping[KT, VT]) - - A generic version of :class:`collections.defaultdict`. - - .. versionadded:: 3.5.2 - -.. class:: OrderedDict(collections.OrderedDict, MutableMapping[KT, VT]) - - A generic version of :class:`collections.OrderedDict`. - - .. versionadded:: 3.7.2 - -.. class:: Counter(collections.Counter, Dict[T, int]) - - A generic version of :class:`collections.Counter`. - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.1 - -.. class:: ChainMap(collections.ChainMap, MutableMapping[KT, VT]) - - A generic version of :class:`collections.ChainMap`. - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.1 - -.. class:: Generator(Iterator[T_co], Generic[T_co, T_contra, V_co]) - - A generator can be annotated by the generic type - ``Generator[YieldType, SendType, ReturnType]``. For example:: - - def echo_round() -> Generator[int, float, str]: - sent = yield 0 - while sent >= 0: - sent = yield round(sent) - return 'Done' - - Note that unlike many other generics in the typing module, the ``SendType`` - of :class:`Generator` behaves contravariantly, not covariantly or - invariantly. - - If your generator will only yield values, set the ``SendType`` and - ``ReturnType`` to ``None``:: - - def infinite_stream(start: int) -> Generator[int, None, None]: - while True: - yield start - start += 1 - - Alternatively, annotate your generator as having a return type of - either ``Iterable[YieldType]`` or ``Iterator[YieldType]``:: - - def infinite_stream(start: int) -> Iterator[int]: - while True: - yield start - start += 1 - -.. class:: AsyncGenerator(AsyncIterator[T_co], Generic[T_co, T_contra]) - - An async generator can be annotated by the generic type - ``AsyncGenerator[YieldType, SendType]``. For example:: - - async def echo_round() -> AsyncGenerator[int, float]: - sent = yield 0 - while sent >= 0.0: - rounded = await round(sent) - sent = yield rounded - - Unlike normal generators, async generators cannot return a value, so there - is no ``ReturnType`` type parameter. As with :class:`Generator`, the - ``SendType`` behaves contravariantly. - - If your generator will only yield values, set the ``SendType`` to - ``None``:: - - async def infinite_stream(start: int) -> AsyncGenerator[int, None]: - while True: - yield start - start = await increment(start) - - Alternatively, annotate your generator as having a return type of - either ``AsyncIterable[YieldType]`` or ``AsyncIterator[YieldType]``:: - - async def infinite_stream(start: int) -> AsyncIterator[int]: - while True: - yield start - start = await increment(start) - - .. versionadded:: 3.6.1 - -.. class:: Text - - ``Text`` is an alias for ``str``. It is provided to supply a forward - compatible path for Python 2 code: in Python 2, ``Text`` is an alias for - ``unicode``. - - Use ``Text`` to indicate that a value must contain a unicode string in - a manner that is compatible with both Python 2 and Python 3:: - - def add_unicode_checkmark(text: Text) -> Text: - return text + u' \u2713' - - .. versionadded:: 3.5.2 - -.. class:: IO - TextIO - BinaryIO - - Generic type ``IO[AnyStr]`` and its subclasses ``TextIO(IO[str])`` - and ``BinaryIO(IO[bytes])`` - represent the types of I/O streams such as returned by - :func:`open`. - -.. class:: Pattern - Match - - These type aliases - correspond to the return types from :func:`re.compile` and - :func:`re.match`. These types (and the corresponding functions) - are generic in ``AnyStr`` and can be made specific by writing - ``Pattern[str]``, ``Pattern[bytes]``, ``Match[str]``, or - ``Match[bytes]``. - -.. class:: NamedTuple - - Typed version of :func:`collections.namedtuple`. - - Usage:: - - class Employee(NamedTuple): - name: str - id: int - - This is equivalent to:: - - Employee = collections.namedtuple('Employee', ['name', 'id']) - - To give a field a default value, you can assign to it in the class body:: - - class Employee(NamedTuple): - name: str - id: int = 3 - - employee = Employee('Guido') - assert employee.id == 3 - - Fields with a default value must come after any fields without a default. - - The resulting class has an extra attribute ``__annotations__`` giving a - dict that maps the field names to the field types. (The field names are in - the ``_fields`` attribute and the default values are in the - ``_field_defaults`` attribute both of which are part of the namedtuple - API.) - - ``NamedTuple`` subclasses can also have docstrings and methods:: - - class Employee(NamedTuple): - """Represents an employee.""" - name: str - id: int = 3 - - def __repr__(self) -> str: - return f'' - - Backward-compatible usage:: - - Employee = NamedTuple('Employee', [('name', str), ('id', int)]) - - .. versionchanged:: 3.6 - Added support for :pep:`526` variable annotation syntax. - - .. versionchanged:: 3.6.1 - Added support for default values, methods, and docstrings. - - .. versionchanged:: 3.8 - Deprecated the ``_field_types`` attribute in favor of the more - standard ``__annotations__`` attribute which has the same information. - - .. versionchanged:: 3.8 - The ``_field_types`` and ``__annotations__`` attributes are - now regular dictionaries instead of instances of ``OrderedDict``. - -.. class:: TypedDict(dict) - - A simple typed namespace. At runtime it is equivalent to - a plain :class:`dict`. - - ``TypedDict`` creates a dictionary type that expects all of its - instances to have a certain set of keys, where each key is - associated with a value of a consistent type. This expectation - is not checked at runtime but is only enforced by type checkers. - Usage:: - - class Point2D(TypedDict): - x: int - y: int - label: str - - a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK - b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check - - assert Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') - - The type info for introspection can be accessed via ``Point2D.__annotations__`` - and ``Point2D.__total__``. To allow using this feature with older versions - of Python that do not support :pep:`526`, ``TypedDict`` supports two additional - equivalent syntactic forms:: - - Point2D = TypedDict('Point2D', x=int, y=int, label=str) - Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) - - See :pep:`589` for more examples and detailed rules of using ``TypedDict`` - with type checkers. - - .. versionadded:: 3.8 - -.. class:: ForwardRef - - A class used for internal typing representation of string forward references. - For example, ``List["SomeClass"]`` is implicitly transformed into - ``List[ForwardRef("SomeClass")]``. This class should not be instantiated by - a user, but may be used by introspection tools. - -.. function:: NewType(typ) - - A helper function to indicate a distinct types to a typechecker, - see :ref:`distinct`. At runtime it returns a function that returns - its argument. Usage:: - - UserId = NewType('UserId', int) - first_user = UserId(1) - - .. versionadded:: 3.5.2 - -.. function:: cast(typ, val) - - Cast a value to a type. - - This returns the value unchanged. To the type checker this - signals that the return value has the designated type, but at - runtime we intentionally don't check anything (we want this - to be as fast as possible). - -.. function:: get_type_hints(obj[, globals[, locals]]) - - Return a dictionary containing type hints for a function, method, module - or class object. - - This is often the same as ``obj.__annotations__``. In addition, - forward references encoded as string literals are handled by evaluating - them in ``globals`` and ``locals`` namespaces. If necessary, - ``Optional[t]`` is added for function and method annotations if a default - value equal to ``None`` is set. For a class ``C``, return - a dictionary constructed by merging all the ``__annotations__`` along - ``C.__mro__`` in reverse order. - -.. function:: get_origin(tp) -.. function:: get_args(tp) - - Provide basic introspection for generic types and special typing forms. - - For a typing object of the form ``X[Y, Z, ...]`` these functions return - ``X`` and ``(Y, Z, ...)``. If ``X`` is a generic alias for a builtin or - :mod:`collections` class, it gets normalized to the original class. - For unsupported objects return ``None`` and ``()`` correspondingly. - Examples:: - - assert get_origin(Dict[str, int]) is dict - assert get_args(Dict[int, str]) == (int, str) - - assert get_origin(Union[int, str]) is Union - assert get_args(Union[int, str]) == (int, str) - - .. versionadded:: 3.8 - -.. decorator:: overload - - The ``@overload`` decorator allows describing functions and methods - that support multiple different combinations of argument types. A series - of ``@overload``-decorated definitions must be followed by exactly one - non-``@overload``-decorated definition (for the same function/method). - The ``@overload``-decorated definitions are for the benefit of the - type checker only, since they will be overwritten by the - non-``@overload``-decorated definition, while the latter is used at - runtime but should be ignored by a type checker. At runtime, calling - a ``@overload``-decorated function directly will raise - :exc:`NotImplementedError`. An example of overload that gives a more - precise type than can be expressed using a union or a type variable:: - - @overload - def process(response: None) -> None: - ... - @overload - def process(response: int) -> Tuple[int, str]: - ... - @overload - def process(response: bytes) -> str: - ... - def process(response): - - - See :pep:`484` for details and comparison with other typing semantics. - -.. decorator:: final - - A decorator to indicate to type checkers that the decorated method - cannot be overridden, and the decorated class cannot be subclassed. - For example:: - - class Base: - @final - def done(self) -> None: - ... - class Sub(Base): - def done(self) -> None: # Error reported by type checker - ... - - @final - class Leaf: - ... - class Other(Leaf): # Error reported by type checker - ... - - There is no runtime checking of these properties. See :pep:`591` for - more details. - - .. versionadded:: 3.8 - -.. decorator:: no_type_check - - Decorator to indicate that annotations are not type hints. - - This works as class or function :term:`decorator`. With a class, it - applies recursively to all methods defined in that class (but not - to methods defined in its superclasses or subclasses). - - This mutates the function(s) in place. - -.. decorator:: no_type_check_decorator - - Decorator to give another decorator the :func:`no_type_check` effect. - - This wraps the decorator with something that wraps the decorated - function in :func:`no_type_check`. - -.. decorator:: type_check_only - - Decorator to mark a class or function to be unavailable at runtime. - - This decorator is itself not available at runtime. It is mainly - intended to mark classes that are defined in type stub files if - an implementation returns an instance of a private class:: - - @type_check_only - class Response: # private or not available at runtime - code: int - def get_header(self, name: str) -> str: ... - - def fetch_response() -> Response: ... - - Note that returning instances of private classes is not recommended. - It is usually preferable to make such classes public. - -.. decorator:: runtime_checkable - - Mark a protocol class as a runtime protocol. - - Such a protocol can be used with :func:`isinstance` and :func:`issubclass`. - This raises :exc:`TypeError` when applied to a non-protocol class. This - allows a simple-minded structural check, very similar to "one trick ponies" - in :mod:`collections.abc` such as :class:`Iterable`. For example:: - - @runtime_checkable - class Closable(Protocol): - def close(self): ... - - assert isinstance(open('/some/file'), Closable) - - **Warning:** this will check only the presence of the required methods, - not their type signatures! - - .. versionadded:: 3.8 - -.. data:: Any - - Special type indicating an unconstrained type. - - * Every type is compatible with :data:`Any`. - * :data:`Any` is compatible with every type. - -.. data:: NoReturn - - Special type indicating that a function never returns. - For example:: - - from typing import NoReturn - - def stop() -> NoReturn: - raise RuntimeError('no way') - - .. versionadded:: 3.5.4 - .. versionadded:: 3.6.2 - -.. data:: Union - - Union type; ``Union[X, Y]`` means either X or Y. - - To define a union, use e.g. ``Union[int, str]``. Details: - - * The arguments must be types and there must be at least one. - - * Unions of unions are flattened, e.g.:: - - Union[Union[int, str], float] == Union[int, str, float] - - * Unions of a single argument vanish, e.g.:: - - Union[int] == int # The constructor actually returns int - - * Redundant arguments are skipped, e.g.:: - - Union[int, str, int] == Union[int, str] - - * When comparing unions, the argument order is ignored, e.g.:: - - Union[int, str] == Union[str, int] - - * You cannot subclass or instantiate a union. - - * You cannot write ``Union[X][Y]``. - - * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``. - - .. versionchanged:: 3.7 - Don't remove explicit subclasses from unions at runtime. - -.. data:: Optional - - Optional type. - - ``Optional[X]`` is equivalent to ``Union[X, None]``. - - Note that this is not the same concept as an optional argument, - which is one that has a default. An optional argument with a - default does not require the ``Optional`` qualifier on its type - annotation just because it is optional. For example:: - - def foo(arg: int = 0) -> None: - ... - - On the other hand, if an explicit value of ``None`` is allowed, the - use of ``Optional`` is appropriate, whether the argument is optional - or not. For example:: - - def foo(arg: Optional[int] = None) -> None: - ... - -.. data:: Tuple - - Tuple type; ``Tuple[X, Y]`` is the type of a tuple of two items - with the first item of type X and the second of type Y. The type of - the empty tuple can be written as ``Tuple[()]``. - - Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding - to type variables T1 and T2. ``Tuple[int, float, str]`` is a tuple - of an int, a float and a string. - - To specify a variable-length tuple of homogeneous type, - use literal ellipsis, e.g. ``Tuple[int, ...]``. A plain :data:`Tuple` - is equivalent to ``Tuple[Any, ...]``, and in turn to :class:`tuple`. - -.. data:: Callable - - Callable type; ``Callable[[int], str]`` is a function of (int) -> str. - - The subscription syntax must always be used with exactly two - values: the argument list and the return type. The argument list - must be a list of types or an ellipsis; the return type must be - a single type. - - There is no syntax to indicate optional or keyword arguments; - such function types are rarely used as callback types. - ``Callable[..., ReturnType]`` (literal ellipsis) can be used to - type hint a callable taking any number of arguments and returning - ``ReturnType``. A plain :data:`Callable` is equivalent to - ``Callable[..., Any]``, and in turn to - :class:`collections.abc.Callable`. - -.. data:: Literal - - A type that can be used to indicate to type checkers that the - corresponding variable or function parameter has a value equivalent to - the provided literal (or one of several literals). For example:: - - def validate_simple(data: Any) -> Literal[True]: # always returns True - ... - - MODE = Literal['r', 'rb', 'w', 'wb'] - def open_helper(file: str, mode: MODE) -> str: - ... - - open_helper('/some/path', 'r') # Passes type check - open_helper('/other/path', 'typo') # Error in type checker - - ``Literal[...]`` cannot be subclassed. At runtime, an arbitrary value - is allowed as type argument to ``Literal[...]``, but type checkers may - impose restrictions. See :pep:`586` for more details about literal types. - - .. versionadded:: 3.8 - -.. data:: ClassVar - - Special type construct to mark class variables. - - As introduced in :pep:`526`, a variable annotation wrapped in ClassVar - indicates that a given attribute is intended to be used as a class variable - and should not be set on instances of that class. Usage:: - - class Starship: - stats: ClassVar[Dict[str, int]] = {} # class variable - damage: int = 10 # instance variable - - :data:`ClassVar` accepts only types and cannot be further subscribed. - - :data:`ClassVar` is not a class itself, and should not - be used with :func:`isinstance` or :func:`issubclass`. - :data:`ClassVar` does not change Python runtime behavior, but - it can be used by third-party type checkers. For example, a type checker - might flag the following code as an error:: - - enterprise_d = Starship(3000) - enterprise_d.stats = {} # Error, setting class variable on instance - Starship.stats = {} # This is OK - - .. versionadded:: 3.5.3 - -.. data:: Final - - A special typing construct to indicate to type checkers that a name - cannot be re-assigned or overridden in a subclass. For example:: - - MAX_SIZE: Final = 9000 - MAX_SIZE += 1 # Error reported by type checker - - class Connection: - TIMEOUT: Final[int] = 10 - - class FastConnector(Connection): - TIMEOUT = 1 # Error reported by type checker - - There is no runtime checking of these properties. See :pep:`591` for - more details. - - .. versionadded:: 3.8 - -.. data:: AnyStr - - ``AnyStr`` is a type variable defined as - ``AnyStr = TypeVar('AnyStr', str, bytes)``. - - It is meant to be used for functions that may accept any kind of string - without allowing different kinds of strings to mix. For example:: - - def concat(a: AnyStr, b: AnyStr) -> AnyStr: - return a + b - - concat(u"foo", u"bar") # Ok, output has type 'unicode' - concat(b"foo", b"bar") # Ok, output has type 'bytes' - concat(u"foo", b"bar") # Error, cannot mix unicode and bytes - -.. data:: TYPE_CHECKING - - A special constant that is assumed to be ``True`` by 3rd party static - type checkers. It is ``False`` at runtime. Usage:: - - if TYPE_CHECKING: - import expensive_mod - - def fun(arg: 'expensive_mod.SomeType') -> None: - local_var: expensive_mod.AnotherType = other_fun() - - Note that the first type annotation must be enclosed in quotes, making it a - "forward reference", to hide the ``expensive_mod`` reference from the - interpreter runtime. Type annotations for local variables are not - evaluated, so the second annotation does not need to be enclosed in quotes. - - .. versionadded:: 3.5.2 diff --git a/Doc/tutorial/errors.rst.bak b/Doc/tutorial/errors.rst.bak deleted file mode 100644 index 8f86eca02483a2..00000000000000 --- a/Doc/tutorial/errors.rst.bak +++ /dev/null @@ -1,474 +0,0 @@ -.. _tut-errors: - -********************* -Errors and Exceptions -********************* - -Until now error messages haven't been more than mentioned, but if you have tried -out the examples you have probably seen some. There are (at least) two -distinguishable kinds of errors: *syntax errors* and *exceptions*. - - -.. _tut-syntaxerrors: - -Syntax Errors -============= - -Syntax errors, also known as parsing errors, are perhaps the most common kind of -complaint you get while you are still learning Python:: - - >>> while True print('Hello world') - File "", line 1 - while True print('Hello world') - ^ - SyntaxError: invalid syntax - -The parser repeats the offending line and displays a little 'arrow' pointing at -the earliest point in the line where the error was detected. The error is -caused by (or at least detected at) the token *preceding* the arrow: in the -example, the error is detected at the function :func:`print`, since a colon -(``':'``) is missing before it. File name and line number are printed so you -know where to look in case the input came from a script. - - -.. _tut-exceptions: - -Exceptions -========== - -Even if a statement or expression is syntactically correct, it may cause an -error when an attempt is made to execute it. Errors detected during execution -are called *exceptions* and are not unconditionally fatal: you will soon learn -how to handle them in Python programs. Most exceptions are not handled by -programs, however, and result in error messages as shown here:: - - >>> 10 * (1/0) - Traceback (most recent call last): - File "", line 1, in - ZeroDivisionError: division by zero - >>> 4 + spam*3 - Traceback (most recent call last): - File "", line 1, in - NameError: name 'spam' is not defined - >>> '2' + 2 - Traceback (most recent call last): - File "", line 1, in - TypeError: Can't convert 'int' object to str implicitly - -The last line of the error message indicates what happened. Exceptions come in -different types, and the type is printed as part of the message: the types in -the example are :exc:`ZeroDivisionError`, :exc:`NameError` and :exc:`TypeError`. -The string printed as the exception type is the name of the built-in exception -that occurred. This is true for all built-in exceptions, but need not be true -for user-defined exceptions (although it is a useful convention). Standard -exception names are built-in identifiers (not reserved keywords). - -The rest of the line provides detail based on the type of exception and what -caused it. - -The preceding part of the error message shows the context where the exception -happened, in the form of a stack traceback. In general it contains a stack -traceback listing source lines; however, it will not display lines read from -standard input. - -:ref:`bltin-exceptions` lists the built-in exceptions and their meanings. - - -.. _tut-handling: - -Handling Exceptions -=================== - -It is possible to write programs that handle selected exceptions. Look at the -following example, which asks the user for input until a valid integer has been -entered, but allows the user to interrupt the program (using :kbd:`Control-C` or -whatever the operating system supports); note that a user-generated interruption -is signalled by raising the :exc:`KeyboardInterrupt` exception. :: - - >>> while True: - ... try: - ... x = int(input("Please enter a number: ")) - ... break - ... except ValueError: - ... print("Oops! That was no valid number. Try again...") - ... - -The :keyword:`try` statement works as follows. - -* First, the *try clause* (the statement(s) between the :keyword:`try` and - :keyword:`except` keywords) is executed. - -* If no exception occurs, the *except clause* is skipped and execution of the - :keyword:`try` statement is finished. - -* If an exception occurs during execution of the try clause, the rest of the - clause is skipped. Then if its type matches the exception named after the - :keyword:`except` keyword, the except clause is executed, and then execution - continues after the :keyword:`try` statement. - -* If an exception occurs which does not match the exception named in the except - clause, it is passed on to outer :keyword:`try` statements; if no handler is - found, it is an *unhandled exception* and execution stops with a message as - shown above. - -A :keyword:`try` statement may have more than one except clause, to specify -handlers for different exceptions. At most one handler will be executed. -Handlers only handle exceptions that occur in the corresponding try clause, not -in other handlers of the same :keyword:`!try` statement. An except clause may -name multiple exceptions as a parenthesized tuple, for example:: - - ... except (RuntimeError, TypeError, NameError): - ... pass - -A class in an :keyword:`except` clause is compatible with an exception if it is -the same class or a base class thereof (but not the other way around --- an -except clause listing a derived class is not compatible with a base class). For -example, the following code will print B, C, D in that order:: - - class B(Exception): - pass - - class C(B): - pass - - class D(C): - pass - - for cls in [B, C, D]: - try: - raise cls() - except D: - print("D") - except C: - print("C") - except B: - print("B") - -Note that if the except clauses were reversed (with ``except B`` first), it -would have printed B, B, B --- the first matching except clause is triggered. - -The last except clause may omit the exception name(s), to serve as a wildcard. -Use this with extreme caution, since it is easy to mask a real programming error -in this way! It can also be used to print an error message and then re-raise -the exception (allowing a caller to handle the exception as well):: - - import sys - - try: - f = open('myfile.txt') - s = f.readline() - i = int(s.strip()) - except OSError as err: - print("OS error: {0}".format(err)) - except ValueError: - print("Could not convert data to an integer.") - except: - print("Unexpected error:", sys.exc_info()[0]) - raise - -The :keyword:`try` ... :keyword:`except` statement has an optional *else -clause*, which, when present, must follow all except clauses. It is useful for -code that must be executed if the try clause does not raise an exception. For -example:: - - for arg in sys.argv[1:]: - try: - f = open(arg, 'r') - except OSError: - print('cannot open', arg) - else: - print(arg, 'has', len(f.readlines()), 'lines') - f.close() - -The use of the :keyword:`!else` clause is better than adding additional code to -the :keyword:`try` clause because it avoids accidentally catching an exception -that wasn't raised by the code being protected by the :keyword:`!try` ... -:keyword:`!except` statement. - -When an exception occurs, it may have an associated value, also known as the -exception's *argument*. The presence and type of the argument depend on the -exception type. - -The except clause may specify a variable after the exception name. The -variable is bound to an exception instance with the arguments stored in -``instance.args``. For convenience, the exception instance defines -:meth:`__str__` so the arguments can be printed directly without having to -reference ``.args``. One may also instantiate an exception first before -raising it and add any attributes to it as desired. :: - - >>> try: - ... raise Exception('spam', 'eggs') - ... except Exception as inst: - ... print(type(inst)) # the exception instance - ... print(inst.args) # arguments stored in .args - ... print(inst) # __str__ allows args to be printed directly, - ... # but may be overridden in exception subclasses - ... x, y = inst.args # unpack args - ... print('x =', x) - ... print('y =', y) - ... - - ('spam', 'eggs') - ('spam', 'eggs') - x = spam - y = eggs - -If an exception has arguments, they are printed as the last part ('detail') of -the message for unhandled exceptions. - -Exception handlers don't just handle exceptions if they occur immediately in the -try clause, but also if they occur inside functions that are called (even -indirectly) in the try clause. For example:: - - >>> def this_fails(): - ... x = 1/0 - ... - >>> try: - ... this_fails() - ... except ZeroDivisionError as err: - ... print('Handling run-time error:', err) - ... - Handling run-time error: division by zero - - -.. _tut-raising: - -Raising Exceptions -================== - -The :keyword:`raise` statement allows the programmer to force a specified -exception to occur. For example:: - - >>> raise NameError('HiThere') - Traceback (most recent call last): - File "", line 1, in - NameError: HiThere - -The sole argument to :keyword:`raise` indicates the exception to be raised. -This must be either an exception instance or an exception class (a class that -derives from :class:`Exception`). If an exception class is passed, it will -be implicitly instantiated by calling its constructor with no arguments:: - - raise ValueError # shorthand for 'raise ValueError()' - -If you need to determine whether an exception was raised but don't intend to -handle it, a simpler form of the :keyword:`raise` statement allows you to -re-raise the exception:: - - >>> try: - ... raise NameError('HiThere') - ... except NameError: - ... print('An exception flew by!') - ... raise - ... - An exception flew by! - Traceback (most recent call last): - File "", line 2, in - NameError: HiThere - - -.. _tut-exception-chaining: - -Exception Chaining -================== - -The :keyword:`raise` statement allows an optional :keyword:`from` which enables -chaining exceptions by setting the ``__cause__`` attribute of the raised -exception. For example:: - - raise RuntimeError from OSError - -This can be useful when you are transforming exceptions. For example:: - - >>> def func(): - ... raise IOError - ... - >>> try: - ... func() - ... except IOError as exc: - ... raise RuntimeError('Failed to open database') from exc - ... - Traceback (most recent call last): - File "", line 2, in - File "", line 2, in func - OSError - - The above exception was the direct cause of the following exception: - - Traceback (most recent call last): - File "", line 4, in - RuntimeError - -The expression following the :keyword:`from` must be either an exception or -``None``. Exception chaining happens automatically when an exception is raised -inside an exception handler or :keyword:`finally` section. Exception chaining -can be disabled by using ``from None`` idiom: - - >>> try: - ... open('database.sqlite') - ... except IOError: - ... raise RuntimeError from None - ... - Traceback (most recent call last): - File "", line 4, in - RuntimeError - - -.. _tut-userexceptions: - -User-defined Exceptions -======================= - -Programs may name their own exceptions by creating a new exception class (see -:ref:`tut-classes` for more about Python classes). Exceptions should typically -be derived from the :exc:`Exception` class, either directly or indirectly. - -Exception classes can be defined which do anything any other class can do, but -are usually kept simple, often only offering a number of attributes that allow -information about the error to be extracted by handlers for the exception. When -creating a module that can raise several distinct errors, a common practice is -to create a base class for exceptions defined by that module, and subclass that -to create specific exception classes for different error conditions:: - - class Error(Exception): - """Base class for exceptions in this module.""" - pass - - class InputError(Error): - """Exception raised for errors in the input. - - Attributes: - expression -- input expression in which the error occurred - message -- explanation of the error - """ - - def __init__(self, expression, message): - self.expression = expression - self.message = message - - class TransitionError(Error): - """Raised when an operation attempts a state transition that's not - allowed. - - Attributes: - previous -- state at beginning of transition - next -- attempted new state - message -- explanation of why the specific transition is not allowed - """ - - def __init__(self, previous, next, message): - self.previous = previous - self.next = next - self.message = message - -Most exceptions are defined with names that end in "Error", similar to the -naming of the standard exceptions. - -Many standard modules define their own exceptions to report errors that may -occur in functions they define. More information on classes is presented in -chapter :ref:`tut-classes`. - - -.. _tut-cleanup: - -Defining Clean-up Actions -========================= - -The :keyword:`try` statement has another optional clause which is intended to -define clean-up actions that must be executed under all circumstances. For -example:: - - >>> try: - ... raise KeyboardInterrupt - ... finally: - ... print('Goodbye, world!') - ... - Goodbye, world! - Traceback (most recent call last): - File "", line 2, in - KeyboardInterrupt - -If a :keyword:`finally` clause is present, the :keyword:`finally` clause will execute as the last task before the :keyword:`try` statement completes. The :keyword:`finally` clause runs whether or not the :keyword:`try` statement produces an exception. The following points discuss more complex cases when an exception occurs: - -* If an exception occurs during execution of the :keyword:`!try` clause, the exception may be handled by an :keyword:`except` clause. If the exception is not handled by an :keyword:`except` clause, the exception is re-raised after the :keyword:`!finally` clause has been executed. - -* An exception could occur during execution of an :keyword:`!except` or :keyword:`!else` clause. Again, the exception is re-raised after the :keyword:`!finally` clause has been executed. - -* If the :keyword:`!try` statement reaches a :keyword:`break`, :keyword:`continue` or :keyword:`return` statement, the :keyword:`finally` clause will execute just prior to the :keyword:`break`, :keyword:`continue` or :keyword:`return` statement's execution. - -* If a :keyword:`finally` clause includes a :keyword:`return` statement, the :keyword:`finally` clause's :keyword:`return` statement will execute before, and instead of, the :keyword:`return` statement in a :keyword:`try` clause. - -For example:: - - >>> def bool_return(): - ... try: - ... return True - ... finally: - ... return False - ... - >>> bool_return() - False - -A more complicated example:: - - >>> def divide(x, y): - ... try: - ... result = x / y - ... except ZeroDivisionError: - ... print("division by zero!") - ... else: - ... print("result is", result) - ... finally: - ... print("executing finally clause") - ... - >>> divide(2, 1) - result is 2.0 - executing finally clause - >>> divide(2, 0) - division by zero! - executing finally clause - >>> divide("2", "1") - executing finally clause - Traceback (most recent call last): - File "", line 1, in - File "", line 3, in divide - TypeError: unsupported operand type(s) for /: 'str' and 'str' - -As you can see, the :keyword:`finally` clause is executed in any event. The -:exc:`TypeError` raised by dividing two strings is not handled by the -:keyword:`except` clause and therefore re-raised after the :keyword:`!finally` -clause has been executed. - -In real world applications, the :keyword:`finally` clause is useful for -releasing external resources (such as files or network connections), regardless -of whether the use of the resource was successful. - - -.. _tut-cleanup-with: - -Predefined Clean-up Actions -=========================== - -Some objects define standard clean-up actions to be undertaken when the object -is no longer needed, regardless of whether or not the operation using the object -succeeded or failed. Look at the following example, which tries to open a file -and print its contents to the screen. :: - - for line in open("myfile.txt"): - print(line, end="") - -The problem with this code is that it leaves the file open for an indeterminate -amount of time after this part of the code has finished executing. -This is not an issue in simple scripts, but can be a problem for larger -applications. The :keyword:`with` statement allows objects like files to be -used in a way that ensures they are always cleaned up promptly and correctly. :: - - with open("myfile.txt") as f: - for line in f: - print(line, end="") - -After the statement is executed, the file *f* is always closed, even if a -problem was encountered while processing the lines. Objects which, like files, -provide predefined clean-up actions will indicate this in their documentation. - - diff --git a/Doc/whatsnew/3.8.rst.bak b/Doc/whatsnew/3.8.rst.bak deleted file mode 100644 index fabc1c597eca70..00000000000000 --- a/Doc/whatsnew/3.8.rst.bak +++ /dev/null @@ -1,2216 +0,0 @@ -**************************** - What's New In Python 3.8 -**************************** - -.. Rules for maintenance: - - * Anyone can add text to this document. Do not spend very much time - on the wording of your changes, because your text will probably - get rewritten to some degree. - - * The maintainer will go through Misc/NEWS periodically and add - changes; it's therefore more important to add your changes to - Misc/NEWS than to this file. - - * This is not a complete list of every single change; completeness - is the purpose of Misc/NEWS. Some changes I consider too small - or esoteric to include. If such a change is added to the text, - I'll just remove it. (This is another reason you shouldn't spend - too much time on writing your addition.) - - * If you want to draw your new text to the attention of the - maintainer, add 'XXX' to the beginning of the paragraph or - section. - - * It's OK to just add a fragmentary note about a change. For - example: "XXX Describe the transmogrify() function added to the - socket module." The maintainer will research the change and - write the necessary text. - - * You can comment out your additions if you like, but it's not - necessary (especially when a final release is some months away). - - * Credit the author of a patch or bugfix. Just the name is - sufficient; the e-mail address isn't necessary. - - * It's helpful to add the bug/patch number as a comment: - - XXX Describe the transmogrify() function added to the socket - module. - (Contributed by P.Y. Developer in :issue:`12345`.) - - This saves the maintainer the effort of going through the Git log - when researching a change. - -:Editor: Raymond Hettinger - -This article explains the new features in Python 3.8, compared to 3.7. -For full details, see the :ref:`changelog `. - -.. testsetup:: - - from datetime import date - from math import cos, radians - from unicodedata import normalize - import re - import math - - -Summary -- Release highlights -============================= - -.. This section singles out the most important changes in Python 3.8. - Brevity is key. - - -.. PEP-sized items next. - - - -New Features -============ - -Assignment expressions ----------------------- - -There is new syntax ``:=`` that assigns values to variables as part of a larger -expression. It is affectionately known as "the walrus operator" due to -its resemblance to `the eyes and tusks of a walrus -`_. - -In this example, the assignment expression helps avoid calling -:func:`len` twice:: - - if (n := len(a)) > 10: - print(f"List is too long ({n} elements, expected <= 10)") - -A similar benefit arises during regular expression matching where -match objects are needed twice, once to test whether a match -occurred and another to extract a subgroup:: - - discount = 0.0 - if (mo := re.search(r'(\d+)% discount', advertisement)): - discount = float(mo.group(1)) / 100.0 - -The operator is also useful with while-loops that compute -a value to test loop termination and then need that same -value again in the body of the loop:: - - # Loop over fixed length blocks - while (block := f.read(256)) != '': - process(block) - -Another motivating use case arises in list comprehensions where -a value computed in a filtering condition is also needed in -the expression body:: - - [clean_name.title() for name in names - if (clean_name := normalize('NFC', name)) in allowed_names] - -Try to limit use of the walrus operator to clean cases that reduce -complexity and improve readability. - -See :pep:`572` for a full description. - -(Contributed by Emily Morehouse in :issue:`35224`.) - - -Positional-only parameters --------------------------- - -There is a new function parameter syntax ``/`` to indicate that some -function parameters must be specified positionally and cannot be used as -keyword arguments. This is the same notation shown by ``help()`` for C -functions annotated with Larry Hastings' `Argument Clinic -`_ tool. - -In the following example, parameters *a* and *b* are positional-only, -while *c* or *d* can be positional or keyword, and *e* or *f* are -required to be keywords:: - - def f(a, b, /, c, d, *, e, f): - print(a, b, c, d, e, f) - -The following is a valid call:: - - f(10, 20, 30, d=40, e=50, f=60) - -However, these are invalid calls:: - - f(10, b=20, c=30, d=40, e=50, f=60) # b cannot be a keyword argument - f(10, 20, 30, 40, 50, f=60) # e must be a keyword argument - -One use case for this notation is that it allows pure Python functions -to fully emulate behaviors of existing C coded functions. For example, -the built-in :func:`pow` function does not accept keyword arguments:: - - def pow(x, y, z=None, /): - "Emulate the built in pow() function" - r = x ** y - return r if z is None else r%z - -Another use case is to preclude keyword arguments when the parameter -name is not helpful. For example, the builtin :func:`len` function has -the signature ``len(obj, /)``. This precludes awkward calls such as:: - - len(obj='hello') # The "obj" keyword argument impairs readability - -A further benefit of marking a parameter as positional-only is that it -allows the parameter name to be changed in the future without risk of -breaking client code. For example, in the :mod:`statistics` module, the -parameter name *dist* may be changed in the future. This was made -possible with the following function specification:: - - def quantiles(dist, /, *, n=4, method='exclusive') - ... - -Since the parameters to the left of ``/`` are not exposed as possible -keywords, the parameters names remain available for use in ``**kwargs``:: - - >>> def f(a, b, /, **kwargs): - ... print(a, b, kwargs) - ... - >>> f(10, 20, a=1, b=2, c=3) # a and b are used in two ways - 10 20 {'a': 1, 'b': 2, 'c': 3} - -This greatly simplifies the implementation of functions and methods -that need to accept arbitrary keyword arguments. For example, here -is an excerpt from code in the :mod:`collections` module:: - - class Counter(dict): - - def __init__(self, iterable=None, /, **kwds): - # Note "iterable" is a possible keyword argument - -See :pep:`570` for a full description. - -(Contributed by Pablo Galindo in :issue:`36540`.) - -.. TODO: Pablo will sprint on docs at PyCon US 2019. - - -Parallel filesystem cache for compiled bytecode files ------------------------------------------------------ - -The new :envvar:`PYTHONPYCACHEPREFIX` setting (also available as -:option:`-X` ``pycache_prefix``) configures the implicit bytecode -cache to use a separate parallel filesystem tree, rather than -the default ``__pycache__`` subdirectories within each source -directory. - -The location of the cache is reported in :data:`sys.pycache_prefix` -(:const:`None` indicates the default location in ``__pycache__`` -subdirectories). - -(Contributed by Carl Meyer in :issue:`33499`.) - - -Debug build uses the same ABI as release build ------------------------------------------------ - -Python now uses the same ABI whether it's built in release or debug mode. On -Unix, when Python is built in debug mode, it is now possible to load C -extensions built in release mode and C extensions built using the stable ABI. - -Release builds and debug builds are now ABI compatible: defining the -``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which -introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which -adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS` -environment variable, can be set using the new ``./configure --with-trace-refs`` -build option. -(Contributed by Victor Stinner in :issue:`36465`.) - -On Unix, C extensions are no longer linked to libpython except on Android -and Cygwin. -It is now possible -for a statically linked Python to load a C extension built using a shared -library Python. -(Contributed by Victor Stinner in :issue:`21536`.) - -On Unix, when Python is built in debug mode, import now also looks for C -extensions compiled in release mode and for C extensions compiled with the -stable ABI. -(Contributed by Victor Stinner in :issue:`36722`.) - -To embed Python into an application, a new ``--embed`` option must be passed to -``python3-config --libs --embed`` to get ``-lpython3.8`` (link the application -to libpython). To support both 3.8 and older, try ``python3-config --libs ---embed`` first and fallback to ``python3-config --libs`` (without ``--embed``) -if the previous command fails. - -Add a pkg-config ``python-3.8-embed`` module to embed Python into an -application: ``pkg-config python-3.8-embed --libs`` includes ``-lpython3.8``. -To support both 3.8 and older, try ``pkg-config python-X.Y-embed --libs`` first -and fallback to ``pkg-config python-X.Y --libs`` (without ``--embed``) if the -previous command fails (replace ``X.Y`` with the Python version). - -On the other hand, ``pkg-config python3.8 --libs`` no longer contains -``-lpython3.8``. C extensions must not be linked to libpython (except on -Android and Cygwin, whose cases are handled by the script); -this change is backward incompatible on purpose. -(Contributed by Victor Stinner in :issue:`36721`.) - - -f-strings support ``=`` for self-documenting expressions and debugging ----------------------------------------------------------------------- - -Added an ``=`` specifier to :term:`f-string`\s. An f-string such as -``f'{expr=}'`` will expand to the text of the expression, an equal sign, -then the representation of the evaluated expression. For example: - - >>> user = 'eric_idle' - >>> member_since = date(1975, 7, 31) - >>> f'{user=} {member_since=}' - "user='eric_idle' member_since=datetime.date(1975, 7, 31)" - -The usual :ref:`f-string format specifiers ` allow more -control over how the result of the expression is displayed:: - - >>> delta = date.today() - member_since - >>> f'{user=!s} {delta.days=:,d}' - 'user=eric_idle delta.days=16,075' - -The ``=`` specifier will display the whole expression so that -calculations can be shown:: - - >>> print(f'{theta=} {cos(radians(theta))=:.3f}') - theta=30 cos(radians(theta))=0.866 - -(Contributed by Eric V. Smith and Larry Hastings in :issue:`36817`.) - - -PEP 578: Python Runtime Audit Hooks ------------------------------------ - -The PEP adds an Audit Hook and Verified Open Hook. Both are available from -Python and native code, allowing applications and frameworks written in pure -Python code to take advantage of extra notifications, while also allowing -embedders or system administrators to deploy builds of Python where auditing is -always enabled. - -See :pep:`578` for full details. - - -PEP 587: Python Initialization Configuration --------------------------------------------- - -The :pep:`587` adds a new C API to configure the Python Initialization -providing finer control on the whole configuration and better error reporting. - -New structures: - -* :c:type:`PyConfig` -* :c:type:`PyPreConfig` -* :c:type:`PyStatus` -* :c:type:`PyWideStringList` - -New functions: - -* :c:func:`PyConfig_Clear` -* :c:func:`PyConfig_InitIsolatedConfig` -* :c:func:`PyConfig_InitPythonConfig` -* :c:func:`PyConfig_Read` -* :c:func:`PyConfig_SetArgv` -* :c:func:`PyConfig_SetBytesArgv` -* :c:func:`PyConfig_SetBytesString` -* :c:func:`PyConfig_SetString` -* :c:func:`PyPreConfig_InitIsolatedConfig` -* :c:func:`PyPreConfig_InitPythonConfig` -* :c:func:`PyStatus_Error` -* :c:func:`PyStatus_Exception` -* :c:func:`PyStatus_Exit` -* :c:func:`PyStatus_IsError` -* :c:func:`PyStatus_IsExit` -* :c:func:`PyStatus_NoMemory` -* :c:func:`PyStatus_Ok` -* :c:func:`PyWideStringList_Append` -* :c:func:`PyWideStringList_Insert` -* :c:func:`Py_BytesMain` -* :c:func:`Py_ExitStatusException` -* :c:func:`Py_InitializeFromConfig` -* :c:func:`Py_PreInitialize` -* :c:func:`Py_PreInitializeFromArgs` -* :c:func:`Py_PreInitializeFromBytesArgs` -* :c:func:`Py_RunMain` - -This PEP also adds ``_PyRuntimeState.preconfig`` (:c:type:`PyPreConfig` type) -and ``PyInterpreterState.config`` (:c:type:`PyConfig` type) fields to these -internal structures. ``PyInterpreterState.config`` becomes the new -reference configuration, replacing global configuration variables and -other private variables. - -See :ref:`Python Initialization Configuration ` for the -documentation. - -See :pep:`587` for a full description. - -(Contributed by Victor Stinner in :issue:`36763`.) - - -PEP 590: Vectorcall: a fast calling protocol for CPython --------------------------------------------------------- - -:ref:`vectorcall` is added to the Python/C API. -It is meant to formalize existing optimizations which were already done -for various classes. -Any static type implementing a callable can use this protocol. - -This is currently provisional. -The aim is to make it fully public in Python 3.9. - -See :pep:`590` for a full description. - -(Contributed by Jeroen Demeyer, Mark Shannon and Petr Viktorin in :issue:`36974`.) - - -Pickle protocol 5 with out-of-band data buffers ------------------------------------------------ - -When :mod:`pickle` is used to transfer large data between Python processes -in order to take advantage of multi-core or multi-machine processing, -it is important to optimize the transfer by reducing memory copies, and -possibly by applying custom techniques such as data-dependent compression. - -The :mod:`pickle` protocol 5 introduces support for out-of-band buffers -where :pep:`3118`-compatible data can be transmitted separately from the -main pickle stream, at the discretion of the communication layer. - -See :pep:`574` for a full description. - -(Contributed by Antoine Pitrou in :issue:`36785`.) - - -Other Language Changes -====================== - -* A :keyword:`continue` statement was illegal in the :keyword:`finally` clause - due to a problem with the implementation. In Python 3.8 this restriction - was lifted. - (Contributed by Serhiy Storchaka in :issue:`32489`.) - -* The :class:`bool`, :class:`int`, and :class:`fractions.Fraction` types - now have an :meth:`~int.as_integer_ratio` method like that found in - :class:`float` and :class:`decimal.Decimal`. This minor API extension - makes it possible to write ``numerator, denominator = - x.as_integer_ratio()`` and have it work across multiple numeric types. - (Contributed by Lisa Roach in :issue:`33073` and Raymond Hettinger in - :issue:`37819`.) - -* Constructors of :class:`int`, :class:`float` and :class:`complex` will now - use the :meth:`~object.__index__` special method, if available and the - corresponding method :meth:`~object.__int__`, :meth:`~object.__float__` - or :meth:`~object.__complex__` is not available. - (Contributed by Serhiy Storchaka in :issue:`20092`.) - -* Added support of ``\N{name}`` escapes in :mod:`regular expressions `:: - - >>> notice = 'Copyright © 2019' - >>> copyright_year_pattern = re.compile(r'\N{copyright sign}\s*(\d{4})') - >>> int(copyright_year_pattern.search(notice).group(1)) - 2019 - - (Contributed by Jonathan Eunice and Serhiy Storchaka in :issue:`30688`.) - -* Dict and dictviews are now iterable in reversed insertion order using - :func:`reversed`. (Contributed by Rémi Lapeyre in :issue:`33462`.) - -* The syntax allowed for keyword names in function calls was further - restricted. In particular, ``f((keyword)=arg)`` is no longer allowed. It was - never intended to permit more than a bare name on the left-hand side of a - keyword argument assignment term. - (Contributed by Benjamin Peterson in :issue:`34641`.) - -* Generalized iterable unpacking in :keyword:`yield` and - :keyword:`return` statements no longer requires enclosing parentheses. - This brings the *yield* and *return* syntax into better agreement with - normal assignment syntax:: - - >>> def parse(family): - lastname, *members = family.split() - return lastname.upper(), *members - - >>> parse('simpsons homer marge bart lisa sally') - ('SIMPSONS', 'homer', 'marge', 'bart', 'lisa', 'sally') - - (Contributed by David Cuthbert and Jordan Chapman in :issue:`32117`.) - -* When a comma is missed in code such as ``[(10, 20) (30, 40)]``, the - compiler displays a :exc:`SyntaxWarning` with a helpful suggestion. - This improves on just having a :exc:`TypeError` indicating that the - first tuple was not callable. (Contributed by Serhiy Storchaka in - :issue:`15248`.) - -* Arithmetic operations between subclasses of :class:`datetime.date` or - :class:`datetime.datetime` and :class:`datetime.timedelta` objects now return - an instance of the subclass, rather than the base class. This also affects - the return type of operations whose implementation (directly or indirectly) - uses :class:`datetime.timedelta` arithmetic, such as - :meth:`~datetime.datetime.astimezone`. - (Contributed by Paul Ganssle in :issue:`32417`.) - -* When the Python interpreter is interrupted by Ctrl-C (SIGINT) and the - resulting :exc:`KeyboardInterrupt` exception is not caught, the Python process - now exits via a SIGINT signal or with the correct exit code such that the - calling process can detect that it died due to a Ctrl-C. Shells on POSIX - and Windows use this to properly terminate scripts in interactive sessions. - (Contributed by Google via Gregory P. Smith in :issue:`1054041`.) - -* Some advanced styles of programming require updating the - :class:`types.CodeType` object for an existing function. Since code - objects are immutable, a new code object needs to be created, one - that is modeled on the existing code object. With 19 parameters, - this was somewhat tedious. Now, the new ``replace()`` method makes - it possible to create a clone with a few altered parameters. - - Here's an example that alters the :func:`statistics.mean` function to - prevent the *data* parameter from being used as a keyword argument:: - - >>> from statistics import mean - >>> mean(data=[10, 20, 90]) - 40 - >>> mean.__code__ = mean.__code__.replace(co_posonlyargcount=1) - >>> mean(data=[10, 20, 90]) - Traceback (most recent call last): - ... - TypeError: mean() got some positional-only arguments passed as keyword arguments: 'data' - - (Contributed by Victor Stinner in :issue:`37032`.) - -* For integers, the three-argument form of the :func:`pow` function now - permits the exponent to be negative in the case where the base is - relatively prime to the modulus. It then computes a modular inverse to - the base when the exponent is ``-1``, and a suitable power of that - inverse for other negative exponents. For example, to compute the - `modular multiplicative inverse - `_ of 38 - modulo 137, write:: - - >>> pow(38, -1, 137) - 119 - >>> 119 * 38 % 137 - 1 - - Modular inverses arise in the solution of `linear Diophantine - equations `_. - For example, to find integer solutions for ``4258𝑥 + 147𝑦 = 369``, - first rewrite as ``4258𝑥 ≡ 369 (mod 147)`` then solve: - - >>> x = 369 * pow(4258, -1, 147) % 147 - >>> y = (4258 * x - 369) // -147 - >>> 4258 * x + 147 * y - 369 - - (Contributed by Mark Dickinson in :issue:`36027`.) - -* Dict comprehensions have been synced-up with dict literals so that the - key is computed first and the value second:: - - >>> # Dict comprehension - >>> cast = {input('role? '): input('actor? ') for i in range(2)} - role? King Arthur - actor? Chapman - role? Black Knight - actor? Cleese - - >>> # Dict literal - >>> cast = {input('role? '): input('actor? ')} - role? Sir Robin - actor? Eric Idle - - The guaranteed execution order is helpful with assignment expressions - because variables assigned in the key expression will be available in - the value expression:: - - >>> names = ['Martin von Löwis', 'Łukasz Langa', 'Walter Dörwald'] - >>> {(n := normalize('NFC', name)).casefold() : n for name in names} - {'martin von löwis': 'Martin von Löwis', - 'łukasz langa': 'Łukasz Langa', - 'walter dörwald': 'Walter Dörwald'} - - (Contributed by Jörn Heissler in :issue:`35224`.) - -* The :meth:`object.__reduce__` method can now return a tuple from two to - six elements long. Formerly, five was the limit. The new, optional sixth - element is a callable with a ``(obj, state)`` signature. This allows the - direct control over the state-updating behavior of a specific object. If - not *None*, this callable will have priority over the object's - :meth:`~__setstate__` method. - (Contributed by Pierre Glaser and Olivier Grisel in :issue:`35900`.) - -New Modules -=========== - -* The new :mod:`importlib.metadata` module provides (provisional) support for - reading metadata from third-party packages. For example, it can extract an - installed package's version number, list of entry points, and more:: - - >>> # Note following example requires that the popular "requests" - >>> # package has been installed. - >>> - >>> from importlib.metadata import version, requires, files - >>> version('requests') - '2.22.0' - >>> list(requires('requests')) - ['chardet (<3.1.0,>=3.0.2)'] - >>> list(files('requests'))[:5] - [PackagePath('requests-2.22.0.dist-info/INSTALLER'), - PackagePath('requests-2.22.0.dist-info/LICENSE'), - PackagePath('requests-2.22.0.dist-info/METADATA'), - PackagePath('requests-2.22.0.dist-info/RECORD'), - PackagePath('requests-2.22.0.dist-info/WHEEL')] - - (Contributed by Barry Warsaw and Jason R. Coombs in :issue:`34632`.) - - -Improved Modules -================ - -ast ---- - -AST nodes now have ``end_lineno`` and ``end_col_offset`` attributes, -which give the precise location of the end of the node. (This only -applies to nodes that have ``lineno`` and ``col_offset`` attributes.) - -New function :func:`ast.get_source_segment` returns the source code -for a specific AST node. - -(Contributed by Ivan Levkivskyi in :issue:`33416`.) - -The :func:`ast.parse` function has some new flags: - -* ``type_comments=True`` causes it to return the text of :pep:`484` and - :pep:`526` type comments associated with certain AST nodes; - -* ``mode='func_type'`` can be used to parse :pep:`484` "signature type - comments" (returned for function definition AST nodes); - -* ``feature_version=(3, N)`` allows specifying an earlier Python 3 - version. For example, ``feature_version=(3, 4)`` will treat - :keyword:`async` and :keyword:`await` as non-reserved words. - -(Contributed by Guido van Rossum in :issue:`35766`.) - - -asyncio -------- - -:func:`asyncio.run` has graduated from the provisional to stable API. This -function can be used to execute a :term:`coroutine` and return the result while -automatically managing the event loop. For example:: - - import asyncio - - async def main(): - await asyncio.sleep(0) - return 42 - - asyncio.run(main()) - -This is *roughly* equivalent to:: - - import asyncio - - async def main(): - await asyncio.sleep(0) - return 42 - - loop = asyncio.new_event_loop() - asyncio.set_event_loop(loop) - try: - loop.run_until_complete(main()) - finally: - asyncio.set_event_loop(None) - loop.close() - - -The actual implementation is significantly more complex. Thus, -:func:`asyncio.run` should be the preferred way of running asyncio programs. - -(Contributed by Yury Selivanov in :issue:`32314`.) - -Running ``python -m asyncio`` launches a natively async REPL. This allows rapid -experimentation with code that has a top-level :keyword:`await`. There is no -longer a need to directly call ``asyncio.run()`` which would spawn a new event -loop on every invocation: - -.. code-block:: none - - $ python -m asyncio - asyncio REPL 3.8.0 - Use "await" directly instead of "asyncio.run()". - Type "help", "copyright", "credits" or "license" for more information. - >>> import asyncio - >>> await asyncio.sleep(10, result='hello') - hello - -(Contributed by Yury Selivanov in :issue:`37028`.) - -The exception :class:`asyncio.CancelledError` now inherits from -:class:`BaseException` rather than :class:`Exception`. -(Contributed by Yury Selivanov in :issue:`32528`.) - -On Windows, the default event loop is now :class:`~asyncio.ProactorEventLoop`. -(Contributed by Victor Stinner in :issue:`34687`.) - -:class:`~asyncio.ProactorEventLoop` now also supports UDP. -(Contributed by Adam Meily and Andrew Svetlov in :issue:`29883`.) - -:class:`~asyncio.ProactorEventLoop` can now be interrupted by -:exc:`KeyboardInterrupt` ("CTRL+C"). -(Contributed by Vladimir Matveev in :issue:`23057`.) - -Added :meth:`asyncio.Task.get_coro` for getting the wrapped coroutine -within an :class:`asyncio.Task`. -(Contributed by Alex Grönholm in :issue:`36999`.) - -Asyncio tasks can now be named, either by passing the ``name`` keyword -argument to :func:`asyncio.create_task` or -the :meth:`~asyncio.loop.create_task` event loop method, or by -calling the :meth:`~asyncio.Task.set_name` method on the task object. The -task name is visible in the ``repr()`` output of :class:`asyncio.Task` and -can also be retrieved using the :meth:`~asyncio.Task.get_name` method. -(Contributed by Alex Grönholm in :issue:`34270`.) - -Added support for -`Happy Eyeballs `_ to -:func:`asyncio.loop.create_connection`. To specify the behavior, two new -parameters have been added: *happy_eyeballs_delay* and *interleave*. The Happy -Eyeballs algorithm improves responsiveness in applications that support IPv4 -and IPv6 by attempting to simultaneously connect using both. -(Contributed by twisteroid ambassador in :issue:`33530`.) - - -builtins --------- - -The :func:`compile` built-in has been improved to accept the -``ast.PyCF_ALLOW_TOP_LEVEL_AWAIT`` flag. With this new flag passed, -:func:`compile` will allow top-level ``await``, ``async for`` and ``async with`` -constructs that are usually considered invalid syntax. Asynchronous code object -marked with the ``CO_COROUTINE`` flag may then be returned. -(Contributed by Matthias Bussonnier in :issue:`34616`) - - -collections ------------ - -The :meth:`~collections.somenamedtuple._asdict` method for -:func:`collections.namedtuple` now returns a :class:`dict` instead of a -:class:`collections.OrderedDict`. This works because regular dicts have -guaranteed ordering since Python 3.7. If the extra features of -:class:`OrderedDict` are required, the suggested remediation is to cast the -result to the desired type: ``OrderedDict(nt._asdict())``. -(Contributed by Raymond Hettinger in :issue:`35864`.) - - -cProfile --------- - -The :class:`cProfile.Profile ` class can now be used as a context manager. -Profile a block of code by running:: - - import cProfile - - with cProfile.Profile() as profiler: - # code to be profiled - ... - -(Contributed by Scott Sanderson in :issue:`29235`.) - - -csv ---- - -The :class:`csv.DictReader` now returns instances of :class:`dict` instead of -a :class:`collections.OrderedDict`. The tool is now faster and uses less -memory while still preserving the field order. -(Contributed by Michael Selik in :issue:`34003`.) - - -curses -------- - -Added a new variable holding structured version information for the -underlying ncurses library: :data:`~curses.ncurses_version`. -(Contributed by Serhiy Storchaka in :issue:`31680`.) - - -ctypes ------- - -On Windows, :class:`~ctypes.CDLL` and subclasses now accept a *winmode* parameter -to specify flags for the underlying ``LoadLibraryEx`` call. The default flags are -set to only load DLL dependencies from trusted locations, including the path -where the DLL is stored (if a full or partial path is used to load the initial -DLL) and paths added by :func:`~os.add_dll_directory`. -(Contributed by Steve Dower in :issue:`36085`.) - - -datetime --------- - -Added new alternate constructors :meth:`datetime.date.fromisocalendar` and -:meth:`datetime.datetime.fromisocalendar`, which construct :class:`date` and -:class:`datetime` objects respectively from ISO year, week number, and weekday; -these are the inverse of each class's ``isocalendar`` method. -(Contributed by Paul Ganssle in :issue:`36004`.) - - -functools ---------- - -:func:`functools.lru_cache` can now be used as a straight decorator rather -than as a function returning a decorator. So both of these are now supported:: - - @lru_cache - def f(x): - ... - - @lru_cache(maxsize=256) - def f(x): - ... - -(Contributed by Raymond Hettinger in :issue:`36772`.) - -Added a new :func:`functools.cached_property` decorator, for computed properties -cached for the life of the instance. :: - - import functools - import statistics - - class Dataset: - def __init__(self, sequence_of_numbers): - self.data = sequence_of_numbers - - @functools.cached_property - def variance(self): - return statistics.variance(self.data) - -(Contributed by Carl Meyer in :issue:`21145`) - - -Added a new :func:`functools.singledispatchmethod` decorator that converts -methods into :term:`generic functions ` using -:term:`single dispatch`:: - - from functools import singledispatchmethod - from contextlib import suppress - - class TaskManager: - - def __init__(self, tasks): - self.tasks = list(tasks) - - @singledispatchmethod - def discard(self, value): - with suppress(ValueError): - self.tasks.remove(value) - - @discard.register(list) - def _(self, tasks): - targets = set(tasks) - self.tasks = [x for x in self.tasks if x not in targets] - -(Contributed by Ethan Smith in :issue:`32380`) - -gc --- - -:func:`~gc.get_objects` can now receive an optional *generation* parameter -indicating a generation to get objects from. -(Contributed by Pablo Galindo in :issue:`36016`.) - - -gettext -------- - -Added :func:`~gettext.pgettext` and its variants. -(Contributed by Franz Glasner, Éric Araujo, and Cheryl Sabella in :issue:`2504`.) - - -gzip ----- - -Added the *mtime* parameter to :func:`gzip.compress` for reproducible output. -(Contributed by Guo Ci Teo in :issue:`34898`.) - -A :exc:`~gzip.BadGzipFile` exception is now raised instead of :exc:`OSError` -for certain types of invalid or corrupt gzip files. -(Contributed by Filip Gruszczyński, Michele Orrù, and Zackery Spytz in -:issue:`6584`.) - - -IDLE and idlelib ----------------- - -Output over N lines (50 by default) is squeezed down to a button. -N can be changed in the PyShell section of the General page of the -Settings dialog. Fewer, but possibly extra long, lines can be squeezed by -right clicking on the output. Squeezed output can be expanded in place -by double-clicking the button or into the clipboard or a separate window -by right-clicking the button. (Contributed by Tal Einat in :issue:`1529353`.) - -Add "Run Customized" to the Run menu to run a module with customized -settings. Any command line arguments entered are added to sys.argv. -They also re-appear in the box for the next customized run. One can also -suppress the normal Shell main module restart. (Contributed by Cheryl -Sabella, Terry Jan Reedy, and others in :issue:`5680` and :issue:`37627`.) - -Added optional line numbers for IDLE editor windows. Windows -open without line numbers unless set otherwise in the General -tab of the configuration dialog. Line numbers for an existing -window are shown and hidden in the Options menu. -(Contributed by Tal Einat and Saimadhav Heblikar in :issue:`17535`.) - -OS native encoding is now used for converting between Python strings and Tcl -objects. This allows IDLE to work with emoji and other non-BMP characters. -These characters can be displayed or copied and pasted to or from the -clipboard. Converting strings from Tcl to Python and back now never fails. -(Many people worked on this for eight years but the problem was finally -solved by Serhiy Storchaka in :issue:`13153`.) - -The changes above have been backported to 3.7 maintenance releases. - - -inspect -------- - -The :func:`inspect.getdoc` function can now find docstrings for ``__slots__`` -if that attribute is a :class:`dict` where the values are docstrings. -This provides documentation options similar to what we already have -for :func:`property`, :func:`classmethod`, and :func:`staticmethod`:: - - class AudioClip: - __slots__ = {'bit_rate': 'expressed in kilohertz to one decimal place', - 'duration': 'in seconds, rounded up to an integer'} - def __init__(self, bit_rate, duration): - self.bit_rate = round(bit_rate / 1000.0, 1) - self.duration = ceil(duration) - -(Contributed by Raymond Hettinger in :issue:`36326`.) - - -io --- - -In development mode (:option:`-X` ``env``) and in debug build, the -:class:`io.IOBase` finalizer now logs the exception if the ``close()`` method -fails. The exception is ignored silently by default in release build. -(Contributed by Victor Stinner in :issue:`18748`.) - - -itertools ---------- - -The :func:`itertools.accumulate` function added an option *initial* keyword -argument to specify an initial value:: - - >>> from itertools import accumulate - >>> list(accumulate([10, 5, 30, 15], initial=1000)) - [1000, 1010, 1015, 1045, 1060] - -(Contributed by Lisa Roach in :issue:`34659`.) - - -json.tool ---------- - -Add option ``--json-lines`` to parse every input line as a separate JSON object. -(Contributed by Weipeng Hong in :issue:`31553`.) - - -logging -------- - -Added a *force* keyword argument to :func:`logging.basicConfig()` -When set to true, any existing handlers attached -to the root logger are removed and closed before carrying out the -configuration specified by the other arguments. - -This solves a long-standing problem. Once a logger or *basicConfig()* had -been called, subsequent calls to *basicConfig()* were silently ignored. -This made it difficult to update, experiment with, or teach the various -logging configuration options using the interactive prompt or a Jupyter -notebook. - -(Suggested by Raymond Hettinger, implemented by Dong-hee Na, and -reviewed by Vinay Sajip in :issue:`33897`.) - - -math ----- - -Added new function :func:`math.dist` for computing Euclidean distance -between two points. (Contributed by Raymond Hettinger in :issue:`33089`.) - -Expanded the :func:`math.hypot` function to handle multiple dimensions. -Formerly, it only supported the 2-D case. -(Contributed by Raymond Hettinger in :issue:`33089`.) - -Added new function, :func:`math.prod`, as analogous function to :func:`sum` -that returns the product of a 'start' value (default: 1) times an iterable of -numbers:: - - >>> prior = 0.8 - >>> likelihoods = [0.625, 0.84, 0.30] - >>> math.prod(likelihoods, start=prior) - 0.126 - -(Contributed by Pablo Galindo in :issue:`35606`.) - -Added two new combinatoric functions :func:`math.perm` and :func:`math.comb`:: - - >>> math.perm(10, 3) # Permutations of 10 things taken 3 at a time - 720 - >>> math.comb(10, 3) # Combinations of 10 things taken 3 at a time - 120 - -(Contributed by Yash Aggarwal, Keller Fuchs, Serhiy Storchaka, and Raymond -Hettinger in :issue:`37128`, :issue:`37178`, and :issue:`35431`.) - -Added a new function :func:`math.isqrt` for computing accurate integer square -roots without conversion to floating point. The new function supports -arbitrarily large integers. It is faster than ``floor(sqrt(n))`` but slower -than :func:`math.sqrt`:: - - >>> r = 650320427 - >>> s = r ** 2 - >>> isqrt(s - 1) # correct - 650320426 - >>> floor(sqrt(s - 1)) # incorrect - 650320427 - -(Contributed by Mark Dickinson in :issue:`36887`.) - -The function :func:`math.factorial` no longer accepts arguments that are not -int-like. (Contributed by Pablo Galindo in :issue:`33083`.) - - -mmap ----- - -The :class:`mmap.mmap` class now has an :meth:`~mmap.mmap.madvise` method to -access the ``madvise()`` system call. -(Contributed by Zackery Spytz in :issue:`32941`.) - - -multiprocessing ---------------- - -Added new :mod:`multiprocessing.shared_memory` module. -(Contributed by Davin Potts in :issue:`35813`.) - -On macOS, the *spawn* start method is now used by default. -(Contributed by Victor Stinner in :issue:`33725`.) - - -os --- - -Added new function :func:`~os.add_dll_directory` on Windows for providing -additional search paths for native dependencies when importing extension -modules or loading DLLs using :mod:`ctypes`. -(Contributed by Steve Dower in :issue:`36085`.) - -A new :func:`os.memfd_create` function was added to wrap the -``memfd_create()`` syscall. -(Contributed by Zackery Spytz and Christian Heimes in :issue:`26836`.) - -On Windows, much of the manual logic for handling reparse points (including -symlinks and directory junctions) has been delegated to the operating system. -Specifically, :func:`os.stat` will now traverse anything supported by the -operating system, while :func:`os.lstat` will only open reparse points that -identify as "name surrogates" while others are opened as for :func:`os.stat`. -In all cases, :attr:`stat_result.st_mode` will only have ``S_IFLNK`` set for -symbolic links and not other kinds of reparse points. To identify other kinds -of reparse point, check the new :attr:`stat_result.st_reparse_tag` attribute. - -On Windows, :func:`os.readlink` is now able to read directory junctions. Note -that :func:`~os.path.islink` will return ``False`` for directory junctions, -and so code that checks ``islink`` first will continue to treat junctions as -directories, while code that handles errors from :func:`os.readlink` may now -treat junctions as links. - -(Contributed by Steve Dower in :issue:`37834`.) - - -os.path -------- - -:mod:`os.path` functions that return a boolean result like -:func:`~os.path.exists`, :func:`~os.path.lexists`, :func:`~os.path.isdir`, -:func:`~os.path.isfile`, :func:`~os.path.islink`, and :func:`~os.path.ismount` -now return ``False`` instead of raising :exc:`ValueError` or its subclasses -:exc:`UnicodeEncodeError` and :exc:`UnicodeDecodeError` for paths that contain -characters or bytes unrepresentable at the OS level. -(Contributed by Serhiy Storchaka in :issue:`33721`.) - -:func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE` -environment variable and does not use :envvar:`HOME`, which is not normally set -for regular user accounts. -(Contributed by Anthony Sottile in :issue:`36264`.) - -:func:`~os.path.isdir` on Windows no longer returns ``True`` for a link to a -non-existent directory. - -:func:`~os.path.realpath` on Windows now resolves reparse points, including -symlinks and directory junctions. - -(Contributed by Steve Dower in :issue:`37834`.) - - -pathlib -------- - -:mod:`pathlib.Path` methods that return a boolean result like -:meth:`~pathlib.Path.exists()`, :meth:`~pathlib.Path.is_dir()`, -:meth:`~pathlib.Path.is_file()`, :meth:`~pathlib.Path.is_mount()`, -:meth:`~pathlib.Path.is_symlink()`, :meth:`~pathlib.Path.is_block_device()`, -:meth:`~pathlib.Path.is_char_device()`, :meth:`~pathlib.Path.is_fifo()`, -:meth:`~pathlib.Path.is_socket()` now return ``False`` instead of raising -:exc:`ValueError` or its subclass :exc:`UnicodeEncodeError` for paths that -contain characters unrepresentable at the OS level. -(Contributed by Serhiy Storchaka in :issue:`33721`.) - -Added :meth:`pathlib.Path.link_to()` which creates a hard link pointing -to a path. -(Contributed by Joannah Nanjekye in :issue:`26978`) - - -pickle ------- - -:mod:`pickle` extensions subclassing the C-optimized :class:`~pickle.Pickler` -can now override the pickling logic of functions and classes by defining the -special :meth:`~pickle.Pickler.reducer_override` method. -(Contributed by Pierre Glaser and Olivier Grisel in :issue:`35900`.) - - -plistlib --------- - -Added new :class:`plistlib.UID` and enabled support for reading and writing -NSKeyedArchiver-encoded binary plists. -(Contributed by Jon Janzen in :issue:`26707`.) - - -pprint ------- - -The :mod:`pprint` module added a *sort_dicts* parameter to several functions. -By default, those functions continue to sort dictionaries before rendering or -printing. However, if *sort_dicts* is set to false, the dictionaries retain -the order that keys were inserted. This can be useful for comparison to JSON -inputs during debugging. - -In addition, there is a convenience new function, :func:`pprint.pp` that is -like :func:`pprint.pprint` but with *sort_dicts* defaulting to ``False``:: - - >>> from pprint import pprint, pp - >>> d = dict(source='input.txt', operation='filter', destination='output.txt') - >>> pp(d, width=40) # Original order - {'source': 'input.txt', - 'operation': 'filter', - 'destination': 'output.txt'} - >>> pprint(d, width=40) # Keys sorted alphabetically - {'destination': 'output.txt', - 'operation': 'filter', - 'source': 'input.txt'} - -(Contributed by Rémi Lapeyre in :issue:`30670`.) - - -py_compile ----------- - -:func:`py_compile.compile` now supports silent mode. -(Contributed by Joannah Nanjekye in :issue:`22640`.) - - -shlex ------ - -The new :func:`shlex.join` function acts as the inverse of :func:`shlex.split`. -(Contributed by Bo Bayles in :issue:`32102`.) - - -shutil ------- - -:func:`shutil.copytree` now accepts a new ``dirs_exist_ok`` keyword argument. -(Contributed by Josh Bronson in :issue:`20849`.) - -:func:`shutil.make_archive` now defaults to the modern pax (POSIX.1-2001) -format for new archives to improve portability and standards conformance, -inherited from the corresponding change to the :mod:`tarfile` module. -(Contributed by C.A.M. Gerlach in :issue:`30661`.) - -:func:`shutil.rmtree` on Windows now removes directory junctions without -recursively removing their contents first. -(Contributed by Steve Dower in :issue:`37834`.) - - -socket ------- - -Added :meth:`~socket.create_server()` and :meth:`~socket.has_dualstack_ipv6()` -convenience functions to automate the necessary tasks usually involved when -creating a server socket, including accepting both IPv4 and IPv6 connections -on the same socket. (Contributed by Giampaolo Rodolà in :issue:`17561`.) - -The :func:`socket.if_nameindex()`, :func:`socket.if_nametoindex()`, and -:func:`socket.if_indextoname()` functions have been implemented on Windows. -(Contributed by Zackery Spytz in :issue:`37007`.) - - -ssl ---- - -Added :attr:`~ssl.SSLContext.post_handshake_auth` to enable and -:meth:`~ssl.SSLSocket.verify_client_post_handshake` to initiate TLS 1.3 -post-handshake authentication. -(Contributed by Christian Heimes in :issue:`34670`.) - - -statistics ----------- - -Added :func:`statistics.fmean` as a faster, floating point variant of -:func:`statistics.mean()`. (Contributed by Raymond Hettinger and -Steven D'Aprano in :issue:`35904`.) - -Added :func:`statistics.geometric_mean()` -(Contributed by Raymond Hettinger in :issue:`27181`.) - -Added :func:`statistics.multimode` that returns a list of the most -common values. (Contributed by Raymond Hettinger in :issue:`35892`.) - -Added :func:`statistics.quantiles` that divides data or a distribution -in to equiprobable intervals (e.g. quartiles, deciles, or percentiles). -(Contributed by Raymond Hettinger in :issue:`36546`.) - -Added :class:`statistics.NormalDist`, a tool for creating -and manipulating normal distributions of a random variable. -(Contributed by Raymond Hettinger in :issue:`36018`.) - -:: - - >>> temperature_feb = NormalDist.from_samples([4, 12, -3, 2, 7, 14]) - >>> temperature_feb.mean - 6.0 - >>> temperature_feb.stdev - 6.356099432828281 - - >>> temperature_feb.cdf(3) # Chance of being under 3 degrees - 0.3184678262814532 - >>> # Relative chance of being 7 degrees versus 10 degrees - >>> temperature_feb.pdf(7) / temperature_feb.pdf(10) - 1.2039930378537762 - - >>> el_niño = NormalDist(4, 2.5) - >>> temperature_feb += el_niño # Add in a climate effect - >>> temperature_feb - NormalDist(mu=10.0, sigma=6.830080526611674) - - >>> temperature_feb * (9/5) + 32 # Convert to Fahrenheit - NormalDist(mu=50.0, sigma=12.294144947901014) - >>> temperature_feb.samples(3) # Generate random samples - [7.672102882379219, 12.000027119750287, 4.647488369766392] - - -sys ---- - -Add new :func:`sys.unraisablehook` function which can be overridden to control -how "unraisable exceptions" are handled. It is called when an exception has -occurred but there is no way for Python to handle it. For example, when a -destructor raises an exception or during garbage collection -(:func:`gc.collect`). -(Contributed by Victor Stinner in :issue:`36829`.) - - -tarfile -------- - -The :mod:`tarfile` module now defaults to the modern pax (POSIX.1-2001) -format for new archives, instead of the previous GNU-specific one. -This improves cross-platform portability with a consistent encoding (UTF-8) -in a standardized and extensible format, and offers several other benefits. -(Contributed by C.A.M. Gerlach in :issue:`36268`.) - - -threading ---------- - -Add a new :func:`threading.excepthook` function which handles uncaught -:meth:`threading.Thread.run` exception. It can be overridden to control how -uncaught :meth:`threading.Thread.run` exceptions are handled. -(Contributed by Victor Stinner in :issue:`1230540`.) - -Add a new :func:`threading.get_native_id` function and -a :data:`~threading.Thread.native_id` -attribute to the :class:`threading.Thread` class. These return the native -integral Thread ID of the current thread assigned by the kernel. -This feature is only available on certain platforms, see -:func:`get_native_id ` for more information. -(Contributed by Jake Tesler in :issue:`36084`.) - - -tokenize --------- - -The :mod:`tokenize` module now implicitly emits a ``NEWLINE`` token when -provided with input that does not have a trailing new line. This behavior -now matches what the C tokenizer does internally. -(Contributed by Ammar Askar in :issue:`33899`.) - - -tkinter -------- - -Added methods :meth:`~tkinter.Spinbox.selection_from`, -:meth:`~tkinter.Spinbox.selection_present`, -:meth:`~tkinter.Spinbox.selection_range` and -:meth:`~tkinter.Spinbox.selection_to` -in the :class:`tkinter.Spinbox` class. -(Contributed by Juliette Monsel in :issue:`34829`.) - -Added method :meth:`~tkinter.Canvas.moveto` -in the :class:`tkinter.Canvas` class. -(Contributed by Juliette Monsel in :issue:`23831`.) - -The :class:`tkinter.PhotoImage` class now has -:meth:`~tkinter.PhotoImage.transparency_get` and -:meth:`~tkinter.PhotoImage.transparency_set` methods. (Contributed by -Zackery Spytz in :issue:`25451`.) - - -time ----- - -Added new clock :data:`~time.CLOCK_UPTIME_RAW` for macOS 10.12. -(Contributed by Joannah Nanjekye in :issue:`35702`.) - - -typing ------- - -The :mod:`typing` module incorporates several new features: - -* A dictionary type with per-key types. See :pep:`589` and - :class:`typing.TypedDict`. - TypedDict uses only string keys. By default, every key is required - to be present. Specify "total=False" to allow keys to be optional:: - - class Location(TypedDict, total=False): - lat_long: tuple - grid_square: str - xy_coordinate: tuple - -* Literal types. See :pep:`586` and :class:`typing.Literal`. - Literal types indicate that a parameter or return value - is constrained to one or more specific literal values:: - - def get_status(port: int) -> Literal['connected', 'disconnected']: - ... - -* "Final" variables, functions, methods and classes. See :pep:`591`, - :class:`typing.Final` and :func:`typing.final`. - The final qualifier instructs a static type checker to restrict - subclassing, overriding, or reassignment:: - - pi: Final[float] = 3.1415926536 - -* Protocol definitions. See :pep:`544`, :class:`typing.Protocol` and - :func:`typing.runtime_checkable`. Simple ABCs like - :class:`typing.SupportsInt` are now ``Protocol`` subclasses. - -* New protocol class :class:`typing.SupportsIndex`. - -* New functions :func:`typing.get_origin` and :func:`typing.get_args`. - - -unicodedata ------------ - -The :mod:`unicodedata` module has been upgraded to use the `Unicode 12.1.0 -`_ release. - -New function :func:`~unicodedata.is_normalized` can be used to verify a string -is in a specific normal form, often much faster than by actually normalizing -the string. (Contributed by Max Belanger, David Euresti, and Greg Price in -:issue:`32285` and :issue:`37966`). - - -unittest --------- - -Added :class:`~unittest.mock.AsyncMock` to support an asynchronous version of -:class:`~unittest.mock.Mock`. Appropriate new assert functions for testing -have been added as well. -(Contributed by Lisa Roach in :issue:`26467`). - -Added :func:`~unittest.addModuleCleanup()` and -:meth:`~unittest.TestCase.addClassCleanup()` to unittest to support -cleanups for :func:`~unittest.setUpModule()` and -:meth:`~unittest.TestCase.setUpClass()`. -(Contributed by Lisa Roach in :issue:`24412`.) - -Several mock assert functions now also print a list of actual calls upon -failure. (Contributed by Petter Strandmark in :issue:`35047`.) - -:mod:`unittest` module gained support for coroutines to be used as test cases -with :class:`unittest.IsolatedAsyncioTestCase`. -(Contributed by Andrew Svetlov in :issue:`32972`.) - -Example:: - - import unittest - - - class TestRequest(unittest.IsolatedAsyncioTestCase): - - async def asyncSetUp(self): - self.connection = await AsyncConnection() - - async def test_get(self): - response = await self.connection.get("https://example.com") - self.assertEqual(response.status_code, 200) - - async def asyncTearDown(self): - await self.connection.close() - - - if __name__ == "__main__": - unittest.main() - - -venv ----- - -:mod:`venv` now includes an ``Activate.ps1`` script on all platforms for -activating virtual environments under PowerShell Core 6.1. -(Contributed by Brett Cannon in :issue:`32718`.) - - -weakref -------- - -The proxy objects returned by :func:`weakref.proxy` now support the matrix -multiplication operators ``@`` and ``@=`` in addition to the other -numeric operators. (Contributed by Mark Dickinson in :issue:`36669`.) - - -xml ---- - -As mitigation against DTD and external entity retrieval, the -:mod:`xml.dom.minidom` and :mod:`xml.sax` modules no longer process -external entities by default. -(Contributed by Christian Heimes in :issue:`17239`.) - -The ``.find*()`` methods in the :mod:`xml.etree.ElementTree` module -support wildcard searches like ``{*}tag`` which ignores the namespace -and ``{namespace}*`` which returns all tags in the given namespace. -(Contributed by Stefan Behnel in :issue:`28238`.) - -The :mod:`xml.etree.ElementTree` module provides a new function -:func:`–xml.etree.ElementTree.canonicalize()` that implements C14N 2.0. -(Contributed by Stefan Behnel in :issue:`13611`.) - -The target object of :class:`xml.etree.ElementTree.XMLParser` can -receive namespace declaration events through the new callback methods -``start_ns()`` and ``end_ns()``. Additionally, the -:class:`xml.etree.ElementTree.TreeBuilder` target can be configured -to process events about comments and processing instructions to include -them in the generated tree. -(Contributed by Stefan Behnel in :issue:`36676` and :issue:`36673`.) - - -xmlrpc ------- - -:class:`xmlrpc.client.ServerProxy` now supports an optional *headers* keyword -argument for a sequence of HTTP headers to be sent with each request. Among -other things, this makes it possible to upgrade from default basic -authentication to faster session authentication. -(Contributed by Cédric Krier in :issue:`35153`.) - - -Optimizations -============= - -* The :mod:`subprocess` module can now use the :func:`os.posix_spawn` function - in some cases for better performance. Currently, it is only used on macOS - and Linux (using glibc 2.24 or newer) if all these conditions are met: - - * *close_fds* is false; - * *preexec_fn*, *pass_fds*, *cwd* and *start_new_session* parameters - are not set; - * the *executable* path contains a directory. - - (Contributed by Joannah Nanjekye and Victor Stinner in :issue:`35537`.) - -* :func:`shutil.copyfile`, :func:`shutil.copy`, :func:`shutil.copy2`, - :func:`shutil.copytree` and :func:`shutil.move` use platform-specific - "fast-copy" syscalls on Linux and macOS in order to copy the file - more efficiently. - "fast-copy" means that the copying operation occurs within the kernel, - avoiding the use of userspace buffers in Python as in - "``outfd.write(infd.read())``". - On Windows :func:`shutil.copyfile` uses a bigger default buffer size (1 MiB - instead of 16 KiB) and a :func:`memoryview`-based variant of - :func:`shutil.copyfileobj` is used. - The speedup for copying a 512 MiB file within the same partition is about - +26% on Linux, +50% on macOS and +40% on Windows. Also, much less CPU cycles - are consumed. - See :ref:`shutil-platform-dependent-efficient-copy-operations` section. - (Contributed by Giampaolo Rodolà in :issue:`33671`.) - -* :func:`shutil.copytree` uses :func:`os.scandir` function and all copy - functions depending from it use cached :func:`os.stat` values. The speedup - for copying a directory with 8000 files is around +9% on Linux, +20% on - Windows and +30% on a Windows SMB share. Also the number of :func:`os.stat` - syscalls is reduced by 38% making :func:`shutil.copytree` especially faster - on network filesystems. (Contributed by Giampaolo Rodolà in :issue:`33695`.) - -* The default protocol in the :mod:`pickle` module is now Protocol 4, - first introduced in Python 3.4. It offers better performance and smaller - size compared to Protocol 3 available since Python 3.0. - -* Removed one ``Py_ssize_t`` member from ``PyGC_Head``. All GC tracked - objects (e.g. tuple, list, dict) size is reduced 4 or 8 bytes. - (Contributed by Inada Naoki in :issue:`33597`.) - -* :class:`uuid.UUID` now uses ``__slots__`` to reduce its memory footprint. - (Contributed by Wouter Bolsterlee and Tal Einat in :issue:`30977`) - -* Improved performance of :func:`operator.itemgetter` by 33%. Optimized - argument handling and added a fast path for the common case of a single - non-negative integer index into a tuple (which is the typical use case in - the standard library). (Contributed by Raymond Hettinger in - :issue:`35664`.) - -* Sped-up field lookups in :func:`collections.namedtuple`. They are now more - than two times faster, making them the fastest form of instance variable - lookup in Python. (Contributed by Raymond Hettinger, Pablo Galindo, and - Joe Jevnik, Serhiy Storchaka in :issue:`32492`.) - -* The :class:`list` constructor does not overallocate the internal item buffer - if the input iterable has a known length (the input implements ``__len__``). - This makes the created list 12% smaller on average. (Contributed by - Raymond Hettinger and Pablo Galindo in :issue:`33234`.) - -* Doubled the speed of class variable writes. When a non-dunder attribute - was updated, there was an unnecessary call to update slots. - (Contributed by Stefan Behnel, Pablo Galindo Salgado, Raymond Hettinger, - Neil Schemenauer, and Serhiy Storchaka in :issue:`36012`.) - -* Reduced an overhead of converting arguments passed to many builtin functions - and methods. This sped up calling some simple builtin functions and - methods up to 20--50%. (Contributed by Serhiy Storchaka in :issue:`23867`, - :issue:`35582` and :issue:`36127`.) - -* ``LOAD_GLOBAL`` instruction now uses new "per opcode cache" mechanism. - It is about 40% faster now. (Contributed by Yury Selivanov and Inada Naoki in - :issue:`26219`.) - - -Build and C API Changes -======================= - -* Default :data:`sys.abiflags` became an empty string: the ``m`` flag for - pymalloc became useless (builds with and without pymalloc are ABI compatible) - and so has been removed. (Contributed by Victor Stinner in :issue:`36707`.) - - Example of changes: - - * Only ``python3.8`` program is installed, ``python3.8m`` program is gone. - * Only ``python3.8-config`` script is installed, ``python3.8m-config`` script - is gone. - * The ``m`` flag has been removed from the suffix of dynamic library - filenames: extension modules in the standard library as well as those - produced and installed by third-party packages, like those downloaded from - PyPI. On Linux, for example, the Python 3.7 suffix - ``.cpython-37m-x86_64-linux-gnu.so`` became - ``.cpython-38-x86_64-linux-gnu.so`` in Python 3.8. - -* The header files have been reorganized to better separate the different kinds - of APIs: - - * ``Include/*.h`` should be the portable public stable C API. - * ``Include/cpython/*.h`` should be the unstable C API specific to CPython; - public API, with some private API prefixed by ``_Py`` or ``_PY``. - * ``Include/internal/*.h`` is the private internal C API very specific to - CPython. This API comes with no backward compatibility warranty and should - not be used outside CPython. It is only exposed for very specific needs - like debuggers and profiles which has to access to CPython internals - without calling functions. This API is now installed by ``make install``. - - (Contributed by Victor Stinner in :issue:`35134` and :issue:`35081`, - work initiated by Eric Snow in Python 3.7.) - -* Some macros have been converted to static inline functions: parameter types - and return type are well defined, they don't have issues specific to macros, - variables have a local scopes. Examples: - - * :c:func:`Py_INCREF`, :c:func:`Py_DECREF` - * :c:func:`Py_XINCREF`, :c:func:`Py_XDECREF` - * :c:func:`PyObject_INIT`, :c:func:`PyObject_INIT_VAR` - * Private functions: :c:func:`_PyObject_GC_TRACK`, - :c:func:`_PyObject_GC_UNTRACK`, :c:func:`_Py_Dealloc` - - (Contributed by Victor Stinner in :issue:`35059`.) - -* The :c:func:`PyByteArray_Init` and :c:func:`PyByteArray_Fini` functions have - been removed. They did nothing since Python 2.7.4 and Python 3.2.0, were - excluded from the limited API (stable ABI), and were not documented. - (Contributed by Victor Stinner in :issue:`35713`.) - -* The result of :c:func:`PyExceptionClass_Name` is now of type - ``const char *`` rather of ``char *``. - (Contributed by Serhiy Storchaka in :issue:`33818`.) - -* The duality of ``Modules/Setup.dist`` and ``Modules/Setup`` has been - removed. Previously, when updating the CPython source tree, one had - to manually copy ``Modules/Setup.dist`` (inside the source tree) to - ``Modules/Setup`` (inside the build tree) in order to reflect any changes - upstream. This was of a small benefit to packagers at the expense of - a frequent annoyance to developers following CPython development, as - forgetting to copy the file could produce build failures. - - Now the build system always reads from ``Modules/Setup`` inside the source - tree. People who want to customize that file are encouraged to maintain - their changes in a git fork of CPython or as patch files, as they would do - for any other change to the source tree. - - (Contributed by Antoine Pitrou in :issue:`32430`.) - -* Functions that convert Python number to C integer like - :c:func:`PyLong_AsLong` and argument parsing functions like - :c:func:`PyArg_ParseTuple` with integer converting format units like ``'i'`` - will now use the :meth:`~object.__index__` special method instead of - :meth:`~object.__int__`, if available. The deprecation warning will be - emitted for objects with the ``__int__()`` method but without the - ``__index__()`` method (like :class:`~decimal.Decimal` and - :class:`~fractions.Fraction`). :c:func:`PyNumber_Check` will now return - ``1`` for objects implementing ``__index__()``. - :c:func:`PyNumber_Long`, :c:func:`PyNumber_Float` and - :c:func:`PyFloat_AsDouble` also now use the ``__index__()`` method if - available. - (Contributed by Serhiy Storchaka in :issue:`36048` and :issue:`20092`.) - -* Heap-allocated type objects will now increase their reference count - in :c:func:`PyObject_Init` (and its parallel macro ``PyObject_INIT``) - instead of in :c:func:`PyType_GenericAlloc`. Types that modify instance - allocation or deallocation may need to be adjusted. - (Contributed by Eddie Elizondo in :issue:`35810`.) - -* The new function :c:func:`PyCode_NewWithPosOnlyArgs` allows to create - code objects like :c:func:`PyCode_New`, but with an extra *posonlyargcount* - parameter for indicating the number of positional-only arguments. - (Contributed by Pablo Galindo in :issue:`37221`.) - -* :c:func:`Py_SetPath` now sets :data:`sys.executable` to the program full - path (:c:func:`Py_GetProgramFullPath`) rather than to the program name - (:c:func:`Py_GetProgramName`). - (Contributed by Victor Stinner in :issue:`38234`.) - - -Deprecated -========== - -* The distutils ``bdist_wininst`` command is now deprecated, use - ``bdist_wheel`` (wheel packages) instead. - (Contributed by Victor Stinner in :issue:`37481`.) - -* Deprecated methods ``getchildren()`` and ``getiterator()`` in - the :mod:`~xml.etree.ElementTree` module now emit a - :exc:`DeprecationWarning` instead of :exc:`PendingDeprecationWarning`. - They will be removed in Python 3.9. - (Contributed by Serhiy Storchaka in :issue:`29209`.) - -* Passing an object that is not an instance of - :class:`concurrent.futures.ThreadPoolExecutor` to - :meth:`loop.set_default_executor() ` is - deprecated and will be prohibited in Python 3.9. - (Contributed by Elvis Pranskevichus in :issue:`34075`.) - -* The :meth:`__getitem__` methods of :class:`xml.dom.pulldom.DOMEventStream`, - :class:`wsgiref.util.FileWrapper` and :class:`fileinput.FileInput` have been - deprecated. - - Implementations of these methods have been ignoring their *index* parameter, - and returning the next item instead. - (Contributed by Berker Peksag in :issue:`9372`.) - -* The :class:`typing.NamedTuple` class has deprecated the ``_field_types`` - attribute in favor of the ``__annotations__`` attribute which has the same - information. (Contributed by Raymond Hettinger in :issue:`36320`.) - -* :mod:`ast` classes ``Num``, ``Str``, ``Bytes``, ``NameConstant`` and - ``Ellipsis`` are considered deprecated and will be removed in future Python - versions. :class:`~ast.Constant` should be used instead. - (Contributed by Serhiy Storchaka in :issue:`32892`.) - -* :class:`ast.NodeVisitor` methods ``visit_Num()``, ``visit_Str()``, - ``visit_Bytes()``, ``visit_NameConstant()`` and ``visit_Ellipsis()`` are - deprecated now and will not be called in future Python versions. - Add the :meth:`~ast.NodeVisitor.visit_Constant` method to handle all - constant nodes. - (Contributed by Serhiy Storchaka in :issue:`36917`.) - -* The :func:`asyncio.coroutine` :term:`decorator` is deprecated and will be - removed in version 3.10. Instead of ``@asyncio.coroutine``, use - :keyword:`async def` instead. - (Contributed by Andrew Svetlov in :issue:`36921`.) - -* In :mod:`asyncio`, the explicit passing of a *loop* argument has been - deprecated and will be removed in version 3.10 for the following: - :func:`asyncio.sleep`, :func:`asyncio.gather`, :func:`asyncio.shield`, - :func:`asyncio.wait_for`, :func:`asyncio.wait`, :func:`asyncio.as_completed`, - :class:`asyncio.Task`, :class:`asyncio.Lock`, :class:`asyncio.Event`, - :class:`asyncio.Condition`, :class:`asyncio.Semaphore`, - :class:`asyncio.BoundedSemaphore`, :class:`asyncio.Queue`, - :func:`asyncio.create_subprocess_exec`, and - :func:`asyncio.create_subprocess_shell`. - -* The explicit passing of coroutine objects to :func:`asyncio.wait` has been - deprecated and will be removed in version 3.11. - (Contributed by Yury Selivanov in :issue:`34790`.) - -* The following functions and methods are deprecated in the :mod:`gettext` - module: :func:`~gettext.lgettext`, :func:`~gettext.ldgettext`, - :func:`~gettext.lngettext` and :func:`~gettext.ldngettext`. - They return encoded bytes, and it's possible that you will get unexpected - Unicode-related exceptions if there are encoding problems with the - translated strings. It's much better to use alternatives which return - Unicode strings in Python 3. These functions have been broken for a long time. - - Function :func:`~gettext.bind_textdomain_codeset`, methods - :meth:`~gettext.NullTranslations.output_charset` and - :meth:`~gettext.NullTranslations.set_output_charset`, and the *codeset* - parameter of functions :func:`~gettext.translation` and - :func:`~gettext.install` are also deprecated, since they are only used for - for the ``l*gettext()`` functions. - (Contributed by Serhiy Storchaka in :issue:`33710`.) - -* The :meth:`~threading.Thread.isAlive()` method of :class:`threading.Thread` - has been deprecated. - (Contributed by Dong-hee Na in :issue:`35283`.) - -* Many builtin and extension functions that take integer arguments will - now emit a deprecation warning for :class:`~decimal.Decimal`\ s, - :class:`~fractions.Fraction`\ s and any other objects that can be converted - to integers only with a loss (e.g. that have the :meth:`~object.__int__` - method but do not have the :meth:`~object.__index__` method). In future - version they will be errors. - (Contributed by Serhiy Storchaka in :issue:`36048`.) - -* Deprecated passing the following arguments as keyword arguments: - - - *func* in :func:`functools.partialmethod`, :func:`weakref.finalize`, - :meth:`profile.Profile.runcall`, :meth:`cProfile.Profile.runcall`, - :meth:`bdb.Bdb.runcall`, :meth:`trace.Trace.runfunc` and - :func:`curses.wrapper`. - - *function* in :meth:`unittest.TestCase.addCleanup`. - - *fn* in the :meth:`~concurrent.futures.Executor.submit` method of - :class:`concurrent.futures.ThreadPoolExecutor` and - :class:`concurrent.futures.ProcessPoolExecutor`. - - *callback* in :meth:`contextlib.ExitStack.callback`, - :meth:`contextlib.AsyncExitStack.callback` and - :meth:`contextlib.AsyncExitStack.push_async_callback`. - - *c* and *typeid* in the :meth:`~multiprocessing.managers.Server.create` - method of :class:`multiprocessing.managers.Server` and - :class:`multiprocessing.managers.SharedMemoryServer`. - - *obj* in :func:`weakref.finalize`. - - In future releases of Python, they will be :ref:`positional-only - `. - (Contributed by Serhiy Storchaka in :issue:`36492`.) - - -API and Feature Removals -======================== - -The following features and APIs have been removed from Python 3.8: - -* Starting with Python 3.3, importing ABCs from :mod:`collections` was - deprecated, and importing should be done from :mod:`collections.abc`. Being - able to import from collections was marked for removal in 3.8, but has been - delayed to 3.9. (See :issue:`36952`.) - -* The :mod:`macpath` module, deprecated in Python 3.7, has been removed. - (Contributed by Victor Stinner in :issue:`35471`.) - -* The function :func:`platform.popen` has been removed, after having been - deprecated since Python 3.3: use :func:`os.popen` instead. - (Contributed by Victor Stinner in :issue:`35345`.) - -* The function :func:`time.clock` has been removed, after having been - deprecated since Python 3.3: use :func:`time.perf_counter` or - :func:`time.process_time` instead, depending - on your requirements, to have well-defined behavior. - (Contributed by Matthias Bussonnier in :issue:`36895`.) - -* The ``pyvenv`` script has been removed in favor of ``python3.8 -m venv`` - to help eliminate confusion as to what Python interpreter the ``pyvenv`` - script is tied to. (Contributed by Brett Cannon in :issue:`25427`.) - -* ``parse_qs``, ``parse_qsl``, and ``escape`` are removed from the :mod:`cgi` - module. They are deprecated in Python 3.2 or older. They should be imported - from the ``urllib.parse`` and ``html`` modules instead. - -* ``filemode`` function is removed from the :mod:`tarfile` module. - It is not documented and deprecated since Python 3.3. - -* The :class:`~xml.etree.ElementTree.XMLParser` constructor no longer accepts - the *html* argument. It never had an effect and was deprecated in Python 3.4. - All other parameters are now :ref:`keyword-only `. - (Contributed by Serhiy Storchaka in :issue:`29209`.) - -* Removed the ``doctype()`` method of :class:`~xml.etree.ElementTree.XMLParser`. - (Contributed by Serhiy Storchaka in :issue:`29209`.) - -* "unicode_internal" codec is removed. - (Contributed by Inada Naoki in :issue:`36297`.) - -* The ``Cache`` and ``Statement`` objects of the :mod:`sqlite3` module are not - exposed to the user. - (Contributed by Aviv Palivoda in :issue:`30262`.) - -* The ``bufsize`` keyword argument of :func:`fileinput.input` and - :func:`fileinput.FileInput` which was ignored and deprecated since Python 3.6 - has been removed. :issue:`36952` (Contributed by Matthias Bussonnier.) - -* The functions :func:`sys.set_coroutine_wrapper` and - :func:`sys.get_coroutine_wrapper` deprecated in Python 3.7 have been removed; - :issue:`36933` (Contributed by Matthias Bussonnier.) - - -Porting to Python 3.8 -===================== - -This section lists previously described changes and other bugfixes -that may require changes to your code. - - -Changes in Python behavior --------------------------- - -* Yield expressions (both ``yield`` and ``yield from`` clauses) are now disallowed - in comprehensions and generator expressions (aside from the iterable expression - in the leftmost :keyword:`!for` clause). - (Contributed by Serhiy Storchaka in :issue:`10544`.) - -* The compiler now produces a :exc:`SyntaxWarning` when identity checks - (``is`` and ``is not``) are used with certain types of literals - (e.g. strings, numbers). These can often work by accident in CPython, - but are not guaranteed by the language spec. The warning advises users - to use equality tests (``==`` and ``!=``) instead. - (Contributed by Serhiy Storchaka in :issue:`34850`.) - -* The CPython interpreter can swallow exceptions in some circumstances. - In Python 3.8 this happens in fewer cases. In particular, exceptions - raised when getting the attribute from the type dictionary are no longer - ignored. (Contributed by Serhiy Storchaka in :issue:`35459`.) - -* Removed ``__str__`` implementations from builtin types :class:`bool`, - :class:`int`, :class:`float`, :class:`complex` and few classes from - the standard library. They now inherit ``__str__()`` from :class:`object`. - As result, defining the ``__repr__()`` method in the subclass of these - classes will affect their string representation. - (Contributed by Serhiy Storchaka in :issue:`36793`.) - -* On AIX, :attr:`sys.platform` doesn't contain the major version anymore. - It is always ``'aix'``, instead of ``'aix3'`` .. ``'aix7'``. Since - older Python versions include the version number, so it is recommended to - always use ``sys.platform.startswith('aix')``. - (Contributed by M. Felt in :issue:`36588`.) - -* :c:func:`PyEval_AcquireLock` and :c:func:`PyEval_AcquireThread` now - terminate the current thread if called while the interpreter is - finalizing, making them consistent with :c:func:`PyEval_RestoreThread`, - :c:func:`Py_END_ALLOW_THREADS`, and :c:func:`PyGILState_Ensure`. If this - behavior is not desired, guard the call by checking :c:func:`_Py_IsFinalizing` - or :c:func:`sys.is_finalizing`. - (Contributed by Joannah Nanjekye in :issue:`36475`.) - - -Changes in the Python API -------------------------- - -* The :func:`os.getcwdb` function now uses the UTF-8 encoding on Windows, - rather than the ANSI code page: see :pep:`529` for the rationale. The - function is no longer deprecated on Windows. - (Contributed by Victor Stinner in :issue:`37412`.) - -* :class:`subprocess.Popen` can now use :func:`os.posix_spawn` in some cases - for better performance. On Windows Subsystem for Linux and QEMU User - Emulation, the :class:`Popen` constructor using :func:`os.posix_spawn` no longer raises an - exception on errors like "missing program". Instead the child process fails with a - non-zero :attr:`~Popen.returncode`. - (Contributed by Joannah Nanjekye and Victor Stinner in :issue:`35537`.) - -* The *preexec_fn* argument of * :class:`subprocess.Popen` is no longer - compatible with subinterpreters. The use of the parameter in a - subinterpreter now raises :exc:`RuntimeError`. - (Contributed by Eric Snow in :issue:`34651`, modified by Christian Heimes - in :issue:`37951`.) - -* The :meth:`imap.IMAP4.logout` method no longer silently ignores arbitrary - exceptions. - (Contributed by Victor Stinner in :issue:`36348`.) - -* The function :func:`platform.popen` has been removed, after having been deprecated since - Python 3.3: use :func:`os.popen` instead. - (Contributed by Victor Stinner in :issue:`35345`.) - -* The :func:`statistics.mode` function no longer raises an exception - when given multimodal data. Instead, it returns the first mode - encountered in the input data. (Contributed by Raymond Hettinger - in :issue:`35892`.) - -* The :meth:`~tkinter.ttk.Treeview.selection` method of the - :class:`tkinter.ttk.Treeview` class no longer takes arguments. Using it with - arguments for changing the selection was deprecated in Python 3.6. Use - specialized methods like :meth:`~tkinter.ttk.Treeview.selection_set` for - changing the selection. (Contributed by Serhiy Storchaka in :issue:`31508`.) - -* The :meth:`writexml`, :meth:`toxml` and :meth:`toprettyxml` methods of - :mod:`xml.dom.minidom`, and the :meth:`write` method of :mod:`xml.etree`, - now preserve the attribute order specified by the user. - (Contributed by Diego Rojas and Raymond Hettinger in :issue:`34160`.) - -* A :mod:`dbm.dumb` database opened with flags ``'r'`` is now read-only. - :func:`dbm.dumb.open` with flags ``'r'`` and ``'w'`` no longer creates - a database if it does not exist. - (Contributed by Serhiy Storchaka in :issue:`32749`.) - -* The ``doctype()`` method defined in a subclass of - :class:`~xml.etree.ElementTree.XMLParser` will no longer be called and will - emit a :exc:`RuntimeWarning` instead of a :exc:`DeprecationWarning`. - Define the :meth:`doctype() ` - method on a target for handling an XML doctype declaration. - (Contributed by Serhiy Storchaka in :issue:`29209`.) - -* A :exc:`RuntimeError` is now raised when the custom metaclass doesn't - provide the ``__classcell__`` entry in the namespace passed to - ``type.__new__``. A :exc:`DeprecationWarning` was emitted in Python - 3.6--3.7. (Contributed by Serhiy Storchaka in :issue:`23722`.) - -* The :class:`cProfile.Profile` class can now be used as a context - manager. (Contributed by Scott Sanderson in :issue:`29235`.) - -* :func:`shutil.copyfile`, :func:`shutil.copy`, :func:`shutil.copy2`, - :func:`shutil.copytree` and :func:`shutil.move` use platform-specific - "fast-copy" syscalls (see - :ref:`shutil-platform-dependent-efficient-copy-operations` section). - -* :func:`shutil.copyfile` default buffer size on Windows was changed from - 16 KiB to 1 MiB. - -* The ``PyGC_Head`` struct has changed completely. All code that touched the - struct member should be rewritten. (See :issue:`33597`.) - -* The :c:type:`PyInterpreterState` struct has been moved into the "internal" - header files (specifically Include/internal/pycore_pystate.h). An - opaque ``PyInterpreterState`` is still available as part of the public - API (and stable ABI). The docs indicate that none of the struct's - fields are public, so we hope no one has been using them. However, - if you do rely on one or more of those private fields and have no - alternative then please open a BPO issue. We'll work on helping - you adjust (possibly including adding accessor functions to the - public API). (See :issue:`35886`.) - -* The :meth:`mmap.flush() ` method now returns ``None`` on - success and raises an exception on error under all platforms. Previously, - its behavior was platform-dependent: a nonzero value was returned on success; - zero was returned on error under Windows. A zero value was returned on - success; an exception was raised on error under Unix. - (Contributed by Berker Peksag in :issue:`2122`.) - -* :mod:`xml.dom.minidom` and :mod:`xml.sax` modules no longer process - external entities by default. - (Contributed by Christian Heimes in :issue:`17239`.) - -* Deleting a key from a read-only :mod:`dbm` database (:mod:`dbm.dumb`, - :mod:`dbm.gnu` or :mod:`dbm.ndbm`) raises :attr:`error` (:exc:`dbm.dumb.error`, - :exc:`dbm.gnu.error` or :exc:`dbm.ndbm.error`) instead of :exc:`KeyError`. - (Contributed by Xiang Zhang in :issue:`33106`.) - -* :func:`~os.path.expanduser` on Windows now prefers the :envvar:`USERPROFILE` - environment variable and does not use :envvar:`HOME`, which is not normally - set for regular user accounts. - (Contributed by Anthony Sottile in :issue:`36264`.) - -* The exception :class:`asyncio.CancelledError` now inherits from - :class:`BaseException` rather than :class:`Exception`. - (Contributed by Yury Selivanov in :issue:`32528`.) - -* The function :func:`asyncio.wait_for` now correctly waits for cancellation - when using an instance of :class:`asyncio.Task`. Previously, upon reaching - *timeout*, it was cancelled and immediately returned. - (Contributed by Elvis Pranskevichus in :issue:`32751`.) - -* The function :func:`asyncio.BaseTransport.get_extra_info` now returns a safe - to use socket object when 'socket' is passed to the *name* parameter. - (Contributed by Yury Selivanov in :issue:`37027`.) - -* :class:`asyncio.BufferedProtocol` has graduated to the stable API. - -.. _bpo-36085-whatsnew: - -* DLL dependencies for extension modules and DLLs loaded with :mod:`ctypes` on - Windows are now resolved more securely. Only the system paths, the directory - containing the DLL or PYD file, and directories added with - :func:`~os.add_dll_directory` are searched for load-time dependencies. - Specifically, :envvar:`PATH` and the current working directory are no longer - used, and modifications to these will no longer have any effect on normal DLL - resolution. If your application relies on these mechanisms, you should check - for :func:`~os.add_dll_directory` and if it exists, use it to add your DLLs - directory while loading your library. Note that Windows 7 users will need to - ensure that Windows Update KB2533623 has been installed (this is also verified - by the installer). - (Contributed by Steve Dower in :issue:`36085`.) - -* The header files and functions related to pgen have been removed after its - replacement by a pure Python implementation. (Contributed by Pablo Galindo - in :issue:`36623`.) - -* :class:`types.CodeType` has a new parameter in the second position of the - constructor (*posonlyargcount*) to support positional-only arguments defined - in :pep:`570`. The first argument (*argcount*) now represents the total - number of positional arguments (including positional-only arguments). The new - ``replace()`` method of :class:`types.CodeType` can be used to make the code - future-proof. - - -Changes in the C API --------------------- - -* The :c:type:`PyCompilerFlags` structure got a new *cf_feature_version* - field. It should be initialized to ``PY_MINOR_VERSION``. The field is ignored - by default, and is used if and only if ``PyCF_ONLY_AST`` flag is set in - *cf_flags*. - (Contributed by Guido van Rossum in :issue:`35766`.) - -* The :c:func:`PyEval_ReInitThreads` function has been removed from the C API. - It should not be called explicitly: use :c:func:`PyOS_AfterFork_Child` - instead. - (Contributed by Victor Stinner in :issue:`36728`.) - -* On Unix, C extensions are no longer linked to libpython except on Android - and Cygwin. When Python is embedded, ``libpython`` must not be loaded with - ``RTLD_LOCAL``, but ``RTLD_GLOBAL`` instead. Previously, using - ``RTLD_LOCAL``, it was already not possible to load C extensions which - were not linked to ``libpython``, like C extensions of the standard - library built by the ``*shared*`` section of ``Modules/Setup``. - (Contributed by Victor Stinner in :issue:`21536`.) - -* Use of ``#`` variants of formats in parsing or building value (e.g. - :c:func:`PyArg_ParseTuple`, :c:func:`Py_BuildValue`, :c:func:`PyObject_CallFunction`, - etc.) without ``PY_SSIZE_T_CLEAN`` defined raises ``DeprecationWarning`` now. - It will be removed in 3.10 or 4.0. Read :ref:`arg-parsing` for detail. - (Contributed by Inada Naoki in :issue:`36381`.) - -* Instances of heap-allocated types (such as those created with - :c:func:`PyType_FromSpec`) hold a reference to their type object. - Increasing the reference count of these type objects has been moved from - :c:func:`PyType_GenericAlloc` to the more low-level functions, - :c:func:`PyObject_Init` and :c:func:`PyObject_INIT`. - This makes types created through :c:func:`PyType_FromSpec` behave like - other classes in managed code. - - Statically allocated types are not affected. - - For the vast majority of cases, there should be no side effect. - However, types that manually increase the reference count after allocating - an instance (perhaps to work around the bug) may now become immortal. - To avoid this, these classes need to call Py_DECREF on the type object - during instance deallocation. - - To correctly port these types into 3.8, please apply the following - changes: - - * Remove :c:macro:`Py_INCREF` on the type object after allocating an - instance - if any. - This may happen after calling :c:func:`PyObject_New`, - :c:func:`PyObject_NewVar`, :c:func:`PyObject_GC_New`, - :c:func:`PyObject_GC_NewVar`, or any other custom allocator that uses - :c:func:`PyObject_Init` or :c:func:`PyObject_INIT`. - - Example: - - .. code-block:: c - - static foo_struct * - foo_new(PyObject *type) { - foo_struct *foo = PyObject_GC_New(foo_struct, (PyTypeObject *) type); - if (foo == NULL) - return NULL; - #if PY_VERSION_HEX < 0x03080000 - // Workaround for Python issue 35810; no longer necessary in Python 3.8 - PY_INCREF(type) - #endif - return foo; - } - - * Ensure that all custom ``tp_dealloc`` functions of heap-allocated types - decrease the type's reference count. - - Example: - - .. code-block:: c - - static void - foo_dealloc(foo_struct *instance) { - PyObject *type = Py_TYPE(instance); - PyObject_GC_Del(instance); - #if PY_VERSION_HEX >= 0x03080000 - // This was not needed before Python 3.8 (Python issue 35810) - Py_DECREF(type); - #endif - } - - (Contributed by Eddie Elizondo in :issue:`35810`.) - -* The :c:macro:`Py_DEPRECATED()` macro has been implemented for MSVC. - The macro now must be placed before the symbol name. - - Example: - - .. code-block:: c - - Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void); - - (Contributed by Zackery Spytz in :issue:`33407`.) - -* The interpreter does not pretend to support binary compatibility of - extension types across feature releases, anymore. A :c:type:`PyTypeObject` - exported by a third-party extension module is supposed to have all the - slots expected in the current Python version, including - :c:member:`~PyTypeObject.tp_finalize` (:const:`Py_TPFLAGS_HAVE_FINALIZE` - is not checked anymore before reading :c:member:`~PyTypeObject.tp_finalize`). - - (Contributed by Antoine Pitrou in :issue:`32388`.) - -* The :c:func:`PyCode_New` has a new parameter in the second position (*posonlyargcount*) - to support :pep:`570`, indicating the number of positional-only arguments. - -* The functions :c:func:`PyNode_AddChild` and :c:func:`PyParser_AddToken` now accept - two additional ``int`` arguments *end_lineno* and *end_col_offset*. - -* The :file:`libpython38.a` file to allow MinGW tools to link directly against - :file:`python38.dll` is no longer included in the regular Windows distribution. - If you require this file, it may be generated with the ``gendef`` and - ``dlltool`` tools, which are part of the MinGW binutils package: - - .. code-block:: shell - - gendef python38.dll > tmp.def - dlltool --dllname python38.dll --def tmp.def --output-lib libpython38.a - - The location of an installed :file:`pythonXY.dll` will depend on the - installation options and the version and language of Windows. See - :ref:`using-on-windows` for more information. The resulting library should be - placed in the same directory as :file:`pythonXY.lib`, which is generally the - :file:`libs` directory under your Python installation. - - (Contributed by Steve Dower in :issue:`37351`.) - - -CPython bytecode changes ------------------------- - -* The interpreter loop has been simplified by moving the logic of unrolling - the stack of blocks into the compiler. The compiler emits now explicit - instructions for adjusting the stack of values and calling the - cleaning-up code for :keyword:`break`, :keyword:`continue` and - :keyword:`return`. - - Removed opcodes :opcode:`BREAK_LOOP`, :opcode:`CONTINUE_LOOP`, - :opcode:`SETUP_LOOP` and :opcode:`SETUP_EXCEPT`. Added new opcodes - :opcode:`ROT_FOUR`, :opcode:`BEGIN_FINALLY`, :opcode:`CALL_FINALLY` and - :opcode:`POP_FINALLY`. Changed the behavior of :opcode:`END_FINALLY` - and :opcode:`WITH_CLEANUP_START`. - - (Contributed by Mark Shannon, Antoine Pitrou and Serhiy Storchaka in - :issue:`17611`.) - -* Added new opcode :opcode:`END_ASYNC_FOR` for handling exceptions raised - when awaiting a next item in an :keyword:`async for` loop. - (Contributed by Serhiy Storchaka in :issue:`33041`.) - -* The :opcode:`MAP_ADD` now expects the value as the first element in the - stack and the key as the second element. This change was made so the key - is always evaluated before the value in dictionary comprehensions, as - proposed by :pep:`572`. (Contributed by Jörn Heissler in :issue:`35224`.) - - -Demos and Tools ---------------- - -Added a benchmark script for timing various ways to access variables: -``Tools/scripts/var_access_benchmark.py``. -(Contributed by Raymond Hettinger in :issue:`35884`.) - -Here's a summary of performance improvements since Python 3.3: - -.. code-block:: none - - Python version 3.3 3.4 3.5 3.6 3.7 3.8 - -------------- --- --- --- --- --- --- - - Variable and attribute read access: - read_local 4.0 7.1 7.1 5.4 5.1 3.9 - read_nonlocal 5.3 7.1 8.1 5.8 5.4 4.4 - read_global 13.3 15.5 19.0 14.3 13.6 7.6 - read_builtin 20.0 21.1 21.6 18.5 19.0 7.5 - read_classvar_from_class 20.5 25.6 26.5 20.7 19.5 18.4 - read_classvar_from_instance 18.5 22.8 23.5 18.8 17.1 16.4 - read_instancevar 26.8 32.4 33.1 28.0 26.3 25.4 - read_instancevar_slots 23.7 27.8 31.3 20.8 20.8 20.2 - read_namedtuple 68.5 73.8 57.5 45.0 46.8 18.4 - read_boundmethod 29.8 37.6 37.9 29.6 26.9 27.7 - - Variable and attribute write access: - write_local 4.6 8.7 9.3 5.5 5.3 4.3 - write_nonlocal 7.3 10.5 11.1 5.6 5.5 4.7 - write_global 15.9 19.7 21.2 18.0 18.0 15.8 - write_classvar 81.9 92.9 96.0 104.6 102.1 39.2 - write_instancevar 36.4 44.6 45.8 40.0 38.9 35.5 - write_instancevar_slots 28.7 35.6 36.1 27.3 26.6 25.7 - - Data structure read access: - read_list 19.2 24.2 24.5 20.8 20.8 19.0 - read_deque 19.9 24.7 25.5 20.2 20.6 19.8 - read_dict 19.7 24.3 25.7 22.3 23.0 21.0 - read_strdict 17.9 22.6 24.3 19.5 21.2 18.9 - - Data structure write access: - write_list 21.2 27.1 28.5 22.5 21.6 20.0 - write_deque 23.8 28.7 30.1 22.7 21.8 23.5 - write_dict 25.9 31.4 33.3 29.3 29.2 24.7 - write_strdict 22.9 28.4 29.9 27.5 25.2 23.1 - - Stack (or queue) operations: - list_append_pop 144.2 93.4 112.7 75.4 74.2 50.8 - deque_append_pop 30.4 43.5 57.0 49.4 49.2 42.5 - deque_append_popleft 30.8 43.7 57.3 49.7 49.7 42.8 - - Timing loop: - loop_overhead 0.3 0.5 0.6 0.4 0.3 0.3 - - (Measured from the macOS 64-bit builds found at python.org) - -Notable changes in Python 3.8.1 -=============================== - -Due to significant security concerns, the *reuse_address* parameter of -:meth:`asyncio.loop.create_datagram_endpoint` is no longer supported. This is -because of the behavior of the socket option ``SO_REUSEADDR`` in UDP. For more -details, see the documentation for ``loop.create_datagram_endpoint()``. -(Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in -:issue:`37228`.) diff --git a/Doc/whatsnew/3.9.rst.bak b/Doc/whatsnew/3.9.rst.bak deleted file mode 100644 index 6e080c7033c7ee..00000000000000 --- a/Doc/whatsnew/3.9.rst.bak +++ /dev/null @@ -1,540 +0,0 @@ -**************************** - What's New In Python 3.9 -**************************** - -:Release: |release| -:Date: |today| - -.. Rules for maintenance: - - * Anyone can add text to this document. Do not spend very much time - on the wording of your changes, because your text will probably - get rewritten to some degree. - - * The maintainer will go through Misc/NEWS periodically and add - changes; it's therefore more important to add your changes to - Misc/NEWS than to this file. - - * This is not a complete list of every single change; completeness - is the purpose of Misc/NEWS. Some changes I consider too small - or esoteric to include. If such a change is added to the text, - I'll just remove it. (This is another reason you shouldn't spend - too much time on writing your addition.) - - * If you want to draw your new text to the attention of the - maintainer, add 'XXX' to the beginning of the paragraph or - section. - - * It's OK to just add a fragmentary note about a change. For - example: "XXX Describe the transmogrify() function added to the - socket module." The maintainer will research the change and - write the necessary text. - - * You can comment out your additions if you like, but it's not - necessary (especially when a final release is some months away). - - * Credit the author of a patch or bugfix. Just the name is - sufficient; the e-mail address isn't necessary. - - * It's helpful to add the bug/patch number as a comment: - - XXX Describe the transmogrify() function added to the socket - module. - (Contributed by P.Y. Developer in :issue:`12345`.) - - This saves the maintainer the effort of going through the Mercurial log - when researching a change. - -This article explains the new features in Python 3.9, compared to 3.8. - -For full details, see the :ref:`changelog `. - -.. note:: - - Prerelease users should be aware that this document is currently in draft - form. It will be updated substantially as Python 3.9 moves towards release, - so it's worth checking back even after reading earlier versions. - - -Summary -- Release highlights -============================= - -.. This section singles out the most important changes in Python 3.9. - Brevity is key. - - -.. PEP-sized items next. - - - -New Features -============ - - - -Other Language Changes -====================== - -* :func:`__import__` now raises :exc:`ImportError` instead of - :exc:`ValueError`, which used to occur when a relative import went past - its top-level package. - (Contributed by Ngalim Siregar in :issue:`37444`.) - - -* Python now gets the absolute path of the script filename specified on - the command line (ex: ``python3 script.py``): the ``__file__`` attribute of - the :mod:`__main__` module and ``sys.path[0]`` become an - absolute path, rather than a relative path. These paths now remain valid - after the current directory is changed by :func:`os.chdir`. As a side effect, - a traceback also displays the absolute path for :mod:`__main__` module frames - in this case. - (Contributed by Victor Stinner in :issue:`20443`.) - -* In the :ref:`Python Development Mode ` and in debug build, the - *encoding* and *errors* arguments are now checked for string encoding and - decoding operations. Examples: :func:`open`, :meth:`str.encode` and - :meth:`bytes.decode`. - - By default, for best performance, the *errors* argument is only checked at - the first encoding/decoding error and the *encoding* argument is sometimes - ignored for empty strings. - (Contributed by Victor Stinner in :issue:`37388`.) - -* ``"".replace("", s, n)`` now returns ``s`` instead of an empty string for - all non-zero ``n``. It is now consistent with ``"".replace("", s)``. - There are similar changes for :class:`bytes` and :class:`bytearray` objects. - (Contributed by Serhiy Storchaka in :issue:`28029`.) - - -New Modules -=========== - -* None yet. - - -Improved Modules -================ - -ast ---- - -Added the *indent* option to :func:`~ast.dump` which allows it to produce a -multiline indented output. -(Contributed by Serhiy Storchaka in :issue:`37995`.) - -Added :func:`ast.unparse` as a function in the :mod:`ast` module that can -be used to unparse an :class:`ast.AST` object and produce a string with code -that would produce an equivalent :class:`ast.AST` object when parsed. -(Contributed by Pablo Galindo and Batuhan Taskaya in :issue:`38870`.) - -asyncio -------- - -Due to significant security concerns, the *reuse_address* parameter of -:meth:`asyncio.loop.create_datagram_endpoint` is no longer supported. This is -because of the behavior of the socket option ``SO_REUSEADDR`` in UDP. For more -details, see the documentation for ``loop.create_datagram_endpoint()``. -(Contributed by Kyle Stanley, Antoine Pitrou, and Yury Selivanov in -:issue:`37228`.) - -Added a new :term:`coroutine` :meth:`~asyncio.loop.shutdown_default_executor` -that schedules a shutdown for the default executor that waits on the -:class:`~concurrent.futures.ThreadPoolExecutor` to finish closing. Also, -:func:`asyncio.run` has been updated to use the new :term:`coroutine`. -(Contributed by Kyle Stanley in :issue:`34037`.) - -Added :class:`asyncio.PidfdChildWatcher`, a Linux-specific child watcher -implementation that polls process file descriptors. (:issue:`38692`) - -concurrent.futures ------------------- - -Added a new *cancel_futures* parameter to -:meth:`concurrent.futures.Executor.shutdown` that cancels all pending futures -which have not started running, instead of waiting for them to complete before -shutting down the executor. -(Contributed by Kyle Stanley in :issue:`39349`.) - -curses ------- - -Add :func:`curses.get_escdelay`, :func:`curses.set_escdelay`, -:func:`curses.get_tabsize`, and :func:`curses.set_tabsize` functions. -(Contributed by Anthony Sottile in :issue:`38312`.) - -fcntl ------ - -Added constants :data:`~fcntl.F_OFD_GETLK`, :data:`~fcntl.F_OFD_SETLK` -and :data:`~fcntl.F_OFD_SETLKW`. -(Contributed by Dong-hee Na in :issue:`38602`.) - -ftplib -------- - -:class:`~ftplib.FTP` and :class:`~ftplib.FTP_TLS` now raise a :class:`ValueError` -if the given timeout for their constructor is zero to prevent the creation of -a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) - -functools ---------- - -Add the :class:`functools.TopologicalSorter` class to offer functionality to perform -topological sorting of graphs. (Contributed by Pablo Galindo, Tim Peters and Larry -Hastings in :issue:`17005`.) - -gc --- - -When the garbage collector makes a collection in which some objects resurrect -(they are reachable from outside the isolated cycles after the finalizers have -been executed), do not block the collection of all objects that are still -unreachable. (Contributed by Pablo Galindo and Tim Peters in :issue:`38379`.) - -Added a new function :func:`gc.is_finalized` to check if an object has been -finalized by the garbage collector. (Contributed by Pablo Galindo in -:issue:`39322`.) - -imaplib -------- - -:class:`~imaplib.IMAP4` and :class:`~imaplib.IMAP4_SSL` now have -an optional *timeout* parameter for their constructors. -Also, the :meth:`~imaplib.IMAP4.open` method now has an optional *timeout* parameter -with this change. The overridden methods of :class:`~imaplib.IMAP4_SSL` and -:class:`~imaplib.IMAP4_stream` were applied to this change. -(Contributed by Dong-hee Na in :issue:`38615`.) - -math ----- - -Add :func:`math.nextafter`: return the next floating-point value after *x* -towards *y*. -(Contributed by Victor Stinner in :issue:`39288`.) - -Add :func:`math.ulp`: return the value of the least significant bit -of a float. -(Contributed by Victor Stinner in :issue:`39310`.) - -nntplib -------- - -:class:`~nntplib.NNTP` and :class:`~nntplib.NNTP_SSL` now raise a :class:`ValueError` -if the given timeout for their constructor is zero to prevent the creation of -a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) - -os --- - -Added :data:`~os.CLD_KILLED` and :data:`~os.CLD_STOPPED` for :attr:`si_code`. -(Contributed by Dong-hee Na in :issue:`38493`.) - -Exposed the Linux-specific :func:`os.pidfd_open` (:issue:`38692`) and -:data:`os.P_PIDFD` (:issue:`38713`) for process management with file -descriptors. - -The :func:`os.unsetenv` function is now also available on Windows. -(Contributed by Victor Stinner in :issue:`39413`.) - -The :func:`os.putenv` and :func:`os.unsetenv` functions are now always -available. -(Contributed by Victor Stinner in :issue:`39395`.) - -poplib ------- - -:class:`~poplib.POP3` and :class:`~poplib.POP3_SSL` now raise a :class:`ValueError` -if the given timeout for their constructor is zero to prevent the creation of -a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) - -threading ---------- - -In a subinterpreter, spawning a daemon thread now raises a :exc:`RuntimeError`. Daemon -threads were never supported in subinterpreters. Previously, the subinterpreter -finalization crashed with a Python fatal error if a daemon thread was still -running. -(Contributed by Victor Stinner in :issue:`37266`.) - -venv ----- - -The activation scripts provided by :mod:`venv` now all specify their prompt -customization consistently by always using the value specified by -``__VENV_PROMPT__``. Previously some scripts unconditionally used -``__VENV_PROMPT__``, others only if it happened to be set (which was the default -case), and one used ``__VENV_NAME__`` instead. -(Contributed by Brett Cannon in :issue:`37663`.) - -pathlib -------- - -Added :meth:`pathlib.Path.readlink()` which acts similarly to -:func:`os.readlink`. -(Contributed by Girts Folkmanis in :issue:`30618`) - -pprint ------- - -:mod:`pprint` can now pretty-print :class:`types.SimpleNamespace`. -(Contributed by Carl Bordum Hansen in :issue:`37376`.) - -importlib ---------- - -To improve consistency with import statements, :func:`importlib.util.resolve_name` -now raises :exc:`ImportError` instead of :exc:`ValueError` for invalid relative -import attempts. -(Contributed by Ngalim Siregar in :issue:`37444`.) - -smtplib -------- - -:class:`~smtplib.SMTP` and :class:`~smtplib.SMTP_SSL` now raise a :class:`ValueError` -if the given timeout for their constructor is zero to prevent the creation of -a non-blocking socket. (Contributed by Dong-hee Na in :issue:`39259`.) - -:class:`~smtplib.LMTP` constructor now has an optional *timeout* parameter. -(Contributed by Dong-hee Na in :issue:`39329`.) - -signal ------- - -Exposed the Linux-specific :func:`signal.pidfd_send_signal` for sending to -signals to a process using a file descriptor instead of a pid. (:issue:`38712`) - - -Optimizations -============= - - -Build and C API Changes -======================= - -* Provide :c:func:`Py_EnterRecursiveCall` and :c:func:`Py_LeaveRecursiveCall` - as regular functions for the limited API. Previously, there were defined as - macros, but these macros didn't work with the limited API which cannot access - ``PyThreadState.recursion_depth`` field. Remove ``_Py_CheckRecursionLimit`` - from the stable ABI. - (Contributed by Victor Stinner in :issue:`38644`.) - -* Add a new public :c:func:`PyObject_CallNoArgs` function to the C API, which - calls a callable Python object without any arguments. It is the most efficient - way to call a callable Python object without any argument. - (Contributed by Victor Stinner in :issue:`37194`.) - -* The global variable :c:data:`PyStructSequence_UnnamedField` is now a constant - and refers to a constant string. - (Contributed by Serhiy Storchaka in :issue:`38650`.) - -* Exclude ``PyFPE_START_PROTECT()`` and ``PyFPE_END_PROTECT()`` macros of - ``pyfpe.h`` from ``Py_LIMITED_API`` (stable API). - (Contributed by Victor Stinner in :issue:`38835`.) - -* Remove ``PyMethod_ClearFreeList()`` and ``PyCFunction_ClearFreeList()`` - functions: the free lists of bound method objects have been removed. - (Contributed by Inada Naoki and Victor Stinner in :issue:`37340`.) - -* Remove ``PyUnicode_ClearFreeList()`` function: the Unicode free list has been - removed in Python 3.3. - (Contributed by Victor Stinner in :issue:`38896`.) - -* The ``tp_print`` slot of :ref:`PyTypeObject ` has been removed. - It was used for printing objects to files in Python 2.7 and before. Since - Python 3.0, it has been ignored and unused. - (Contributed by Jeroen Demeyer in :issue:`36974`.) - -* On non-Windows platforms, the :c:func:`setenv` and :c:func:`unsetenv` - functions are now required to build Python. - (Contributed by Victor Stinner in :issue:`39395`.) - -* The ``COUNT_ALLOCS`` special build macro has been removed. - (Contributed by Victor Stinner in :issue:`39489`.) - - -Deprecated -========== - -* Currently :func:`math.factorial` accepts :class:`float` instances with - non-negative integer values (like ``5.0``). It raises a :exc:`ValueError` - for non-integral and negative floats. It is now deprecated. In future - Python versions it will raise a :exc:`TypeError` for all floats. - (Contributed by Serhiy Storchaka in :issue:`37315`.) - -* The :mod:`parser` module is deprecated and will be removed in future versions - of Python. For the majority of use cases, users can leverage the Abstract Syntax - Tree (AST) generation and compilation stage, using the :mod:`ast` module. - -* The :mod:`random` module currently accepts any hashable type as a - possible seed value. Unfortunately, some of those types are not - guaranteed to have a deterministic hash value. After Python 3.9, - the module will restrict its seeds to :const:`None`, :class:`int`, - :class:`float`, :class:`str`, :class:`bytes`, and :class:`bytearray`. - -* Opening the :class:`~gzip.GzipFile` file for writing without specifying - the *mode* argument is deprecated. In future Python versions it will always - be opened for reading by default. Specify the *mode* argument for opening - it for writing and silencing a warning. - (Contributed by Serhiy Storchaka in :issue:`28286`.) - -* Deprecated the ``split()`` method of :class:`_tkinter.TkappType` in - favour of the ``splitlist()`` method which has more consistent and - predicable behavior. - (Contributed by Serhiy Storchaka in :issue:`38371`.) - -* The explicit passing of coroutine objects to :func:`asyncio.wait` has been - deprecated and will be removed in version 3.11. - (Contributed by Yury Selivanov and Kyle Stanley in :issue:`34790`.) - -* binhex4 and hexbin4 standards are now deprecated. The :`binhex` module - and the following :mod:`binascii` functions are now deprecated: - - * :func:`~binascii.b2a_hqx`, :func:`~binascii.a2b_hqx` - * :func:`~binascii.rlecode_hqx`, :func:`~binascii.rledecode_hqx` - - (Contributed by Victor Stinner in :issue:`39353`.) - - -Removed -======= - -* The erroneous version at :data:`unittest.mock.__version__` has been removed. - -* :class:`nntplib.NNTP`: ``xpath()`` and ``xgtitle()`` methods have been removed. - These methods are deprecated since Python 3.3. Generally, these extensions - are not supported or not enabled by NNTP server administrators. - For ``xgtitle()``, please use :meth:`nntplib.NNTP.descriptions` or - :meth:`nntplib.NNTP.description` instead. - (Contributed by Dong-hee Na in :issue:`39366`.) - -* :class:`array.array`: ``tostring()`` and ``fromstring()`` methods have been - removed. They were aliases to ``tobytes()`` and ``frombytes()``, deprecated - since Python 3.2. - (Contributed by Victor Stinner in :issue:`38916`.) - -* The abstract base classes in :mod:`collections.abc` no longer are - exposed in the regular :mod:`collections` module. This will help - create a clearer distinction between the concrete classes and the abstract - base classes. - -* The undocumented ``sys.callstats()`` function has been removed. Since Python - 3.7, it was deprecated and always returned :const:`None`. It required a special - build option ``CALL_PROFILE`` which was already removed in Python 3.7. - (Contributed by Victor Stinner in :issue:`37414`.) - -* The ``sys.getcheckinterval()`` and ``sys.setcheckinterval()`` functions have - been removed. They were deprecated since Python 3.2. Use - :func:`sys.getswitchinterval` and :func:`sys.setswitchinterval` instead. - (Contributed by Victor Stinner in :issue:`37392`.) - -* The C function ``PyImport_Cleanup()`` has been removed. It was documented as: - "Empty the module table. For internal use only." - (Contributed by Victor Stinner in :issue:`36710`.) - -* ``_dummy_thread`` and ``dummy_threading`` modules have been removed. These - modules were deprecated since Python 3.7 which requires threading support. - (Contributed by Victor Stinner in :issue:`37312`.) - -* ``aifc.openfp()`` alias to ``aifc.open()``, ``sunau.openfp()`` alias to - ``sunau.open()``, and ``wave.openfp()`` alias to :func:`wave.open()` have been - removed. They were deprecated since Python 3.7. - (Contributed by Victor Stinner in :issue:`37320`.) - -* The :meth:`~threading.Thread.isAlive()` method of :class:`threading.Thread` - has been removed. It was deprecated since Python 3.8. - Use :meth:`~threading.Thread.is_alive()` instead. - (Contributed by Dong-hee Na in :issue:`37804`.) - -* Methods ``getchildren()`` and ``getiterator()`` in the - :mod:`~xml.etree.ElementTree` module have been removed. They were - deprecated in Python 3.2. Use functions :func:`list` and :func:`iter` - instead. The ``xml.etree.cElementTree`` module has been removed. - (Contributed by Serhiy Storchaka in :issue:`36543`.) - -* The old :mod:`plistlib` API has been removed, it was deprecated since Python - 3.4. Use the :func:`~plistlib.load`, :func:`~plistlib.loads`, :func:`~plistlib.dump`, and - :func:`~plistlib.dumps` functions. Additionally, the *use_builtin_types* parameter was - removed, standard :class:`bytes` objects are always used instead. - (Contributed by Jon Janzen in :issue:`36409`.) - -* The C function ``PyThreadState_DeleteCurrent()`` has been removed. It was not documented. - (Contributed by Joannah Nanjekye in :issue:`37878`.) - -* The C function ``PyGen_NeedsFinalizing`` has been removed. It was not - documented, tested, or used anywhere within CPython after the implementation - of :pep:`442`. Patch by Joannah Nanjekye. - (Contributed by Joannah Nanjekye in :issue:`15088`) - -* ``base64.encodestring()`` and ``base64.decodestring()``, aliases deprecated - since Python 3.1, have been removed: use :func:`base64.encodebytes` and - :func:`base64.decodebytes` instead. - (Contributed by Victor Stinner in :issue:`39351`.) - -* ``fractions.gcd()`` function has been removed, it was deprecated since Python - 3.5 (:issue:`22486`): use :func:`math.gcd` instead. - (Contributed by Victor Stinner in :issue:`39350`.) - -* The *buffering* parameter of :class:`bz2.BZ2File` has been removed. Since - Python 3.0, it was ignored and using it emitted a :exc:`DeprecationWarning`. - Pass an open file object to control how the file is opened. - (Contributed by Victor Stinner in :issue:`39357`.) - -* The *encoding* parameter of :func:`json.loads` has been removed. - As of Python 3.1, it was deprecated and ignored; using it has emitted a - :exc:`DeprecationWarning` since Python 3.8. - (Contributed by Inada Naoki in :issue:`39377`) - -* ``with (await asyncio.lock):`` and ``with (yield from asyncio.lock):`` statements are - not longer supported, use ``async with lock`` instead. The same is correct for - ``asyncio.Condition`` and ``asyncio.Semaphore``. - (Contributed by Andrew Svetlov in :issue:`34793`.) - -* The :func:`sys.getcounts` function, the ``-X showalloccount`` command line - option and the ``show_alloc_count`` field of the C structure - :c:type:`PyConfig` have been removed. They required a special Python build by - defining ``COUNT_ALLOCS`` macro. - (Contributed by Victor Stinner in :issue:`39489`.) - - -Porting to Python 3.9 -===================== - -This section lists previously described changes and other bugfixes -that may require changes to your code. - - -Changes in the Python API -------------------------- - -* :func:`open`, :func:`io.open`, :func:`codecs.open` and - :class:`fileinput.FileInput` no longer accept ``'U'`` ("universal newline") - in the file mode. This flag was deprecated since Python 3.3. In Python 3, the - "universal newline" is used by default when a file is open in text mode. The - :ref:`newline parameter ` of :func:`open` controls - how universal newlines works. - (Contributed by Victor Stinner in :issue:`37330`.) - -* :func:`__import__` and :func:`importlib.util.resolve_name` now raise - :exc:`ImportError` where it previously raised :exc:`ValueError`. Callers - catching the specific exception type and supporting both Python 3.9 and - earlier versions will need to catch both using ``except (ImportError, ValueError):``. - -* The :mod:`venv` activation scripts no longer special-case when - ``__VENV_PROMPT__`` is set to ``""``. - -* The :meth:`select.epoll.unregister` method no longer ignores the - :data:`~errno.EBADF` error. - (Contributed by Victor Stinner in :issue:`39239`.) - -* The *compresslevel* parameter of :class:`bz2.BZ2File` became keyword-only, - since the *buffering* parameter has been removed. - (Contributed by Victor Stinner in :issue:`39357`.) - - -CPython bytecode changes ------------------------- - -* The :opcode:`LOAD_ASSERTION_ERROR` opcode was added for handling the - :keyword:`assert` statement. Previously, the assert statement would not work - correctly if the :exc:`AssertionError` exception was being shadowed. - (Contributed by Zackery Spytz in :issue:`34880`.) diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 8870f4d2d2219c..39f6a0b5fbd644 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12779,7 +12779,7 @@ unicode_cutprefix_impl(PyObject* self, PyObject* prefix) } if (match) { return PyUnicode_Substring(self, PyUnicode_GET_LENGTH(prefix), - PyUnicode_GET_LENGTH(self)); + PyUnicode_GET_LENGTH(self)); } return unicode_result_unchanged(self); } @@ -12806,7 +12806,7 @@ unicode_cutsuffix_impl(PyObject* self, PyObject* suffix) } if (match) { return PyUnicode_Substring(self, 0, PyUnicode_GET_LENGTH(self) - - PyUnicode_GET_LENGTH(suffix)); + - PyUnicode_GET_LENGTH(suffix)); } return unicode_result_unchanged(self); } From fe186443d87a3005f94742f2da858d27ebb86b08 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 13:57:08 -0400 Subject: [PATCH 04/35] pep 7: line up arguemnts --- Objects/unicodeobject.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 39f6a0b5fbd644..8870f4d2d2219c 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12779,7 +12779,7 @@ unicode_cutprefix_impl(PyObject* self, PyObject* prefix) } if (match) { return PyUnicode_Substring(self, PyUnicode_GET_LENGTH(prefix), - PyUnicode_GET_LENGTH(self)); + PyUnicode_GET_LENGTH(self)); } return unicode_result_unchanged(self); } @@ -12806,7 +12806,7 @@ unicode_cutsuffix_impl(PyObject* self, PyObject* suffix) } if (match) { return PyUnicode_Substring(self, 0, PyUnicode_GET_LENGTH(self) - - PyUnicode_GET_LENGTH(suffix)); + - PyUnicode_GET_LENGTH(suffix)); } return unicode_result_unchanged(self); } From ff8e3c6bc2d4c166d383d96556a5498db8b20f7a Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 14:43:28 -0400 Subject: [PATCH 05/35] pep 7: line up arguemnts --- Objects/bytearrayobject.c | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index 1f5395f3817ecf..56da279669b151 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1201,16 +1201,16 @@ static PyObject * bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) /*[clinic end generated code: output=21632e315d769b4b input=1848afa62344e091]*/ { - const char* self_start = PyByteArray_AS_STRING(self); + const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); - const char* prefix_start = prefix->buf; + const char *prefix_start = prefix->buf; Py_ssize_t prefix_len = prefix->len; if (self_len >= prefix_len && memcmp(self_start, prefix_start, prefix_len) == 0) { return PyByteArray_FromStringAndSize(self_start + prefix_len, - self_len - prefix_len); + self_len - prefix_len); } return PyByteArray_FromStringAndSize(self_start, self_len); @@ -1232,9 +1232,9 @@ static PyObject * bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) /*[clinic end generated code: output=9862e6f256b4e5a0 input=8f8c10709806b42b]*/ { - const char* self_start = PyByteArray_AS_STRING(self); + const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); - const char* suffix_start = suffix->buf; + const char *suffix_start = suffix->buf; Py_ssize_t suffix_len = suffix->len; if (self_len >= suffix_len @@ -1242,7 +1242,7 @@ bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) suffix_start, suffix_len) == 0) { return PyByteArray_FromStringAndSize(self_start, - self_len - suffix_len); + self_len - suffix_len); } return PyByteArray_FromStringAndSize(self_start, self_len); From 5339a46a965df72c51ecf1886432d7f5b5021c6f Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Wed, 11 Mar 2020 19:17:37 +0000 Subject: [PATCH 06/35] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20b?= =?UTF-8?q?lurb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst new file mode 100644 index 00000000000000..64b4bddf81590a --- /dev/null +++ b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst @@ -0,0 +1 @@ +Added str.cutprefix and str.cutsuffix methods and corresponding bytes and bytearray methods to cut affixes off of a string, if present. \ No newline at end of file From cc85978dfca60b1df8dfecf54caa130df4c2e41c Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 15:59:37 -0400 Subject: [PATCH 07/35] add UserString methods --- Lib/collections/__init__.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 1aa7d10ad22e4a..758980667cf9b6 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1202,6 +1202,14 @@ def count(self, sub, start=0, end=_sys.maxsize): if isinstance(sub, UserString): sub = sub.data return self.data.count(sub, start, end) + def cutprefix(self, prefix, /): + if self.startswith(prefix): + return self[len(prefix):] + return self[:] + def cutsuffix(self, suffix, /): + if self.endswith(suffix): + return self[:len(self)-len(suffix)] + return self[:] def encode(self, encoding='utf-8', errors='strict'): encoding = 'utf-8' if encoding is None else encoding errors = 'strict' if errors is None else errors From 111b0f991b26e35f26e11abf76bde270c3866558 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 16:08:09 -0400 Subject: [PATCH 08/35] update count of objects in test_doctests --- Lib/test/test_doctest.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py index aa92777efc3c7a..aa387a30f46959 100644 --- a/Lib/test/test_doctest.py +++ b/Lib/test/test_doctest.py @@ -661,7 +661,7 @@ def non_Python_modules(): r""" >>> import builtins >>> tests = doctest.DocTestFinder().find(builtins) - >>> 800 < len(tests) < 820 # approximate number of objects with docstrings + >>> 800 < len(tests) < 822 # approximate number of objects with docstrings True >>> real_tests = [t for t in tests if len(t.examples) > 0] >>> len(real_tests) # objects that actually have doctests From 8265e4d527a97dc862b61104c15d6c58a70f4768 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 16:25:04 -0400 Subject: [PATCH 09/35] restore clinic output --- Objects/unicodeobject.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 8870f4d2d2219c..b3eb0a950ed70f 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12770,7 +12770,7 @@ Otherwise, return the original string. [clinic start generated code]*/ static PyObject * -unicode_cutprefix_impl(PyObject* self, PyObject* prefix) +unicode_cutprefix_impl(PyObject *self, PyObject *prefix) /*[clinic end generated code: output=885902e3c7f5fae0 input=52efc288b6160337]*/ { int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); @@ -12797,7 +12797,7 @@ Otherwise, return the original string. [clinic start generated code]*/ static PyObject * -unicode_cutsuffix_impl(PyObject* self, PyObject* suffix) +unicode_cutsuffix_impl(PyObject *self, PyObject *suffix) /*[clinic end generated code: output=5e5babcd284e6e6e input=7cb8ec5dd6849be0]*/ { int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); From 7401b876ea8d29f454f0a4d43a48dfe9e5ac28b9 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 16:49:16 -0400 Subject: [PATCH 10/35] update count of objects in test_doctests --- Lib/test/test_doctest.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Lib/test/test_doctest.py b/Lib/test/test_doctest.py index aa387a30f46959..a9b9424fc854da 100644 --- a/Lib/test/test_doctest.py +++ b/Lib/test/test_doctest.py @@ -661,7 +661,7 @@ def non_Python_modules(): r""" >>> import builtins >>> tests = doctest.DocTestFinder().find(builtins) - >>> 800 < len(tests) < 822 # approximate number of objects with docstrings + >>> 800 < len(tests) < 826 # approximate number of objects with docstrings True >>> real_tests = [t for t in tests if len(t.examples) > 0] >>> len(real_tests) # objects that actually have doctests From e55017151ba2f7d7134f686929582add80079023 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 18:40:17 -0400 Subject: [PATCH 11/35] return original when bytes.cut***fix does not find match --- Objects/bytesobject.c | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 738ce6f1886d7f..090a052b795bf0 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2209,6 +2209,11 @@ bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) self_len - prefix_len); } + if (PyBytes_CheckExact(self)) { + Py_INCREF(self); + return (PyObject *)self; + } + return PyBytes_FromStringAndSize(self_start, self_len); } @@ -2241,6 +2246,11 @@ bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) self_len - suffix_len); } + if (PyBytes_CheckExact(self)) { + Py_INCREF(self); + return (PyObject *)self; + } + return PyBytes_FromStringAndSize(self_start, self_len); } From 0a5d0a9b09e5766973f65ac349a234577292661b Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 23:39:48 -0400 Subject: [PATCH 12/35] Document cutprefix and cutsuffix --- Doc/library/stdtypes.rst | 64 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 881c15d8f7c5d1..4e085da405f579 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1549,6 +1549,35 @@ expression support in the :mod:`re` module). interpreted as in slice notation. +.. method:: str.cutprefix(prefix, /) + + Return a copy of the string with the given prefix removed, if present. :: + + >>> 'BarFooBaz'.cutprefix('Bar') + 'FooBaz' + >>> 'BarFooBaz'.cutprefix('Baz') + 'BarFooBaz' + + The expression ``s.cutprefix(pre)`` is roughly equivalent to + ``s[len(pre):] if s.startswith(pre) else s``. + + .. versionadded:: 3.9 + +.. method:: str.cutsuffix(suffix, /) + + Return a copy of the string with the given suffix removed, if present. :: + + >>> 'BarFooBaz'.cutsuffix('Baz') + 'BarFoo' + >>> 'BarFooBaz'.cutsuffix('Bar') + 'BarFooBaz' + + The expression ``s.cutprefix(suf)`` is roughly equivalent to + ``s[:len(s)-len(suf)] if s.endswith(suf) else s``. + + .. versionadded:: 3.9 + + .. method:: str.encode(encoding="utf-8", errors="strict") Return an encoded version of the string as a bytes object. Default encoding @@ -2591,6 +2620,41 @@ arbitrary binary data. Also accept an integer in the range 0 to 255 as the subsequence. +.. method:: bytes.cutprefix(prefix, /) + bytearray.cutprefix(prefix, /) + + Return a copy of the binary data with the given prefix removed, + if present. :: + + >>> b'BarFooBaz'.cutprefix(b'Bar') + b'FooBaz' + >>> b'BarFooBaz'.cutprefix(b'Baz') + b'BarFooBaz' + + The *prefix* may be any :term:`bytes-like object`. + The expression ``b.cutprefix(pre)`` is roughly equivalent to + ``b[len(pre):] if b.startswith(pre) else b``. + + .. versionadded:: 3.9 + + +.. method:: bytes.cutsuffix(suffix, /) + bytearray.cutsuffix(suffix, /) + Return a copy of the binary data with the given suffix removed, + if present. :: + + >>> b'BarFooBaz'.cutsuffix(b'Baz') + b'BarFoo' + >>> 'BarFooBaz'.cutsuffix(b'Bar') + b'BarFooBaz' + + The *suffix* may be any :term:`bytes-like object`. + The expression ``b.cutsuffix(suf)`` is roughly equivalent to + ``b[:len(b)-len(suf)] if b.endswith(suf) else b``. + + .. versionadded:: 3.9 + + .. method:: bytes.decode(encoding="utf-8", errors="strict") bytearray.decode(encoding="utf-8", errors="strict") From a126438e86874e6fb98342484513c5dd992576ed Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 11 Mar 2020 23:50:16 -0400 Subject: [PATCH 13/35] fix doctest in docs --- Doc/library/stdtypes.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4e085da405f579..1892c418c60b94 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2640,12 +2640,13 @@ arbitrary binary data. .. method:: bytes.cutsuffix(suffix, /) bytearray.cutsuffix(suffix, /) + Return a copy of the binary data with the given suffix removed, if present. :: >>> b'BarFooBaz'.cutsuffix(b'Baz') b'BarFoo' - >>> 'BarFooBaz'.cutsuffix(b'Bar') + >>> b'BarFooBaz'.cutsuffix(b'Bar') b'BarFooBaz' The *suffix* may be any :term:`bytes-like object`. From fbc4a504b94958212a3cfccc85da4a9646b7692a Mon Sep 17 00:00:00 2001 From: sweeneyde <36520290+sweeneyde@users.noreply.github.com> Date: Wed, 11 Mar 2020 23:56:41 -0400 Subject: [PATCH 14/35] Add credit --- .../Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst index 64b4bddf81590a..6e514128743291 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst @@ -1 +1 @@ -Added str.cutprefix and str.cutsuffix methods and corresponding bytes and bytearray methods to cut affixes off of a string, if present. \ No newline at end of file +Added str.cutprefix and str.cutsuffix methods and corresponding bytes and bytearray methods to cut affixes off of a string, if present. Patch by Dennis Sweeney. From 3783dc3ad02c6c6cd87852fff4ef9b5a01082787 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 00:57:33 -0400 Subject: [PATCH 15/35] make the empty affix case fast --- Doc/library/stdtypes.rst | 6 +++--- Objects/bytesobject.c | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 1892c418c60b94..93f56f4bd83a1a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1573,7 +1573,7 @@ expression support in the :mod:`re` module). 'BarFooBaz' The expression ``s.cutprefix(suf)`` is roughly equivalent to - ``s[:len(s)-len(suf)] if s.endswith(suf) else s``. + ``s[:-len(suf)] if suf and s.endswith(suf) else s``. .. versionadded:: 3.9 @@ -2633,7 +2633,7 @@ arbitrary binary data. The *prefix* may be any :term:`bytes-like object`. The expression ``b.cutprefix(pre)`` is roughly equivalent to - ``b[len(pre):] if b.startswith(pre) else b``. + ``b[len(pre):] if b.startswith(pre) else b[:]``. .. versionadded:: 3.9 @@ -2651,7 +2651,7 @@ arbitrary binary data. The *suffix* may be any :term:`bytes-like object`. The expression ``b.cutsuffix(suf)`` is roughly equivalent to - ``b[:len(b)-len(suf)] if b.endswith(suf) else b``. + ``b[:-len(suf)] if suf and b.endswith(suf) else b[:]``. .. versionadded:: 3.9 diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 090a052b795bf0..53cd04fa9ea757 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2203,6 +2203,7 @@ bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) Py_ssize_t prefix_len = prefix->len; if (self_len >= prefix_len + && prefix_len > 0 && memcmp(self_start, prefix_start, prefix_len) == 0) { return PyBytes_FromStringAndSize(self_start + prefix_len, @@ -2239,6 +2240,7 @@ bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) Py_ssize_t suffix_len = suffix->len; if (self_len >= suffix_len + && suffix_len > 0 && memcmp(self_start + self_len - suffix_len, suffix_start, suffix_len) == 0) { From 428e733ba44e34a1185c236be8b92acf08ae0829 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 01:09:44 -0400 Subject: [PATCH 16/35] clarified: one affix at a time --- Doc/library/stdtypes.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 93f56f4bd83a1a..8b99196acdc3c3 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1560,6 +1560,8 @@ expression support in the :mod:`re` module). The expression ``s.cutprefix(pre)`` is roughly equivalent to ``s[len(pre):] if s.startswith(pre) else s``. + Unlike :meth:`~str.startswith`, only one prefix can be passed + at a time. .. versionadded:: 3.9 @@ -1574,6 +1576,8 @@ expression support in the :mod:`re` module). The expression ``s.cutprefix(suf)`` is roughly equivalent to ``s[:-len(suf)] if suf and s.endswith(suf) else s``. + Unlike :meth:`~str.endswith`, only one suffix can be passed + at a time. .. versionadded:: 3.9 @@ -2634,6 +2638,8 @@ arbitrary binary data. The *prefix* may be any :term:`bytes-like object`. The expression ``b.cutprefix(pre)`` is roughly equivalent to ``b[len(pre):] if b.startswith(pre) else b[:]``. + Unlike :meth:`~bytes.startswith`, only one prefix can be passed + at a time. .. versionadded:: 3.9 @@ -2652,6 +2658,8 @@ arbitrary binary data. The *suffix* may be any :term:`bytes-like object`. The expression ``b.cutsuffix(suf)`` is roughly equivalent to ``b[:-len(suf)] if suf and b.endswith(suf) else b[:]``. + Unlike :meth:`~bytes.endswith`, only one suffix can be passed + at a time. .. versionadded:: 3.9 From 5796757661d8ded53895f80e024e810bb3e72b52 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 01:30:34 -0400 Subject: [PATCH 17/35] ensure tuples are not allowed --- Lib/collections/__init__.py | 8 +++++++- Lib/test/string_tests.py | 2 ++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 758980667cf9b6..bca6bdd8a74bd7 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1203,11 +1203,17 @@ def count(self, sub, start=0, end=_sys.maxsize): sub = sub.data return self.data.count(sub, start, end) def cutprefix(self, prefix, /): + if not isinstance(prefix, str): + raise TypeError(f"cutprefix() argument must be str, not " + f"{type(prefix)!r}") if self.startswith(prefix): return self[len(prefix):] return self[:] def cutsuffix(self, suffix, /): - if self.endswith(suffix): + if not isinstance(suffix, str): + raise TypeError(f"cutsuffix() argument must be str, not " + f"{type(suffix)!r}") + if suffix and self.endswith(suffix): return self[:len(self)-len(suffix)] return self[:] def encode(self, encoding='utf-8', errors='strict'): diff --git a/Lib/test/string_tests.py b/Lib/test/string_tests.py index 51dd4a3afb0555..60d9d7c25945b0 100644 --- a/Lib/test/string_tests.py +++ b/Lib/test/string_tests.py @@ -698,6 +698,7 @@ def test_cutprefix(self): self.checkraises(TypeError, 'hello', 'cutprefix', 42) self.checkraises(TypeError, 'hello', 'cutprefix', 42, 'h') self.checkraises(TypeError, 'hello', 'cutprefix', 'h', 42) + self.checkraises(TypeError, 'hello', 'cutprefix', ("he", "l")) def test_cutsuffix(self): self.checkequal('sp', 'spam', 'cutsuffix', 'am') @@ -715,6 +716,7 @@ def test_cutsuffix(self): self.checkraises(TypeError, 'hello', 'cutsuffix', 42) self.checkraises(TypeError, 'hello', 'cutsuffix', 42, 'h') self.checkraises(TypeError, 'hello', 'cutsuffix', 'h', 42) + self.checkraises(TypeError, 'hello', 'cutsuffix', ("lo", "l")) def test_capitalize(self): self.checkequal(' hello ', ' hello ', 'capitalize') From 6fe9ac5b933d4510ce34885baff2e5c1f2ff8fb3 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 01:57:26 -0400 Subject: [PATCH 18/35] Fix userstring type behavior --- Lib/collections/__init__.py | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index bca6bdd8a74bd7..0fe03dbb7d13f5 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1203,19 +1203,13 @@ def count(self, sub, start=0, end=_sys.maxsize): sub = sub.data return self.data.count(sub, start, end) def cutprefix(self, prefix, /): - if not isinstance(prefix, str): - raise TypeError(f"cutprefix() argument must be str, not " - f"{type(prefix)!r}") - if self.startswith(prefix): - return self[len(prefix):] - return self[:] + if isinstance(prefix, UserString): + prefix = prefix.data + return self.__class__(self.data.cutprefix(prefix)) def cutsuffix(self, suffix, /): - if not isinstance(suffix, str): - raise TypeError(f"cutsuffix() argument must be str, not " - f"{type(suffix)!r}") - if suffix and self.endswith(suffix): - return self[:len(self)-len(suffix)] - return self[:] + if isinstance(suffix, UserString): + suffix = suffix.data + return self.__class__(self.data.cutsuffix(suffix)) def encode(self, encoding='utf-8', errors='strict'): encoding = 'utf-8' if encoding is None else encoding errors = 'strict' if errors is None else errors From 13e8296f16934ec98d2a216cb88fa7abe49b26d4 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 03:47:44 -0400 Subject: [PATCH 19/35] WhatsNew and ACKS --- Misc/ACKS | 1 + 1 file changed, 1 insertion(+) diff --git a/Misc/ACKS b/Misc/ACKS index cc5694af008b32..97a7e0e4b597ed 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -1655,6 +1655,7 @@ Hisao Suzuki Kalle Svensson Andrew Svetlov Paul Swartz +Dennis Sweeney Al Sweigart Sviatoslav Sydorenko Thenault Sylvain From 49fa2208ac79dc8e2d8603ca41d76256f5a5ac6a Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 03:48:58 -0400 Subject: [PATCH 20/35] WhatsNew and ACKS --- Doc/whatsnew/3.9.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index c2328053a66aa3..f9f85dab8c46bc 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -105,6 +105,13 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in :class:`dict` class. See :pep:`584` for a full description. (Contributed by Brandt Bucher in :issue:`36144`.) +cutprefix and cutsuffix methods for strings +------------------------------------------- +``str.cutprefix(prefix)`` and ``str.cutsuffix(suffix)`` have been added to +easily remove an unneeded prefix or a suffix from a string. Corrsponding +``bytes`` and ``bytearray`` methods have also been added. +(Contributed by Dennis Sweeney in :issue:`18939`.) + Other Language Changes ====================== From 550beca6c88cece2a1b5f6cfe1507a042c26c8e5 Mon Sep 17 00:00:00 2001 From: sweeneyde <36520290+sweeneyde@users.noreply.github.com> Date: Thu, 12 Mar 2020 04:19:38 -0400 Subject: [PATCH 21/35] fix spelling Co-Authored-By: Serhiy Storchaka --- Doc/whatsnew/3.9.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index f9f85dab8c46bc..56958e99f4bad1 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -108,7 +108,7 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in cutprefix and cutsuffix methods for strings ------------------------------------------- ``str.cutprefix(prefix)`` and ``str.cutsuffix(suffix)`` have been added to -easily remove an unneeded prefix or a suffix from a string. Corrsponding +easily remove an unneeded prefix or a suffix from a string. Corresponding ``bytes`` and ``bytearray`` methods have also been added. (Contributed by Dennis Sweeney in :issue:`18939`.) From 01d06553edf463cc9e1f24ea289bff2ee9146956 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Thu, 12 Mar 2020 15:32:07 -0400 Subject: [PATCH 22/35] Direct readers from (l/r)strip to cut***fix --- Doc/library/stdtypes.rst | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 8b99196acdc3c3..6eeebec105f065 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1864,6 +1864,9 @@ expression support in the :mod:`re` module). >>> 'www.example.com'.lstrip('cmowz.') 'example.com' + See :meth:`str.cutprefix` for a method that will remove a single prefix + string rather than all of a set of characters. + .. staticmethod:: str.maketrans(x[, y[, z]]) @@ -1944,6 +1947,8 @@ expression support in the :mod:`re` module). >>> 'mississippi'.rstrip('ipz') 'mississ' + See :meth:`str.cutsuffix` for a method that will remove a single suffix + string rather than all of a set of characters. .. method:: str.split(sep=None, maxsplit=-1) @@ -2914,7 +2919,9 @@ produce new objects. b'example.com' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. + :term:`bytes-like object`. See :meth:`~bytes.cutprefix` for a method + that will remove a single prefix string rather than all of a set of + characters. .. note:: @@ -2963,7 +2970,9 @@ produce new objects. b'mississ' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. + :term:`bytes-like object`. See :meth:`~bytes.cutsuffix` for a method + that will remove a single suffix string rather than all of a set of + characters. .. note:: From fe80ba8b9767ce59c0f5cd1904c2eb866a930502 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Mon, 16 Mar 2020 00:58:19 -0400 Subject: [PATCH 23/35] Fix typo in docs --- Doc/library/stdtypes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 6eeebec105f065..e5c45065af8729 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1574,7 +1574,7 @@ expression support in the :mod:`re` module). >>> 'BarFooBaz'.cutsuffix('Bar') 'BarFooBaz' - The expression ``s.cutprefix(suf)`` is roughly equivalent to + The expression ``s.cutsuffix(suf)`` is roughly equivalent to ``s[:-len(suf)] if suf and s.endswith(suf) else s``. Unlike :meth:`~str.endswith`, only one suffix can be passed at a time. From ae236920c3e4d74872bbc4ffaa8de3879d25bd22 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Mon, 16 Mar 2020 01:17:14 -0400 Subject: [PATCH 24/35] minor c formatting consistency --- Objects/bytearrayobject.c | 2 +- Objects/bytesobject.c | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index 56da279669b151..48e7bba1a717db 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1239,7 +1239,7 @@ bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) if (self_len >= suffix_len && memcmp(self_start + self_len - suffix_len, - suffix_start, suffix_len) == 0) + suffix_start, suffix_len) == 0) { return PyByteArray_FromStringAndSize(self_start, self_len - suffix_len); diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 53cd04fa9ea757..1f34f7158cdb0f 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2234,9 +2234,9 @@ static PyObject * bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) /*[clinic end generated code: output=303549ce0a999724 input=5e4ee249c40f7bf6]*/ { - const char* self_start = PyBytes_AS_STRING(self); + const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); - const char* suffix_start = suffix->buf; + const char *suffix_start = suffix->buf; Py_ssize_t suffix_len = suffix->len; if (self_len >= suffix_len From a9e253c86334f6c55d1deac865c4c85296e7c620 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Fri, 20 Mar 2020 12:50:47 -0400 Subject: [PATCH 25/35] copy/paste errors; don't say 'return the original' --- Objects/bytesobject.c | 8 ++++---- Objects/clinic/bytesobject.c.h | 6 +++--- Objects/clinic/unicodeobject.c.h | 8 ++++---- Objects/unicodeobject.c | 10 +++++----- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 1f34f7158cdb0f..22116aa0c632cc 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2190,12 +2190,12 @@ bytes.cutprefix as bytes_cutprefix Remove a specified prefix, if present. If the bytes starts with the prefix, return b[len(prefix):]. -Otherwise, return the original bytes. +Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=5e5ef0cf576a8a9c input=f5409d4eb86164e8]*/ +/*[clinic end generated code: output=5e5ef0cf576a8a9c input=62efeb5116b52516]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); @@ -2227,12 +2227,12 @@ bytes.cutsuffix as bytes_cutsuffix Remove a specified suffix, if present. If the bytes ends with the suffix, return b[:len(b)-len(prefix)]. -Otherwise, return the original bytes. +Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=303549ce0a999724 input=5e4ee249c40f7bf6]*/ +/*[clinic end generated code: output=303549ce0a999724 input=afec1a85ea98d67f]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index d020dfb7619b52..587d0f2bb82cdf 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -533,7 +533,7 @@ PyDoc_STRVAR(bytes_cutprefix__doc__, "Remove a specified prefix, if present.\n" "\n" "If the bytes starts with the prefix, return b[len(prefix):].\n" -"Otherwise, return the original bytes."); +"Otherwise, return a copy of the original bytes."); #define BYTES_CUTPREFIX_METHODDEF \ {"cutprefix", (PyCFunction)bytes_cutprefix, METH_O, bytes_cutprefix__doc__}, @@ -572,7 +572,7 @@ PyDoc_STRVAR(bytes_cutsuffix__doc__, "Remove a specified suffix, if present.\n" "\n" "If the bytes ends with the suffix, return b[:len(b)-len(prefix)].\n" -"Otherwise, return the original bytes."); +"Otherwise, return a copy of the original bytes."); #define BYTES_CUTSUFFIX_METHODDEF \ {"cutsuffix", (PyCFunction)bytes_cutsuffix, METH_O, bytes_cutsuffix__doc__}, @@ -833,4 +833,4 @@ bytes_hex(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=9e9fe9b5771cea06 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=377e6c8757a80baa input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index 2e95db8bfd3d52..41fb19b088f9d8 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -761,7 +761,7 @@ PyDoc_STRVAR(unicode_cutprefix__doc__, "Remove a specified prefix, if present.\n" "\n" "If the string starts with the prefix, return string[len(prefix):].\n" -"Otherwise, return the original string."); +"Otherwise, return a copy of the original string."); #define UNICODE_CUTPREFIX_METHODDEF \ {"cutprefix", (PyCFunction)unicode_cutprefix, METH_O, unicode_cutprefix__doc__}, @@ -795,8 +795,8 @@ PyDoc_STRVAR(unicode_cutsuffix__doc__, "\n" "Remove a specified suffix, if present.\n" "\n" -"If the string starts with the suffix, return string[len(suffix):].\n" -"Otherwise, return the original string."); +"If the string ends with the suffix, return string[:len(string)-len(suffix)].\n" +"Otherwise, return a copy of the original string."); #define UNICODE_CUTSUFFIX_METHODDEF \ {"cutsuffix", (PyCFunction)unicode_cutsuffix, METH_O, unicode_cutsuffix__doc__}, @@ -1302,4 +1302,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return unicode_sizeof_impl(self); } -/*[clinic end generated code: output=94e6d11b96656992 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=db94a0ba79ae9c95 input=a9049054013a1b77]*/ diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index b3eb0a950ed70f..2aac05714455fc 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12766,12 +12766,12 @@ str.cutprefix as unicode_cutprefix Remove a specified prefix, if present. If the string starts with the prefix, return string[len(prefix):]. -Otherwise, return the original string. +Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * unicode_cutprefix_impl(PyObject *self, PyObject *prefix) -/*[clinic end generated code: output=885902e3c7f5fae0 input=52efc288b6160337]*/ +/*[clinic end generated code: output=885902e3c7f5fae0 input=adf93aba99de6d2b]*/ { int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); if (match == -1) { @@ -12792,13 +12792,13 @@ str.cutsuffix as unicode_cutsuffix Remove a specified suffix, if present. -If the string starts with the suffix, return string[len(suffix):]. -Otherwise, return the original string. +If the string ends with the suffix, return string[:len(string)-len(suffix)]. +Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * unicode_cutsuffix_impl(PyObject *self, PyObject *suffix) -/*[clinic end generated code: output=5e5babcd284e6e6e input=7cb8ec5dd6849be0]*/ +/*[clinic end generated code: output=5e5babcd284e6e6e input=cdfb4cb7d8a27164]*/ { int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); if (match == -1) { From 4c33b7441385c9f2f49b50b6d81950d851676c38 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 25 Mar 2020 18:59:11 -0400 Subject: [PATCH 26/35] changed 'cut' to 'remove' --- Doc/library/stdtypes.rst | 44 +++++++++---------- Lib/collections/__init__.py | 8 ++-- Lib/test/string_tests.py | 70 +++++++++++++++--------------- Objects/bytearrayobject.c | 16 +++---- Objects/bytesobject.c | 16 +++---- Objects/clinic/bytearrayobject.c.h | 34 +++++++-------- Objects/clinic/bytesobject.c.h | 34 +++++++-------- Objects/clinic/unicodeobject.c.h | 34 +++++++-------- Objects/unicodeobject.c | 16 +++---- 9 files changed, 136 insertions(+), 136 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e5c45065af8729..0ee9592b98c848 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1549,32 +1549,32 @@ expression support in the :mod:`re` module). interpreted as in slice notation. -.. method:: str.cutprefix(prefix, /) +.. method:: str.removeprefix(prefix, /) Return a copy of the string with the given prefix removed, if present. :: - >>> 'BarFooBaz'.cutprefix('Bar') + >>> 'BarFooBaz'.removeprefix('Bar') 'FooBaz' - >>> 'BarFooBaz'.cutprefix('Baz') + >>> 'BarFooBaz'.removeprefix('Baz') 'BarFooBaz' - The expression ``s.cutprefix(pre)`` is roughly equivalent to + The expression ``s.removeprefix(pre)`` is roughly equivalent to ``s[len(pre):] if s.startswith(pre) else s``. Unlike :meth:`~str.startswith`, only one prefix can be passed at a time. .. versionadded:: 3.9 -.. method:: str.cutsuffix(suffix, /) +.. method:: str.removesuffix(suffix, /) Return a copy of the string with the given suffix removed, if present. :: - >>> 'BarFooBaz'.cutsuffix('Baz') + >>> 'BarFooBaz'.removesuffix('Baz') 'BarFoo' - >>> 'BarFooBaz'.cutsuffix('Bar') + >>> 'BarFooBaz'.removesuffix('Bar') 'BarFooBaz' - The expression ``s.cutsuffix(suf)`` is roughly equivalent to + The expression ``s.removesuffix(suf)`` is roughly equivalent to ``s[:-len(suf)] if suf and s.endswith(suf) else s``. Unlike :meth:`~str.endswith`, only one suffix can be passed at a time. @@ -1864,7 +1864,7 @@ expression support in the :mod:`re` module). >>> 'www.example.com'.lstrip('cmowz.') 'example.com' - See :meth:`str.cutprefix` for a method that will remove a single prefix + See :meth:`str.removeprefix` for a method that will remove a single prefix string rather than all of a set of characters. @@ -1947,7 +1947,7 @@ expression support in the :mod:`re` module). >>> 'mississippi'.rstrip('ipz') 'mississ' - See :meth:`str.cutsuffix` for a method that will remove a single suffix + See :meth:`str.removesuffix` for a method that will remove a single suffix string rather than all of a set of characters. .. method:: str.split(sep=None, maxsplit=-1) @@ -2629,19 +2629,19 @@ arbitrary binary data. Also accept an integer in the range 0 to 255 as the subsequence. -.. method:: bytes.cutprefix(prefix, /) - bytearray.cutprefix(prefix, /) +.. method:: bytes.removeprefix(prefix, /) + bytearray.removeprefix(prefix, /) Return a copy of the binary data with the given prefix removed, if present. :: - >>> b'BarFooBaz'.cutprefix(b'Bar') + >>> b'BarFooBaz'.removeprefix(b'Bar') b'FooBaz' - >>> b'BarFooBaz'.cutprefix(b'Baz') + >>> b'BarFooBaz'.removeprefix(b'Baz') b'BarFooBaz' The *prefix* may be any :term:`bytes-like object`. - The expression ``b.cutprefix(pre)`` is roughly equivalent to + The expression ``b.removeprefix(pre)`` is roughly equivalent to ``b[len(pre):] if b.startswith(pre) else b[:]``. Unlike :meth:`~bytes.startswith`, only one prefix can be passed at a time. @@ -2649,19 +2649,19 @@ arbitrary binary data. .. versionadded:: 3.9 -.. method:: bytes.cutsuffix(suffix, /) - bytearray.cutsuffix(suffix, /) +.. method:: bytes.removesuffix(suffix, /) + bytearray.removesuffix(suffix, /) Return a copy of the binary data with the given suffix removed, if present. :: - >>> b'BarFooBaz'.cutsuffix(b'Baz') + >>> b'BarFooBaz'.removesuffix(b'Baz') b'BarFoo' - >>> b'BarFooBaz'.cutsuffix(b'Bar') + >>> b'BarFooBaz'.removesuffix(b'Bar') b'BarFooBaz' The *suffix* may be any :term:`bytes-like object`. - The expression ``b.cutsuffix(suf)`` is roughly equivalent to + The expression ``b.removesuffix(suf)`` is roughly equivalent to ``b[:-len(suf)] if suf and b.endswith(suf) else b[:]``. Unlike :meth:`~bytes.endswith`, only one suffix can be passed at a time. @@ -2919,7 +2919,7 @@ produce new objects. b'example.com' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. See :meth:`~bytes.cutprefix` for a method + :term:`bytes-like object`. See :meth:`~bytes.removeprefix` for a method that will remove a single prefix string rather than all of a set of characters. @@ -2970,7 +2970,7 @@ produce new objects. b'mississ' The binary sequence of byte values to remove may be any - :term:`bytes-like object`. See :meth:`~bytes.cutsuffix` for a method + :term:`bytes-like object`. See :meth:`~bytes.removesuffix` for a method that will remove a single suffix string rather than all of a set of characters. diff --git a/Lib/collections/__init__.py b/Lib/collections/__init__.py index 0fe03dbb7d13f5..f7d070dbe5b84e 100644 --- a/Lib/collections/__init__.py +++ b/Lib/collections/__init__.py @@ -1202,14 +1202,14 @@ def count(self, sub, start=0, end=_sys.maxsize): if isinstance(sub, UserString): sub = sub.data return self.data.count(sub, start, end) - def cutprefix(self, prefix, /): + def removeprefix(self, prefix, /): if isinstance(prefix, UserString): prefix = prefix.data - return self.__class__(self.data.cutprefix(prefix)) - def cutsuffix(self, suffix, /): + return self.__class__(self.data.removeprefix(prefix)) + def removesuffix(self, suffix, /): if isinstance(suffix, UserString): suffix = suffix.data - return self.__class__(self.data.cutsuffix(suffix)) + return self.__class__(self.data.removesuffix(suffix)) def encode(self, encoding='utf-8', errors='strict'): encoding = 'utf-8' if encoding is None else encoding errors = 'strict' if errors is None else errors diff --git a/Lib/test/string_tests.py b/Lib/test/string_tests.py index 60d9d7c25945b0..527f505c0169b3 100644 --- a/Lib/test/string_tests.py +++ b/Lib/test/string_tests.py @@ -682,41 +682,41 @@ def test_replace_overflow(self): self.checkraises(OverflowError, A2_16, "replace", "A", A2_16) self.checkraises(OverflowError, A2_16, "replace", "AA", A2_16+A2_16) - def test_cutprefix(self): - self.checkequal('am', 'spam', 'cutprefix', 'sp') - self.checkequal('spamspam', 'spamspamspam', 'cutprefix', 'spam') - self.checkequal('spam', 'spam', 'cutprefix', 'python') - self.checkequal('spam', 'spam', 'cutprefix', 'spider') - self.checkequal('spam', 'spam', 'cutprefix', 'spam and eggs') - - self.checkequal('', '', 'cutprefix', '') - self.checkequal('', '', 'cutprefix', 'abcde') - self.checkequal('abcde', 'abcde', 'cutprefix', '') - self.checkequal('', 'abcde', 'cutprefix', 'abcde') - - self.checkraises(TypeError, 'hello', 'cutprefix') - self.checkraises(TypeError, 'hello', 'cutprefix', 42) - self.checkraises(TypeError, 'hello', 'cutprefix', 42, 'h') - self.checkraises(TypeError, 'hello', 'cutprefix', 'h', 42) - self.checkraises(TypeError, 'hello', 'cutprefix', ("he", "l")) - - def test_cutsuffix(self): - self.checkequal('sp', 'spam', 'cutsuffix', 'am') - self.checkequal('spamspam', 'spamspamspam', 'cutsuffix', 'spam') - self.checkequal('spam', 'spam', 'cutsuffix', 'python') - self.checkequal('spam', 'spam', 'cutsuffix', 'blam') - self.checkequal('spam', 'spam', 'cutsuffix', 'eggs and spam') - - self.checkequal('', '', 'cutsuffix', '') - self.checkequal('', '', 'cutsuffix', 'abcde') - self.checkequal('abcde', 'abcde', 'cutsuffix', '') - self.checkequal('', 'abcde', 'cutsuffix', 'abcde') - - self.checkraises(TypeError, 'hello', 'cutsuffix') - self.checkraises(TypeError, 'hello', 'cutsuffix', 42) - self.checkraises(TypeError, 'hello', 'cutsuffix', 42, 'h') - self.checkraises(TypeError, 'hello', 'cutsuffix', 'h', 42) - self.checkraises(TypeError, 'hello', 'cutsuffix', ("lo", "l")) + def test_removeprefix(self): + self.checkequal('am', 'spam', 'removeprefix', 'sp') + self.checkequal('spamspam', 'spamspamspam', 'removeprefix', 'spam') + self.checkequal('spam', 'spam', 'removeprefix', 'python') + self.checkequal('spam', 'spam', 'removeprefix', 'spider') + self.checkequal('spam', 'spam', 'removeprefix', 'spam and eggs') + + self.checkequal('', '', 'removeprefix', '') + self.checkequal('', '', 'removeprefix', 'abcde') + self.checkequal('abcde', 'abcde', 'removeprefix', '') + self.checkequal('', 'abcde', 'removeprefix', 'abcde') + + self.checkraises(TypeError, 'hello', 'removeprefix') + self.checkraises(TypeError, 'hello', 'removeprefix', 42) + self.checkraises(TypeError, 'hello', 'removeprefix', 42, 'h') + self.checkraises(TypeError, 'hello', 'removeprefix', 'h', 42) + self.checkraises(TypeError, 'hello', 'removeprefix', ("he", "l")) + + def test_removesuffix(self): + self.checkequal('sp', 'spam', 'removesuffix', 'am') + self.checkequal('spamspam', 'spamspamspam', 'removesuffix', 'spam') + self.checkequal('spam', 'spam', 'removesuffix', 'python') + self.checkequal('spam', 'spam', 'removesuffix', 'blam') + self.checkequal('spam', 'spam', 'removesuffix', 'eggs and spam') + + self.checkequal('', '', 'removesuffix', '') + self.checkequal('', '', 'removesuffix', 'abcde') + self.checkequal('abcde', 'abcde', 'removesuffix', '') + self.checkequal('', 'abcde', 'removesuffix', 'abcde') + + self.checkraises(TypeError, 'hello', 'removesuffix') + self.checkraises(TypeError, 'hello', 'removesuffix', 42) + self.checkraises(TypeError, 'hello', 'removesuffix', 42, 'h') + self.checkraises(TypeError, 'hello', 'removesuffix', 'h', 42) + self.checkraises(TypeError, 'hello', 'removesuffix', ("lo", "l")) def test_capitalize(self): self.checkequal(' hello ', ' hello ', 'capitalize') diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index 48e7bba1a717db..8b2b0ebb313bd1 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1186,7 +1186,7 @@ bytearray_endswith(PyByteArrayObject *self, PyObject *args) } /*[clinic input] -bytearray.cutprefix as bytearray_cutprefix +bytearray.removeprefix as bytearray_removeprefix prefix: Py_buffer / @@ -1198,8 +1198,8 @@ Otherwise, return a copy of the original bytearray. [clinic start generated code]*/ static PyObject * -bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=21632e315d769b4b input=1848afa62344e091]*/ +bytearray_removeprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) +/*[clinic end generated code: output=6cabc585e7f502e0 input=4b4f34cda54a3c82]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); @@ -1217,7 +1217,7 @@ bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) } /*[clinic input] -bytearray.cutsuffix as bytearray_cutsuffix +bytearray.removesuffix as bytearray_removesuffix suffix: Py_buffer / @@ -1229,8 +1229,8 @@ Otherwise, return a copy of the original bytearray. [clinic start generated code]*/ static PyObject * -bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=9862e6f256b4e5a0 input=8f8c10709806b42b]*/ +bytearray_removesuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) +/*[clinic end generated code: output=2bc8cfb79de793d3 input=9e99a83e43aa6ed8]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); @@ -2270,8 +2270,8 @@ bytearray_methods[] = { BYTEARRAY_POP_METHODDEF BYTEARRAY_REMOVE_METHODDEF BYTEARRAY_REPLACE_METHODDEF - BYTEARRAY_CUTPREFIX_METHODDEF - BYTEARRAY_CUTSUFFIX_METHODDEF + BYTEARRAY_REMOVEPREFIX_METHODDEF + BYTEARRAY_REMOVESUFFIX_METHODDEF BYTEARRAY_REVERSE_METHODDEF {"rfind", (PyCFunction)bytearray_rfind, METH_VARARGS, _Py_rfind__doc__}, {"rindex", (PyCFunction)bytearray_rindex, METH_VARARGS, _Py_rindex__doc__}, diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 22116aa0c632cc..3e62cc02b7e479 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2182,7 +2182,7 @@ bytes_replace_impl(PyBytesObject *self, Py_buffer *old, Py_buffer *new, /** End DALKE **/ /*[clinic input] -bytes.cutprefix as bytes_cutprefix +bytes.removeprefix as bytes_removeprefix prefix: Py_buffer / @@ -2194,8 +2194,8 @@ Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * -bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=5e5ef0cf576a8a9c input=62efeb5116b52516]*/ +bytes_removeprefix_impl(PyBytesObject *self, Py_buffer *prefix) +/*[clinic end generated code: output=f006865331a06ab6 input=51ea1fc18687503e]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); @@ -2219,7 +2219,7 @@ bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix) } /*[clinic input] -bytes.cutsuffix as bytes_cutsuffix +bytes.removesuffix as bytes_removesuffix suffix: Py_buffer / @@ -2231,8 +2231,8 @@ Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * -bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=303549ce0a999724 input=afec1a85ea98d67f]*/ +bytes_removesuffix_impl(PyBytesObject *self, Py_buffer *suffix) +/*[clinic end generated code: output=d887d308e3242eeb input=9f6172d9ddad90cd]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); @@ -2494,8 +2494,8 @@ bytes_methods[] = { BYTES_MAKETRANS_METHODDEF BYTES_PARTITION_METHODDEF BYTES_REPLACE_METHODDEF - BYTES_CUTPREFIX_METHODDEF - BYTES_CUTSUFFIX_METHODDEF + BYTES_REMOVEPREFIX_METHODDEF + BYTES_REMOVESUFFIX_METHODDEF {"rfind", (PyCFunction)bytes_rfind, METH_VARARGS, _Py_rfind__doc__}, {"rindex", (PyCFunction)bytes_rindex, METH_VARARGS, _Py_rindex__doc__}, STRINGLIB_RJUST_METHODDEF diff --git a/Objects/clinic/bytearrayobject.c.h b/Objects/clinic/bytearrayobject.c.h index 90a886e9df515f..12ebba9b205ed8 100644 --- a/Objects/clinic/bytearrayobject.c.h +++ b/Objects/clinic/bytearrayobject.c.h @@ -38,8 +38,8 @@ bytearray_copy(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) return bytearray_copy_impl(self); } -PyDoc_STRVAR(bytearray_cutprefix__doc__, -"cutprefix($self, prefix, /)\n" +PyDoc_STRVAR(bytearray_removeprefix__doc__, +"removeprefix($self, prefix, /)\n" "--\n" "\n" "Return a copy of the bytearray with a given prefix removed if present.\n" @@ -47,14 +47,14 @@ PyDoc_STRVAR(bytearray_cutprefix__doc__, "If the bytearray starts with the prefix, return b[len(prefix):].\n" "Otherwise, return a copy of the original bytearray."); -#define BYTEARRAY_CUTPREFIX_METHODDEF \ - {"cutprefix", (PyCFunction)bytearray_cutprefix, METH_O, bytearray_cutprefix__doc__}, +#define BYTEARRAY_REMOVEPREFIX_METHODDEF \ + {"removeprefix", (PyCFunction)bytearray_removeprefix, METH_O, bytearray_removeprefix__doc__}, static PyObject * -bytearray_cutprefix_impl(PyByteArrayObject *self, Py_buffer *prefix); +bytearray_removeprefix_impl(PyByteArrayObject *self, Py_buffer *prefix); static PyObject * -bytearray_cutprefix(PyByteArrayObject *self, PyObject *arg) +bytearray_removeprefix(PyByteArrayObject *self, PyObject *arg) { PyObject *return_value = NULL; Py_buffer prefix = {NULL, NULL}; @@ -63,10 +63,10 @@ bytearray_cutprefix(PyByteArrayObject *self, PyObject *arg) goto exit; } if (!PyBuffer_IsContiguous(&prefix, 'C')) { - _PyArg_BadArgument("cutprefix", "argument", "contiguous buffer", arg); + _PyArg_BadArgument("removeprefix", "argument", "contiguous buffer", arg); goto exit; } - return_value = bytearray_cutprefix_impl(self, &prefix); + return_value = bytearray_removeprefix_impl(self, &prefix); exit: /* Cleanup for prefix */ @@ -77,8 +77,8 @@ bytearray_cutprefix(PyByteArrayObject *self, PyObject *arg) return return_value; } -PyDoc_STRVAR(bytearray_cutsuffix__doc__, -"cutsuffix($self, suffix, /)\n" +PyDoc_STRVAR(bytearray_removesuffix__doc__, +"removesuffix($self, suffix, /)\n" "--\n" "\n" "Return a copy of the bytearray with a given suffix removed if present.\n" @@ -86,14 +86,14 @@ PyDoc_STRVAR(bytearray_cutsuffix__doc__, "If the bytearray ends with the suffix, return b[:len(b)-len(suffix)].\n" "Otherwise, return a copy of the original bytearray."); -#define BYTEARRAY_CUTSUFFIX_METHODDEF \ - {"cutsuffix", (PyCFunction)bytearray_cutsuffix, METH_O, bytearray_cutsuffix__doc__}, +#define BYTEARRAY_REMOVESUFFIX_METHODDEF \ + {"removesuffix", (PyCFunction)bytearray_removesuffix, METH_O, bytearray_removesuffix__doc__}, static PyObject * -bytearray_cutsuffix_impl(PyByteArrayObject *self, Py_buffer *suffix); +bytearray_removesuffix_impl(PyByteArrayObject *self, Py_buffer *suffix); static PyObject * -bytearray_cutsuffix(PyByteArrayObject *self, PyObject *arg) +bytearray_removesuffix(PyByteArrayObject *self, PyObject *arg) { PyObject *return_value = NULL; Py_buffer suffix = {NULL, NULL}; @@ -102,10 +102,10 @@ bytearray_cutsuffix(PyByteArrayObject *self, PyObject *arg) goto exit; } if (!PyBuffer_IsContiguous(&suffix, 'C')) { - _PyArg_BadArgument("cutsuffix", "argument", "contiguous buffer", arg); + _PyArg_BadArgument("removesuffix", "argument", "contiguous buffer", arg); goto exit; } - return_value = bytearray_cutsuffix_impl(self, &suffix); + return_value = bytearray_removesuffix_impl(self, &suffix); exit: /* Cleanup for suffix */ @@ -1089,4 +1089,4 @@ bytearray_sizeof(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) { return bytearray_sizeof_impl(self); } -/*[clinic end generated code: output=e42aa99e5a589150 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=4ea3c2feebafe2d0 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index 587d0f2bb82cdf..4139b9057a2361 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -526,8 +526,8 @@ bytes_replace(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs) return return_value; } -PyDoc_STRVAR(bytes_cutprefix__doc__, -"cutprefix($self, prefix, /)\n" +PyDoc_STRVAR(bytes_removeprefix__doc__, +"removeprefix($self, prefix, /)\n" "--\n" "\n" "Remove a specified prefix, if present.\n" @@ -535,14 +535,14 @@ PyDoc_STRVAR(bytes_cutprefix__doc__, "If the bytes starts with the prefix, return b[len(prefix):].\n" "Otherwise, return a copy of the original bytes."); -#define BYTES_CUTPREFIX_METHODDEF \ - {"cutprefix", (PyCFunction)bytes_cutprefix, METH_O, bytes_cutprefix__doc__}, +#define BYTES_REMOVEPREFIX_METHODDEF \ + {"removeprefix", (PyCFunction)bytes_removeprefix, METH_O, bytes_removeprefix__doc__}, static PyObject * -bytes_cutprefix_impl(PyBytesObject *self, Py_buffer *prefix); +bytes_removeprefix_impl(PyBytesObject *self, Py_buffer *prefix); static PyObject * -bytes_cutprefix(PyBytesObject *self, PyObject *arg) +bytes_removeprefix(PyBytesObject *self, PyObject *arg) { PyObject *return_value = NULL; Py_buffer prefix = {NULL, NULL}; @@ -551,10 +551,10 @@ bytes_cutprefix(PyBytesObject *self, PyObject *arg) goto exit; } if (!PyBuffer_IsContiguous(&prefix, 'C')) { - _PyArg_BadArgument("cutprefix", "argument", "contiguous buffer", arg); + _PyArg_BadArgument("removeprefix", "argument", "contiguous buffer", arg); goto exit; } - return_value = bytes_cutprefix_impl(self, &prefix); + return_value = bytes_removeprefix_impl(self, &prefix); exit: /* Cleanup for prefix */ @@ -565,8 +565,8 @@ bytes_cutprefix(PyBytesObject *self, PyObject *arg) return return_value; } -PyDoc_STRVAR(bytes_cutsuffix__doc__, -"cutsuffix($self, suffix, /)\n" +PyDoc_STRVAR(bytes_removesuffix__doc__, +"removesuffix($self, suffix, /)\n" "--\n" "\n" "Remove a specified suffix, if present.\n" @@ -574,14 +574,14 @@ PyDoc_STRVAR(bytes_cutsuffix__doc__, "If the bytes ends with the suffix, return b[:len(b)-len(prefix)].\n" "Otherwise, return a copy of the original bytes."); -#define BYTES_CUTSUFFIX_METHODDEF \ - {"cutsuffix", (PyCFunction)bytes_cutsuffix, METH_O, bytes_cutsuffix__doc__}, +#define BYTES_REMOVESUFFIX_METHODDEF \ + {"removesuffix", (PyCFunction)bytes_removesuffix, METH_O, bytes_removesuffix__doc__}, static PyObject * -bytes_cutsuffix_impl(PyBytesObject *self, Py_buffer *suffix); +bytes_removesuffix_impl(PyBytesObject *self, Py_buffer *suffix); static PyObject * -bytes_cutsuffix(PyBytesObject *self, PyObject *arg) +bytes_removesuffix(PyBytesObject *self, PyObject *arg) { PyObject *return_value = NULL; Py_buffer suffix = {NULL, NULL}; @@ -590,10 +590,10 @@ bytes_cutsuffix(PyBytesObject *self, PyObject *arg) goto exit; } if (!PyBuffer_IsContiguous(&suffix, 'C')) { - _PyArg_BadArgument("cutsuffix", "argument", "contiguous buffer", arg); + _PyArg_BadArgument("removesuffix", "argument", "contiguous buffer", arg); goto exit; } - return_value = bytes_cutsuffix_impl(self, &suffix); + return_value = bytes_removesuffix_impl(self, &suffix); exit: /* Cleanup for suffix */ @@ -833,4 +833,4 @@ bytes_hex(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=377e6c8757a80baa input=a9049054013a1b77]*/ +/*[clinic end generated code: output=bff31a7956db2561 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index 41fb19b088f9d8..d8a755cfd6bb33 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -754,8 +754,8 @@ unicode_replace(PyObject *self, PyObject *const *args, Py_ssize_t nargs) return return_value; } -PyDoc_STRVAR(unicode_cutprefix__doc__, -"cutprefix($self, prefix, /)\n" +PyDoc_STRVAR(unicode_removeprefix__doc__, +"removeprefix($self, prefix, /)\n" "--\n" "\n" "Remove a specified prefix, if present.\n" @@ -763,34 +763,34 @@ PyDoc_STRVAR(unicode_cutprefix__doc__, "If the string starts with the prefix, return string[len(prefix):].\n" "Otherwise, return a copy of the original string."); -#define UNICODE_CUTPREFIX_METHODDEF \ - {"cutprefix", (PyCFunction)unicode_cutprefix, METH_O, unicode_cutprefix__doc__}, +#define UNICODE_REMOVEPREFIX_METHODDEF \ + {"removeprefix", (PyCFunction)unicode_removeprefix, METH_O, unicode_removeprefix__doc__}, static PyObject * -unicode_cutprefix_impl(PyObject *self, PyObject *prefix); +unicode_removeprefix_impl(PyObject *self, PyObject *prefix); static PyObject * -unicode_cutprefix(PyObject *self, PyObject *arg) +unicode_removeprefix(PyObject *self, PyObject *arg) { PyObject *return_value = NULL; PyObject *prefix; if (!PyUnicode_Check(arg)) { - _PyArg_BadArgument("cutprefix", "argument", "str", arg); + _PyArg_BadArgument("removeprefix", "argument", "str", arg); goto exit; } if (PyUnicode_READY(arg) == -1) { goto exit; } prefix = arg; - return_value = unicode_cutprefix_impl(self, prefix); + return_value = unicode_removeprefix_impl(self, prefix); exit: return return_value; } -PyDoc_STRVAR(unicode_cutsuffix__doc__, -"cutsuffix($self, suffix, /)\n" +PyDoc_STRVAR(unicode_removesuffix__doc__, +"removesuffix($self, suffix, /)\n" "--\n" "\n" "Remove a specified suffix, if present.\n" @@ -798,27 +798,27 @@ PyDoc_STRVAR(unicode_cutsuffix__doc__, "If the string ends with the suffix, return string[:len(string)-len(suffix)].\n" "Otherwise, return a copy of the original string."); -#define UNICODE_CUTSUFFIX_METHODDEF \ - {"cutsuffix", (PyCFunction)unicode_cutsuffix, METH_O, unicode_cutsuffix__doc__}, +#define UNICODE_REMOVESUFFIX_METHODDEF \ + {"removesuffix", (PyCFunction)unicode_removesuffix, METH_O, unicode_removesuffix__doc__}, static PyObject * -unicode_cutsuffix_impl(PyObject *self, PyObject *suffix); +unicode_removesuffix_impl(PyObject *self, PyObject *suffix); static PyObject * -unicode_cutsuffix(PyObject *self, PyObject *arg) +unicode_removesuffix(PyObject *self, PyObject *arg) { PyObject *return_value = NULL; PyObject *suffix; if (!PyUnicode_Check(arg)) { - _PyArg_BadArgument("cutsuffix", "argument", "str", arg); + _PyArg_BadArgument("removesuffix", "argument", "str", arg); goto exit; } if (PyUnicode_READY(arg) == -1) { goto exit; } suffix = arg; - return_value = unicode_cutsuffix_impl(self, suffix); + return_value = unicode_removesuffix_impl(self, suffix); exit: return return_value; @@ -1302,4 +1302,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return unicode_sizeof_impl(self); } -/*[clinic end generated code: output=db94a0ba79ae9c95 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=246ebcf168b1492c input=a9049054013a1b77]*/ diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 2aac05714455fc..fe1741ed4c2026 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12758,7 +12758,7 @@ unicode_replace_impl(PyObject *self, PyObject *old, PyObject *new, } /*[clinic input] -str.cutprefix as unicode_cutprefix +str.removeprefix as unicode_removeprefix prefix: unicode / @@ -12770,8 +12770,8 @@ Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * -unicode_cutprefix_impl(PyObject *self, PyObject *prefix) -/*[clinic end generated code: output=885902e3c7f5fae0 input=adf93aba99de6d2b]*/ +unicode_removeprefix_impl(PyObject *self, PyObject *prefix) +/*[clinic end generated code: output=f1e5945e9763bcb9 input=9aeb1706f08ce2cf]*/ { int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); if (match == -1) { @@ -12785,7 +12785,7 @@ unicode_cutprefix_impl(PyObject *self, PyObject *prefix) } /*[clinic input] -str.cutsuffix as unicode_cutsuffix +str.removesuffix as unicode_removesuffix suffix: unicode / @@ -12797,8 +12797,8 @@ Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * -unicode_cutsuffix_impl(PyObject *self, PyObject *suffix) -/*[clinic end generated code: output=5e5babcd284e6e6e input=cdfb4cb7d8a27164]*/ +unicode_removesuffix_impl(PyObject *self, PyObject *suffix) +/*[clinic end generated code: output=d36629e227636822 input=ed89a10ab150499c]*/ { int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); if (match == -1) { @@ -14124,8 +14124,8 @@ static PyMethodDef unicode_methods[] = { UNICODE_UPPER_METHODDEF {"startswith", (PyCFunction) unicode_startswith, METH_VARARGS, startswith__doc__}, {"endswith", (PyCFunction) unicode_endswith, METH_VARARGS, endswith__doc__}, - UNICODE_CUTPREFIX_METHODDEF - UNICODE_CUTSUFFIX_METHODDEF + UNICODE_REMOVEPREFIX_METHODDEF + UNICODE_REMOVESUFFIX_METHODDEF UNICODE_ISASCII_METHODDEF UNICODE_ISLOWER_METHODDEF UNICODE_ISUPPER_METHODDEF From 4413e2efe036599896b1f0196768c4c5b53990af Mon Sep 17 00:00:00 2001 From: sweeneyde <36520290+sweeneyde@users.noreply.github.com> Date: Wed, 25 Mar 2020 19:18:16 -0400 Subject: [PATCH 27/35] Change method names in whatsnew --- Doc/whatsnew/3.9.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index 56958e99f4bad1..d5de04f78c78c1 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -107,7 +107,7 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in cutprefix and cutsuffix methods for strings ------------------------------------------- -``str.cutprefix(prefix)`` and ``str.cutsuffix(suffix)`` have been added to +``str.removeprefix(prefix)`` and ``str.removesuffix(suffix)`` have been added to easily remove an unneeded prefix or a suffix from a string. Corresponding ``bytes`` and ``bytearray`` methods have also been added. (Contributed by Dennis Sweeney in :issue:`18939`.) From 5dfa96851c954c9bac8ff0a12c1cd8380ef1c599 Mon Sep 17 00:00:00 2001 From: sweeneyde <36520290+sweeneyde@users.noreply.github.com> Date: Wed, 25 Mar 2020 19:18:49 -0400 Subject: [PATCH 28/35] Update Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst Change method names in NEWS --- .../Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst index 6e514128743291..fd2ce97d9f267c 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst @@ -1 +1 @@ -Added str.cutprefix and str.cutsuffix methods and corresponding bytes and bytearray methods to cut affixes off of a string, if present. Patch by Dennis Sweeney. +Added str.removeprefix and str.removesuffix methods and corresponding bytes and bytearray methods to remove affixes from a string if present. Patch by Dennis Sweeney. From aa6eedec65c68e7d34fae585d8750afad3256b26 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Fri, 27 Mar 2020 20:57:07 -0400 Subject: [PATCH 29/35] new names in the whatsnew header --- Doc/whatsnew/3.9.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index d5de04f78c78c1..7e407942e7d0dc 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -105,8 +105,8 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in :class:`dict` class. See :pep:`584` for a full description. (Contributed by Brandt Bucher in :issue:`36144`.) -cutprefix and cutsuffix methods for strings -------------------------------------------- +removeprefix and removesuffix methods for strings +------------------------------------------------- ``str.removeprefix(prefix)`` and ``str.removesuffix(suffix)`` have been added to easily remove an unneeded prefix or a suffix from a string. Corresponding ``bytes`` and ``bytearray`` methods have also been added. From f55836d764da79fe596b44be163794bc8da535ba Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Tue, 21 Apr 2020 03:06:52 -0400 Subject: [PATCH 30/35] add examples of differences between l/rstrip and removeaffix --- Doc/library/stdtypes.rst | 28 ++++++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 0ee9592b98c848..8f25de56483ec8 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1865,7 +1865,12 @@ expression support in the :mod:`re` module). 'example.com' See :meth:`str.removeprefix` for a method that will remove a single prefix - string rather than all of a set of characters. + string rather than all of a set of characters. For example:: + + >>> 'Arthur: three!'.lstrip('Arthur: ') + 'ee!' + >>> 'Arthur: three!'.removeprefix('Arthur: ') + 'three!' .. staticmethod:: str.maketrans(x[, y[, z]]) @@ -1948,7 +1953,12 @@ expression support in the :mod:`re` module). 'mississ' See :meth:`str.removesuffix` for a method that will remove a single suffix - string rather than all of a set of characters. + string rather than all of a set of characters. For example:: + + >>> 'Monty Python'.rstrip(' Python') + 'M' + >>> 'Monty Python'.removesuffix(' Python') + 'Monty' .. method:: str.split(sep=None, maxsplit=-1) @@ -2921,7 +2931,12 @@ produce new objects. The binary sequence of byte values to remove may be any :term:`bytes-like object`. See :meth:`~bytes.removeprefix` for a method that will remove a single prefix string rather than all of a set of - characters. + characters. For example:: + + >>> b'Monty Python'.rstrip(b' Python') + b'M' + >>> b'Monty Python'.removesuffix(b' Python') + b'Monty' .. note:: @@ -2972,7 +2987,12 @@ produce new objects. The binary sequence of byte values to remove may be any :term:`bytes-like object`. See :meth:`~bytes.removesuffix` for a method that will remove a single suffix string rather than all of a set of - characters. + characters. For example:: + + >>> b'Arthur: three!'.lstrip(b'Arthur: ') + b'ee!' + >>> b'Arthur: three!'.removeprefix(b'Arthur: ') + b'three!' .. note:: From 8b6267aff016f916b8f44cd8b4ac99b39ff5b28e Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 22 Apr 2020 04:15:12 -0400 Subject: [PATCH 31/35] apply changes from review --- Doc/library/stdtypes.rst | 92 +++++++++---------- Doc/whatsnew/3.9.rst | 10 +- .../2020-03-11-19-17-36.bpo-39939.NwCnAM.rst | 2 +- 3 files changed, 51 insertions(+), 53 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 4efcaf3fc801ec..2f42a5b343f777 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1551,33 +1551,26 @@ expression support in the :mod:`re` module). .. method:: str.removeprefix(prefix, /) - Return a copy of the string with the given prefix removed, if present. :: + If the string starts with the prefix, return ``string[len(prefix):]``. + Otherwise, return a copy of the original string:: - >>> 'BarFooBaz'.removeprefix('Bar') - 'FooBaz' - >>> 'BarFooBaz'.removeprefix('Baz') - 'BarFooBaz' - - The expression ``s.removeprefix(pre)`` is roughly equivalent to - ``s[len(pre):] if s.startswith(pre) else s``. - Unlike :meth:`~str.startswith`, only one prefix can be passed - at a time. + >>> 'TestHook'.removeprefix('Test') + 'Hook' + >>> 'BaseTestCase'.removeprefix('Test') + 'BaseTestCase' .. versionadded:: 3.9 .. method:: str.removesuffix(suffix, /) - Return a copy of the string with the given suffix removed, if present. :: - - >>> 'BarFooBaz'.removesuffix('Baz') - 'BarFoo' - >>> 'BarFooBaz'.removesuffix('Bar') - 'BarFooBaz' + If the string ends with the suffix, return + ``string[:len(string)-len(suffix)]``. Otherwise, return a copy of the + original string:: - The expression ``s.removesuffix(suf)`` is roughly equivalent to - ``s[:-len(suf)] if suf and s.endswith(suf) else s``. - Unlike :meth:`~str.endswith`, only one suffix can be passed - at a time. + >>> 'MiscTests'.removesuffix('Tests') + 'Misc' + >>> 'TmpDirMixin'.removesuffix('Tests') + 'TmpDirMixin' .. versionadded:: 3.9 @@ -2642,19 +2635,20 @@ arbitrary binary data. .. method:: bytes.removeprefix(prefix, /) bytearray.removeprefix(prefix, /) - Return a copy of the binary data with the given prefix removed, - if present. :: + If the binary data starts with the *prefix*, return ``b[len(prefix):]``. + Otherwise, return a copy of the original binary data:: - >>> b'BarFooBaz'.removeprefix(b'Bar') - b'FooBaz' - >>> b'BarFooBaz'.removeprefix(b'Baz') - b'BarFooBaz' + >>> b'TestHook'.removeprefix(b'Test') + b'Hook' + >>> b'BaseTestCase'.removeprefix(b'Test') + b'BaseTestCase' The *prefix* may be any :term:`bytes-like object`. - The expression ``b.removeprefix(pre)`` is roughly equivalent to - ``b[len(pre):] if b.startswith(pre) else b[:]``. - Unlike :meth:`~bytes.startswith`, only one prefix can be passed - at a time. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. .. versionadded:: 3.9 @@ -2662,19 +2656,21 @@ arbitrary binary data. .. method:: bytes.removesuffix(suffix, /) bytearray.removesuffix(suffix, /) - Return a copy of the binary data with the given suffix removed, - if present. :: + If the binary data ends with the *suffix*, return + ``b[:len(b)-len(prefix)]``. Otherwise, return a copy of the original + binary data:: - >>> b'BarFooBaz'.removesuffix(b'Baz') - b'BarFoo' - >>> b'BarFooBaz'.removesuffix(b'Bar') - b'BarFooBaz' + >>> b'MiscTests'.removesuffix(b'Tests') + b'Misc' + >>> b'TmpDirMixin'.removesuffix(b'Tests') + b'TmpDirMixin' The *suffix* may be any :term:`bytes-like object`. - The expression ``b.removesuffix(suf)`` is roughly equivalent to - ``b[:-len(suf)] if suf and b.endswith(suf) else b[:]``. - Unlike :meth:`~bytes.endswith`, only one suffix can be passed - at a time. + + .. note:: + + The bytearray version of this method does *not* operate in place - + it always produces a new object, even if no changes were made. .. versionadded:: 3.9 @@ -2933,10 +2929,10 @@ produce new objects. that will remove a single prefix string rather than all of a set of characters. For example:: - >>> b'Monty Python'.rstrip(b' Python') - b'M' - >>> b'Monty Python'.removesuffix(b' Python') - b'Monty' + >>> b'Arthur: three!'.lstrip(b'Arthur: ') + b'ee!' + >>> b'Arthur: three!'.removeprefix(b'Arthur: ') + b'three!' .. note:: @@ -2989,10 +2985,10 @@ produce new objects. that will remove a single suffix string rather than all of a set of characters. For example:: - >>> b'Arthur: three!'.lstrip(b'Arthur: ') - b'ee!' - >>> b'Arthur: three!'.removeprefix(b'Arthur: ') - b'three!' + >>> b'Monty Python'.rstrip(b' Python') + b'M' + >>> b'Monty Python'.removesuffix(b' Python') + b'Monty' .. note:: diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index 43fccc72dc4c29..a22c1d22856abf 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -107,10 +107,12 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in removeprefix and removesuffix methods for strings ------------------------------------------------- -``str.removeprefix(prefix)`` and ``str.removesuffix(suffix)`` have been added to -easily remove an unneeded prefix or a suffix from a string. Corresponding -``bytes`` and ``bytearray`` methods have also been added. -(Contributed by Dennis Sweeney in :issue:`18939`.) + +``str.removeprefix(prefix)`` and ``str.removesuffix(suffix)`` have been added +to easily remove an unneeded prefix or a suffix from a string. Corresponding +``bytes``, ``bytearray``, and ``collections.UserString`` methods have also been +added. See :pep:`616` for a full description (Contributed by Dennis Sweeney in +:issue:`18939`.) Other Language Changes diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst index fd2ce97d9f267c..edd4febda306ce 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst @@ -1 +1 @@ -Added str.removeprefix and str.removesuffix methods and corresponding bytes and bytearray methods to remove affixes from a string if present. Patch by Dennis Sweeney. +Added str.removeprefix and str.removesuffix methods and corresponding bytes, bytearray, and collections.UserString methods to remove affixes from a string if present. See PEP 616 for a full description. Patch by Dennis Sweeney. From 61cd530e4942733e6b6c2902c2fbecc46f8ea653 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 22 Apr 2020 04:27:31 -0400 Subject: [PATCH 32/35] apply changes from review --- Doc/library/stdtypes.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 2f42a5b343f777..ddb7ff48f1c3ee 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1551,8 +1551,9 @@ expression support in the :mod:`re` module). .. method:: str.removeprefix(prefix, /) - If the string starts with the prefix, return ``string[len(prefix):]``. - Otherwise, return a copy of the original string:: + If the string starts with the *prefix* string, return + ``string[len(prefix):]``. Otherwise, return a copy of the original + string:: >>> 'TestHook'.removeprefix('Test') 'Hook' @@ -1563,7 +1564,7 @@ expression support in the :mod:`re` module). .. method:: str.removesuffix(suffix, /) - If the string ends with the suffix, return + If the string ends with the *suffix* string, return ``string[:len(string)-len(suffix)]``. Otherwise, return a copy of the original string:: From ffe72f1fe7697d2b20feb7686bb6b84a343430d2 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 22 Apr 2020 14:51:45 -0400 Subject: [PATCH 33/35] more documentation tweaks --- Doc/library/stdtypes.rst | 15 ++++++++------- Doc/whatsnew/3.9.rst | 9 +++++---- Objects/bytearrayobject.c | 15 ++++++++------- Objects/bytesobject.c | 12 ++++++------ Objects/clinic/bytearrayobject.c.h | 13 +++++++------ Objects/clinic/bytesobject.c.h | 10 +++++----- Objects/clinic/unicodeobject.c.h | 10 +++++----- Objects/unicodeobject.c | 12 ++++++------ 8 files changed, 50 insertions(+), 46 deletions(-) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index ddb7ff48f1c3ee..4e7729c83f49a4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1564,8 +1564,8 @@ expression support in the :mod:`re` module). .. method:: str.removesuffix(suffix, /) - If the string ends with the *suffix* string, return - ``string[:len(string)-len(suffix)]``. Otherwise, return a copy of the + If the string ends with the *suffix* string and that *suffix* is not empty, + return ``string[:-len(suffix)]``. Otherwise, return a copy of the original string:: >>> 'MiscTests'.removesuffix('Tests') @@ -2636,8 +2636,9 @@ arbitrary binary data. .. method:: bytes.removeprefix(prefix, /) bytearray.removeprefix(prefix, /) - If the binary data starts with the *prefix*, return ``b[len(prefix):]``. - Otherwise, return a copy of the original binary data:: + If the binary data starts with the *prefix* string, return + ``bytes[len(prefix):]``. Otherwise, return a copy of the original + binary data:: >>> b'TestHook'.removeprefix(b'Test') b'Hook' @@ -2657,9 +2658,9 @@ arbitrary binary data. .. method:: bytes.removesuffix(suffix, /) bytearray.removesuffix(suffix, /) - If the binary data ends with the *suffix*, return - ``b[:len(b)-len(prefix)]``. Otherwise, return a copy of the original - binary data:: + If the binary data ends with the *suffix* string and that *suffix* is + not empty, return ``bytes[:-len(suffix)]``. Otherwise, return a copy of + the original binary data:: >>> b'MiscTests'.removesuffix(b'Tests') b'Misc' diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst index a22c1d22856abf..c8de678b24f032 100644 --- a/Doc/whatsnew/3.9.rst +++ b/Doc/whatsnew/3.9.rst @@ -105,13 +105,14 @@ Merge (``|``) and update (``|=``) operators have been added to the built-in :class:`dict` class. See :pep:`584` for a full description. (Contributed by Brandt Bucher in :issue:`36144`.) -removeprefix and removesuffix methods for strings -------------------------------------------------- +PEP 616: New removeprefix() and removesuffix() string methods +------------------------------------------------------------- -``str.removeprefix(prefix)`` and ``str.removesuffix(suffix)`` have been added +:meth:`str.removeprefix(prefix)` and +:meth:`str.removesuffix(suffix)` have been added to easily remove an unneeded prefix or a suffix from a string. Corresponding ``bytes``, ``bytearray``, and ``collections.UserString`` methods have also been -added. See :pep:`616` for a full description (Contributed by Dennis Sweeney in +added. See :pep:`616` for a full description. (Contributed by Dennis Sweeney in :issue:`18939`.) diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index 5476a84d87c1d5..1c2ddc33d6ab7f 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1192,15 +1192,15 @@ bytearray.removeprefix as bytearray_removeprefix prefix: Py_buffer / -Return a copy of the bytearray with a given prefix removed if present. +Return a bytearray with the given prefix string removed if present. -If the bytearray starts with the prefix, return b[len(prefix):]. +If the bytearray starts with the prefix, return bytearray[len(prefix):]. Otherwise, return a copy of the original bytearray. [clinic start generated code]*/ static PyObject * bytearray_removeprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=6cabc585e7f502e0 input=4b4f34cda54a3c82]*/ +/*[clinic end generated code: output=6cabc585e7f502e0 input=431c03722532cba5]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); @@ -1223,15 +1223,16 @@ bytearray.removesuffix as bytearray_removesuffix suffix: Py_buffer / -Return a copy of the bytearray with a given suffix removed if present. +Return a bytearray with the given suffix string removed if present. -If the bytearray ends with the suffix, return b[:len(b)-len(suffix)]. -Otherwise, return a copy of the original bytearray. +If the bytearray ends with the suffix string and the suffix is not +empty, return bytearray[:-len(suffix)]. Otherwise, return a copy of +the original bytearray. [clinic start generated code]*/ static PyObject * bytearray_removesuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=2bc8cfb79de793d3 input=9e99a83e43aa6ed8]*/ +/*[clinic end generated code: output=2bc8cfb79de793d3 input=e4155e07c8629473]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index 9d41ef04cd5233..daab561f2575d3 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2188,7 +2188,7 @@ bytes.removeprefix as bytes_removeprefix prefix: Py_buffer / -Remove a specified prefix, if present. +Return a bytes object with the given prefix string removed if present. If the bytes starts with the prefix, return b[len(prefix):]. Otherwise, return a copy of the original bytes. @@ -2196,7 +2196,7 @@ Otherwise, return a copy of the original bytes. static PyObject * bytes_removeprefix_impl(PyBytesObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=f006865331a06ab6 input=51ea1fc18687503e]*/ +/*[clinic end generated code: output=f006865331a06ab6 input=24f4dccc70a6e388]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); @@ -2225,15 +2225,15 @@ bytes.removesuffix as bytes_removesuffix suffix: Py_buffer / -Remove a specified suffix, if present. +Return a bytes object with the given suffix string removed if present. -If the bytes ends with the suffix, return b[:len(b)-len(prefix)]. -Otherwise, return a copy of the original bytes. +If the bytes ends with the suffix and the suffix is not empty, return +b[:-len(prefix)]. Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * bytes_removesuffix_impl(PyBytesObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=d887d308e3242eeb input=9f6172d9ddad90cd]*/ +/*[clinic end generated code: output=d887d308e3242eeb input=b0128a19cd0453ef]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); diff --git a/Objects/clinic/bytearrayobject.c.h b/Objects/clinic/bytearrayobject.c.h index 12ebba9b205ed8..1e8e5e8f31b22e 100644 --- a/Objects/clinic/bytearrayobject.c.h +++ b/Objects/clinic/bytearrayobject.c.h @@ -42,9 +42,9 @@ PyDoc_STRVAR(bytearray_removeprefix__doc__, "removeprefix($self, prefix, /)\n" "--\n" "\n" -"Return a copy of the bytearray with a given prefix removed if present.\n" +"Return a bytearray with the given prefix string removed if present.\n" "\n" -"If the bytearray starts with the prefix, return b[len(prefix):].\n" +"If the bytearray starts with the prefix, return bytearray[len(prefix):].\n" "Otherwise, return a copy of the original bytearray."); #define BYTEARRAY_REMOVEPREFIX_METHODDEF \ @@ -81,10 +81,11 @@ PyDoc_STRVAR(bytearray_removesuffix__doc__, "removesuffix($self, suffix, /)\n" "--\n" "\n" -"Return a copy of the bytearray with a given suffix removed if present.\n" +"Return a bytearray with the given suffix string removed if present.\n" "\n" -"If the bytearray ends with the suffix, return b[:len(b)-len(suffix)].\n" -"Otherwise, return a copy of the original bytearray."); +"If the bytearray ends with the suffix string and the suffix is not\n" +"empty, return bytearray[:-len(suffix)]. Otherwise, return a copy of\n" +"the original bytearray."); #define BYTEARRAY_REMOVESUFFIX_METHODDEF \ {"removesuffix", (PyCFunction)bytearray_removesuffix, METH_O, bytearray_removesuffix__doc__}, @@ -1089,4 +1090,4 @@ bytearray_sizeof(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) { return bytearray_sizeof_impl(self); } -/*[clinic end generated code: output=4ea3c2feebafe2d0 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=8b7b311d194a75f8 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index 4139b9057a2361..adaf79943c87da 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -530,7 +530,7 @@ PyDoc_STRVAR(bytes_removeprefix__doc__, "removeprefix($self, prefix, /)\n" "--\n" "\n" -"Remove a specified prefix, if present.\n" +"Return a bytes object with the given prefix string removed if present.\n" "\n" "If the bytes starts with the prefix, return b[len(prefix):].\n" "Otherwise, return a copy of the original bytes."); @@ -569,10 +569,10 @@ PyDoc_STRVAR(bytes_removesuffix__doc__, "removesuffix($self, suffix, /)\n" "--\n" "\n" -"Remove a specified suffix, if present.\n" +"Return a bytes object with the given suffix string removed if present.\n" "\n" -"If the bytes ends with the suffix, return b[:len(b)-len(prefix)].\n" -"Otherwise, return a copy of the original bytes."); +"If the bytes ends with the suffix and the suffix is not empty, return\n" +"b[:-len(prefix)]. Otherwise, return a copy of the original bytes."); #define BYTES_REMOVESUFFIX_METHODDEF \ {"removesuffix", (PyCFunction)bytes_removesuffix, METH_O, bytes_removesuffix__doc__}, @@ -833,4 +833,4 @@ bytes_hex(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=bff31a7956db2561 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=cdee4f315f08f207 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index d8a755cfd6bb33..fadc27fe492704 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -758,7 +758,7 @@ PyDoc_STRVAR(unicode_removeprefix__doc__, "removeprefix($self, prefix, /)\n" "--\n" "\n" -"Remove a specified prefix, if present.\n" +"Return a str with the given prefix string removed if present.\n" "\n" "If the string starts with the prefix, return string[len(prefix):].\n" "Otherwise, return a copy of the original string."); @@ -793,10 +793,10 @@ PyDoc_STRVAR(unicode_removesuffix__doc__, "removesuffix($self, suffix, /)\n" "--\n" "\n" -"Remove a specified suffix, if present.\n" +"Return a str with the given suffix string removed if present.\n" "\n" -"If the string ends with the suffix, return string[:len(string)-len(suffix)].\n" -"Otherwise, return a copy of the original string."); +"If the string ends with the suffix and the suffix is not empty, return\n" +"string[:-len(suffix)]. Otherwise, return a copy of the original string."); #define UNICODE_REMOVESUFFIX_METHODDEF \ {"removesuffix", (PyCFunction)unicode_removesuffix, METH_O, unicode_removesuffix__doc__}, @@ -1302,4 +1302,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return unicode_sizeof_impl(self); } -/*[clinic end generated code: output=246ebcf168b1492c input=a9049054013a1b77]*/ +/*[clinic end generated code: output=3026a75c0aed4d6f input=a9049054013a1b77]*/ diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 3c12fdebfd720b..2737288b1c3f12 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12767,7 +12767,7 @@ str.removeprefix as unicode_removeprefix prefix: unicode / -Remove a specified prefix, if present. +Return a str with the given prefix string removed if present. If the string starts with the prefix, return string[len(prefix):]. Otherwise, return a copy of the original string. @@ -12775,7 +12775,7 @@ Otherwise, return a copy of the original string. static PyObject * unicode_removeprefix_impl(PyObject *self, PyObject *prefix) -/*[clinic end generated code: output=f1e5945e9763bcb9 input=9aeb1706f08ce2cf]*/ +/*[clinic end generated code: output=f1e5945e9763bcb9 input=59b55b6fa49a46b5]*/ { int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); if (match == -1) { @@ -12794,15 +12794,15 @@ str.removesuffix as unicode_removesuffix suffix: unicode / -Remove a specified suffix, if present. +Return a str with the given suffix string removed if present. -If the string ends with the suffix, return string[:len(string)-len(suffix)]. -Otherwise, return a copy of the original string. +If the string ends with the suffix and the suffix is not empty, return +string[:-len(suffix)]. Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * unicode_removesuffix_impl(PyObject *self, PyObject *suffix) -/*[clinic end generated code: output=d36629e227636822 input=ed89a10ab150499c]*/ +/*[clinic end generated code: output=d36629e227636822 input=50db6c0aa0f82736]*/ { int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); if (match == -1) { From d8f5a999e6d3f236be9a63cc8307eb10644d2013 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 22 Apr 2020 15:30:49 -0400 Subject: [PATCH 34/35] clean up the NEWS entry --- .../2020-03-11-19-17-36.bpo-39939.NwCnAM.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst index edd4febda306ce..bf094f1ce9b9b5 100644 --- a/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst +++ b/Misc/NEWS.d/next/Core and Builtins/2020-03-11-19-17-36.bpo-39939.NwCnAM.rst @@ -1 +1,5 @@ -Added str.removeprefix and str.removesuffix methods and corresponding bytes, bytearray, and collections.UserString methods to remove affixes from a string if present. See PEP 616 for a full description. Patch by Dennis Sweeney. +Added str.removeprefix and str.removesuffix methods and corresponding +bytes, bytearray, and collections.UserString methods to remove affixes +from a string if present. +See :pep:`616` for a full description. +Patch by Dennis Sweeney. From 3df1f38aad2aaa71410297c1f6aa0272e0a9bb15 Mon Sep 17 00:00:00 2001 From: sweeneyde Date: Wed, 22 Apr 2020 15:50:31 -0400 Subject: [PATCH 35/35] mention arg type in docstrings --- Objects/bytearrayobject.c | 11 ++++++----- Objects/bytesobject.c | 11 ++++++----- Objects/clinic/bytearrayobject.c.h | 9 +++++---- Objects/clinic/bytesobject.c.h | 9 +++++---- Objects/clinic/unicodeobject.c.h | 9 +++++---- Objects/unicodeobject.c | 11 ++++++----- 6 files changed, 33 insertions(+), 27 deletions(-) diff --git a/Objects/bytearrayobject.c b/Objects/bytearrayobject.c index 1c2ddc33d6ab7f..9805fa9c89e6ab 100644 --- a/Objects/bytearrayobject.c +++ b/Objects/bytearrayobject.c @@ -1194,13 +1194,14 @@ bytearray.removeprefix as bytearray_removeprefix Return a bytearray with the given prefix string removed if present. -If the bytearray starts with the prefix, return bytearray[len(prefix):]. -Otherwise, return a copy of the original bytearray. +If the bytearray starts with the prefix string, return +bytearray[len(prefix):]. Otherwise, return a copy of the original +bytearray. [clinic start generated code]*/ static PyObject * bytearray_removeprefix_impl(PyByteArrayObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=6cabc585e7f502e0 input=431c03722532cba5]*/ +/*[clinic end generated code: output=6cabc585e7f502e0 input=968aada38aedd262]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); @@ -1225,14 +1226,14 @@ bytearray.removesuffix as bytearray_removesuffix Return a bytearray with the given suffix string removed if present. -If the bytearray ends with the suffix string and the suffix is not +If the bytearray ends with the suffix string and that suffix is not empty, return bytearray[:-len(suffix)]. Otherwise, return a copy of the original bytearray. [clinic start generated code]*/ static PyObject * bytearray_removesuffix_impl(PyByteArrayObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=2bc8cfb79de793d3 input=e4155e07c8629473]*/ +/*[clinic end generated code: output=2bc8cfb79de793d3 input=c1827e810b2f6b99]*/ { const char *self_start = PyByteArray_AS_STRING(self); Py_ssize_t self_len = PyByteArray_GET_SIZE(self); diff --git a/Objects/bytesobject.c b/Objects/bytesobject.c index daab561f2575d3..796ec12684b731 100644 --- a/Objects/bytesobject.c +++ b/Objects/bytesobject.c @@ -2190,13 +2190,13 @@ bytes.removeprefix as bytes_removeprefix Return a bytes object with the given prefix string removed if present. -If the bytes starts with the prefix, return b[len(prefix):]. +If the bytes starts with the prefix string, return bytes[len(prefix):]. Otherwise, return a copy of the original bytes. [clinic start generated code]*/ static PyObject * bytes_removeprefix_impl(PyBytesObject *self, Py_buffer *prefix) -/*[clinic end generated code: output=f006865331a06ab6 input=24f4dccc70a6e388]*/ +/*[clinic end generated code: output=f006865331a06ab6 input=0c93bac817a8502c]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); @@ -2227,13 +2227,14 @@ bytes.removesuffix as bytes_removesuffix Return a bytes object with the given suffix string removed if present. -If the bytes ends with the suffix and the suffix is not empty, return -b[:-len(prefix)]. Otherwise, return a copy of the original bytes. +If the bytes ends with the suffix string and that suffix is not empty, +return bytes[:-len(prefix)]. Otherwise, return a copy of the original +bytes. [clinic start generated code]*/ static PyObject * bytes_removesuffix_impl(PyBytesObject *self, Py_buffer *suffix) -/*[clinic end generated code: output=d887d308e3242eeb input=b0128a19cd0453ef]*/ +/*[clinic end generated code: output=d887d308e3242eeb input=9f4e1da8c637bbf1]*/ { const char *self_start = PyBytes_AS_STRING(self); Py_ssize_t self_len = PyBytes_GET_SIZE(self); diff --git a/Objects/clinic/bytearrayobject.c.h b/Objects/clinic/bytearrayobject.c.h index 1e8e5e8f31b22e..35ba1ff3d576d2 100644 --- a/Objects/clinic/bytearrayobject.c.h +++ b/Objects/clinic/bytearrayobject.c.h @@ -44,8 +44,9 @@ PyDoc_STRVAR(bytearray_removeprefix__doc__, "\n" "Return a bytearray with the given prefix string removed if present.\n" "\n" -"If the bytearray starts with the prefix, return bytearray[len(prefix):].\n" -"Otherwise, return a copy of the original bytearray."); +"If the bytearray starts with the prefix string, return\n" +"bytearray[len(prefix):]. Otherwise, return a copy of the original\n" +"bytearray."); #define BYTEARRAY_REMOVEPREFIX_METHODDEF \ {"removeprefix", (PyCFunction)bytearray_removeprefix, METH_O, bytearray_removeprefix__doc__}, @@ -83,7 +84,7 @@ PyDoc_STRVAR(bytearray_removesuffix__doc__, "\n" "Return a bytearray with the given suffix string removed if present.\n" "\n" -"If the bytearray ends with the suffix string and the suffix is not\n" +"If the bytearray ends with the suffix string and that suffix is not\n" "empty, return bytearray[:-len(suffix)]. Otherwise, return a copy of\n" "the original bytearray."); @@ -1090,4 +1091,4 @@ bytearray_sizeof(PyByteArrayObject *self, PyObject *Py_UNUSED(ignored)) { return bytearray_sizeof_impl(self); } -/*[clinic end generated code: output=8b7b311d194a75f8 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=b2919f76709e48dc input=a9049054013a1b77]*/ diff --git a/Objects/clinic/bytesobject.c.h b/Objects/clinic/bytesobject.c.h index adaf79943c87da..063a3777b49074 100644 --- a/Objects/clinic/bytesobject.c.h +++ b/Objects/clinic/bytesobject.c.h @@ -532,7 +532,7 @@ PyDoc_STRVAR(bytes_removeprefix__doc__, "\n" "Return a bytes object with the given prefix string removed if present.\n" "\n" -"If the bytes starts with the prefix, return b[len(prefix):].\n" +"If the bytes starts with the prefix string, return bytes[len(prefix):].\n" "Otherwise, return a copy of the original bytes."); #define BYTES_REMOVEPREFIX_METHODDEF \ @@ -571,8 +571,9 @@ PyDoc_STRVAR(bytes_removesuffix__doc__, "\n" "Return a bytes object with the given suffix string removed if present.\n" "\n" -"If the bytes ends with the suffix and the suffix is not empty, return\n" -"b[:-len(prefix)]. Otherwise, return a copy of the original bytes."); +"If the bytes ends with the suffix string and that suffix is not empty,\n" +"return bytes[:-len(prefix)]. Otherwise, return a copy of the original\n" +"bytes."); #define BYTES_REMOVESUFFIX_METHODDEF \ {"removesuffix", (PyCFunction)bytes_removesuffix, METH_O, bytes_removesuffix__doc__}, @@ -833,4 +834,4 @@ bytes_hex(PyBytesObject *self, PyObject *const *args, Py_ssize_t nargs, PyObject exit: return return_value; } -/*[clinic end generated code: output=cdee4f315f08f207 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=220388917d7bf751 input=a9049054013a1b77]*/ diff --git a/Objects/clinic/unicodeobject.c.h b/Objects/clinic/unicodeobject.c.h index fadc27fe492704..cf81df4af67b2c 100644 --- a/Objects/clinic/unicodeobject.c.h +++ b/Objects/clinic/unicodeobject.c.h @@ -760,7 +760,7 @@ PyDoc_STRVAR(unicode_removeprefix__doc__, "\n" "Return a str with the given prefix string removed if present.\n" "\n" -"If the string starts with the prefix, return string[len(prefix):].\n" +"If the string starts with the prefix string, return string[len(prefix):].\n" "Otherwise, return a copy of the original string."); #define UNICODE_REMOVEPREFIX_METHODDEF \ @@ -795,8 +795,9 @@ PyDoc_STRVAR(unicode_removesuffix__doc__, "\n" "Return a str with the given suffix string removed if present.\n" "\n" -"If the string ends with the suffix and the suffix is not empty, return\n" -"string[:-len(suffix)]. Otherwise, return a copy of the original string."); +"If the string ends with the suffix string and that suffix is not empty,\n" +"return string[:-len(suffix)]. Otherwise, return a copy of the original\n" +"string."); #define UNICODE_REMOVESUFFIX_METHODDEF \ {"removesuffix", (PyCFunction)unicode_removesuffix, METH_O, unicode_removesuffix__doc__}, @@ -1302,4 +1303,4 @@ unicode_sizeof(PyObject *self, PyObject *Py_UNUSED(ignored)) { return unicode_sizeof_impl(self); } -/*[clinic end generated code: output=3026a75c0aed4d6f input=a9049054013a1b77]*/ +/*[clinic end generated code: output=b91233f3722643be input=a9049054013a1b77]*/ diff --git a/Objects/unicodeobject.c b/Objects/unicodeobject.c index 2737288b1c3f12..9ba2dcaf7b9916 100644 --- a/Objects/unicodeobject.c +++ b/Objects/unicodeobject.c @@ -12769,13 +12769,13 @@ str.removeprefix as unicode_removeprefix Return a str with the given prefix string removed if present. -If the string starts with the prefix, return string[len(prefix):]. +If the string starts with the prefix string, return string[len(prefix):]. Otherwise, return a copy of the original string. [clinic start generated code]*/ static PyObject * unicode_removeprefix_impl(PyObject *self, PyObject *prefix) -/*[clinic end generated code: output=f1e5945e9763bcb9 input=59b55b6fa49a46b5]*/ +/*[clinic end generated code: output=f1e5945e9763bcb9 input=27ec40b99a37eb88]*/ { int match = tailmatch(self, prefix, 0, PY_SSIZE_T_MAX, -1); if (match == -1) { @@ -12796,13 +12796,14 @@ str.removesuffix as unicode_removesuffix Return a str with the given suffix string removed if present. -If the string ends with the suffix and the suffix is not empty, return -string[:-len(suffix)]. Otherwise, return a copy of the original string. +If the string ends with the suffix string and that suffix is not empty, +return string[:-len(suffix)]. Otherwise, return a copy of the original +string. [clinic start generated code]*/ static PyObject * unicode_removesuffix_impl(PyObject *self, PyObject *suffix) -/*[clinic end generated code: output=d36629e227636822 input=50db6c0aa0f82736]*/ +/*[clinic end generated code: output=d36629e227636822 input=12cc32561e769be4]*/ { int match = tailmatch(self, suffix, 0, PY_SSIZE_T_MAX, +1); if (match == -1) {