+#include "structmember.h"
+
+typedef struct {
+ PyObject_HEAD
+ PyObject *first; /* first name */
+ PyObject *last; /* last name */
+ int number;
+} CustomObject;
+
+static int
+Custom_traverse(CustomObject *self, visitproc visit, void *arg)
+{
+ Py_VISIT(self->first);
+ Py_VISIT(self->last);
+ return 0;
+}
+
+static int
+Custom_clear(CustomObject *self)
+{
+ Py_CLEAR(self->first);
+ Py_CLEAR(self->last);
+ return 0;
+}
+
+static void
+Custom_dealloc(CustomObject *self)
+{
+ PyObject_GC_UnTrack(self);
+ Custom_clear(self);
+ Py_TYPE(self)->tp_free((PyObject *) self);
+}
+
+static PyObject *
+Custom_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
+{
+ CustomObject *self;
+ self = (CustomObject *) type->tp_alloc(type, 0);
+ if (self != NULL) {
+ self->first = PyUnicode_FromString("");
+ if (self->first == NULL) {
+ Py_DECREF(self);
+ return NULL;
+ }
+ self->last = PyUnicode_FromString("");
+ if (self->last == NULL) {
+ Py_DECREF(self);
+ return NULL;
+ }
+ self->number = 0;
+ }
+ return (PyObject *) self;
+}
+
+static int
+Custom_init(CustomObject *self, PyObject *args, PyObject *kwds)
+{
+ static char *kwlist[] = {"first", "last", "number", NULL};
+ PyObject *first = NULL, *last = NULL, *tmp;
+
+ if (!PyArg_ParseTupleAndKeywords(args, kwds, "|UUi", kwlist,
+ &first, &last,
+ &self->number))
+ return -1;
+
+ if (first) {
+ tmp = self->first;
+ Py_INCREF(first);
+ self->first = first;
+ Py_DECREF(tmp);
+ }
+ if (last) {
+ tmp = self->last;
+ Py_INCREF(last);
+ self->last = last;
+ Py_DECREF(tmp);
+ }
+ return 0;
+}
+
+static PyMemberDef Custom_members[] = {
+ {"number", T_INT, offsetof(CustomObject, number), 0,
+ "custom number"},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Custom_getfirst(CustomObject *self, void *closure)
+{
+ Py_INCREF(self->first);
+ return self->first;
+}
+
+static int
+Custom_setfirst(CustomObject *self, PyObject *value, void *closure)
+{
+ if (value == NULL) {
+ PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
+ return -1;
+ }
+ if (!PyUnicode_Check(value)) {
+ PyErr_SetString(PyExc_TypeError,
+ "The first attribute value must be a string");
+ return -1;
+ }
+ Py_INCREF(value);
+ Py_CLEAR(self->first);
+ self->first = value;
+ return 0;
+}
+
+static PyObject *
+Custom_getlast(CustomObject *self, void *closure)
+{
+ Py_INCREF(self->last);
+ return self->last;
+}
+
+static int
+Custom_setlast(CustomObject *self, PyObject *value, void *closure)
+{
+ if (value == NULL) {
+ PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
+ return -1;
+ }
+ if (!PyUnicode_Check(value)) {
+ PyErr_SetString(PyExc_TypeError,
+ "The last attribute value must be a string");
+ return -1;
+ }
+ Py_INCREF(value);
+ Py_CLEAR(self->last);
+ self->last = value;
+ return 0;
+}
+
+static PyGetSetDef Custom_getsetters[] = {
+ {"first", (getter) Custom_getfirst, (setter) Custom_setfirst,
+ "first name", NULL},
+ {"last", (getter) Custom_getlast, (setter) Custom_setlast,
+ "last name", NULL},
+ {NULL} /* Sentinel */
+};
+
+static PyObject *
+Custom_name(CustomObject *self, PyObject *Py_UNUSED(ignored))
+{
+ return PyUnicode_FromFormat("%S %S", self->first, self->last);
+}
+
+static PyMethodDef Custom_methods[] = {
+ {"name", (PyCFunction) Custom_name, METH_NOARGS,
+ "Return the name, combining the first and last name"
+ },
+ {NULL} /* Sentinel */
+};
+
+static PyTypeObject CustomType = {
+ PyVarObject_HEAD_INIT(NULL, 0)
+ .tp_name = "custom4.Custom",
+ .tp_doc = "Custom objects",
+ .tp_basicsize = sizeof(CustomObject),
+ .tp_itemsize = 0,
+ .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC,
+ .tp_new = Custom_new,
+ .tp_init = (initproc) Custom_init,
+ .tp_dealloc = (destructor) Custom_dealloc,
+ .tp_traverse = (traverseproc) Custom_traverse,
+ .tp_clear = (inquiry) Custom_clear,
+ .tp_members = Custom_members,
+ .tp_methods = Custom_methods,
+ .tp_getset = Custom_getsetters,
+};
+
+static PyModuleDef custommodule = {
+ PyModuleDef_HEAD_INIT,
+ .m_name = "custom4",
+ .m_doc = "Example module that creates an extension type.",
+ .m_size = -1,
+};
+
+PyMODINIT_FUNC
+PyInit_custom4(void)
+{
+ PyObject *m;
+ if (PyType_Ready(&CustomType) < 0)
+ return NULL;
+
+ m = PyModule_Create(&custommodule);
+ if (m == NULL)
+ return NULL;
+
+ Py_INCREF(&CustomType);
+ PyModule_AddObject(m, "Custom", (PyObject *) &CustomType);
+ return m;
+}
diff --git a/Doc/includes/email-alternative.py b/Doc/includes/email-alternative.py
index 2e142b1e3b71e4b..df7ca6f3faa332c 100644
--- a/Doc/includes/email-alternative.py
+++ b/Doc/includes/email-alternative.py
@@ -32,7 +32,7 @@
Salut!
Cela ressemble à un excellent
-
recipie
déjeuner.
diff --git a/Doc/includes/email-read-alternative.py b/Doc/includes/email-read-alternative.py
index 3f5ab24c0fbdd25..5ea84e62584a465 100644
--- a/Doc/includes/email-read-alternative.py
+++ b/Doc/includes/email-read-alternative.py
@@ -21,7 +21,7 @@
print('From:', msg['from'])
print('Subject:', msg['subject'])
-# If we want to print a priview of the message content, we can extract whatever
+# If we want to print a preview of the message content, we can extract whatever
# the least formatted payload is and print the first three lines. Of course,
# if the message has no plain text part printing the first three lines of html
# is probably useless, but this is just a conceptual example.
diff --git a/Doc/includes/noddy.c b/Doc/includes/noddy.c
deleted file mode 100644
index 19a27a89e883b3b..000000000000000
--- a/Doc/includes/noddy.c
+++ /dev/null
@@ -1,56 +0,0 @@
-#include
-
-typedef struct {
- PyObject_HEAD
- /* Type-specific fields go here. */
-} noddy_NoddyObject;
-
-static PyTypeObject noddy_NoddyType = {
- PyVarObject_HEAD_INIT(NULL, 0)
- "noddy.Noddy", /* tp_name */
- sizeof(noddy_NoddyObject), /* tp_basicsize */
- 0, /* tp_itemsize */
- 0, /* tp_dealloc */
- 0, /* tp_print */
- 0, /* tp_getattr */
- 0, /* tp_setattr */
- 0, /* tp_reserved */
- 0, /* 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 */
- Py_TPFLAGS_DEFAULT, /* tp_flags */
- "Noddy objects", /* tp_doc */
-};
-
-static PyModuleDef noddymodule = {
- PyModuleDef_HEAD_INIT,
- "noddy",
- "Example module that creates an extension type.",
- -1,
- NULL, NULL, NULL, NULL, NULL
-};
-
-PyMODINIT_FUNC
-PyInit_noddy(void)
-{
- PyObject* m;
-
- noddy_NoddyType.tp_new = PyType_GenericNew;
- if (PyType_Ready(&noddy_NoddyType) < 0)
- return NULL;
-
- m = PyModule_Create(&noddymodule);
- if (m == NULL)
- return NULL;
-
- Py_INCREF(&noddy_NoddyType);
- PyModule_AddObject(m, "Noddy", (PyObject *)&noddy_NoddyType);
- return m;
-}
diff --git a/Doc/includes/noddy2.c b/Doc/includes/noddy2.c
deleted file mode 100644
index 964155845fee83e..000000000000000
--- a/Doc/includes/noddy2.c
+++ /dev/null
@@ -1,172 +0,0 @@
-#include
-#include "structmember.h"
-
-typedef struct {
- PyObject_HEAD
- PyObject *first; /* first name */
- PyObject *last; /* last name */
- int number;
-} Noddy;
-
-static void
-Noddy_dealloc(Noddy* self)
-{
- Py_XDECREF(self->first);
- Py_XDECREF(self->last);
- Py_TYPE(self)->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
- Noddy *self;
-
- self = (Noddy *)type->tp_alloc(type, 0);
- if (self != NULL) {
- self->first = PyUnicode_FromString("");
- if (self->first == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->last = PyUnicode_FromString("");
- if (self->last == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->number = 0;
- }
-
- return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
- PyObject *first=NULL, *last=NULL, *tmp;
-
- static char *kwlist[] = {"first", "last", "number", NULL};
-
- if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
- &first, &last,
- &self->number))
- return -1;
-
- if (first) {
- tmp = self->first;
- Py_INCREF(first);
- self->first = first;
- Py_XDECREF(tmp);
- }
-
- if (last) {
- tmp = self->last;
- Py_INCREF(last);
- self->last = last;
- Py_XDECREF(tmp);
- }
-
- return 0;
-}
-
-
-static PyMemberDef Noddy_members[] = {
- {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
- "first name"},
- {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
- "last name"},
- {"number", T_INT, offsetof(Noddy, number), 0,
- "noddy number"},
- {NULL} /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
- if (self->first == NULL) {
- PyErr_SetString(PyExc_AttributeError, "first");
- return NULL;
- }
-
- if (self->last == NULL) {
- PyErr_SetString(PyExc_AttributeError, "last");
- return NULL;
- }
-
- return PyUnicode_FromFormat("%S %S", self->first, self->last);
-}
-
-static PyMethodDef Noddy_methods[] = {
- {"name", (PyCFunction)Noddy_name, METH_NOARGS,
- "Return the name, combining the first and last name"
- },
- {NULL} /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
- PyVarObject_HEAD_INIT(NULL, 0)
- "noddy.Noddy", /* tp_name */
- sizeof(Noddy), /* tp_basicsize */
- 0, /* tp_itemsize */
- (destructor)Noddy_dealloc, /* tp_dealloc */
- 0, /* tp_print */
- 0, /* tp_getattr */
- 0, /* tp_setattr */
- 0, /* tp_reserved */
- 0, /* 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 */
- Py_TPFLAGS_DEFAULT |
- Py_TPFLAGS_BASETYPE, /* tp_flags */
- "Noddy objects", /* tp_doc */
- 0, /* tp_traverse */
- 0, /* tp_clear */
- 0, /* tp_richcompare */
- 0, /* tp_weaklistoffset */
- 0, /* tp_iter */
- 0, /* tp_iternext */
- Noddy_methods, /* tp_methods */
- Noddy_members, /* tp_members */
- 0, /* tp_getset */
- 0, /* tp_base */
- 0, /* tp_dict */
- 0, /* tp_descr_get */
- 0, /* tp_descr_set */
- 0, /* tp_dictoffset */
- (initproc)Noddy_init, /* tp_init */
- 0, /* tp_alloc */
- Noddy_new, /* tp_new */
-};
-
-static PyModuleDef noddy2module = {
- PyModuleDef_HEAD_INIT,
- "noddy2",
- "Example module that creates an extension type.",
- -1,
- NULL, NULL, NULL, NULL, NULL
-};
-
-PyMODINIT_FUNC
-PyInit_noddy2(void)
-{
- PyObject* m;
-
- if (PyType_Ready(&NoddyType) < 0)
- return NULL;
-
- m = PyModule_Create(&noddy2module);
- if (m == NULL)
- return NULL;
-
- Py_INCREF(&NoddyType);
- PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
- return m;
-}
diff --git a/Doc/includes/noddy3.c b/Doc/includes/noddy3.c
deleted file mode 100644
index 8a5a753ca439eb9..000000000000000
--- a/Doc/includes/noddy3.c
+++ /dev/null
@@ -1,225 +0,0 @@
-#include
-#include "structmember.h"
-
-typedef struct {
- PyObject_HEAD
- PyObject *first;
- PyObject *last;
- int number;
-} Noddy;
-
-static void
-Noddy_dealloc(Noddy* self)
-{
- Py_XDECREF(self->first);
- Py_XDECREF(self->last);
- Py_TYPE(self)->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
- Noddy *self;
-
- self = (Noddy *)type->tp_alloc(type, 0);
- if (self != NULL) {
- self->first = PyUnicode_FromString("");
- if (self->first == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->last = PyUnicode_FromString("");
- if (self->last == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->number = 0;
- }
-
- return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
- PyObject *first=NULL, *last=NULL, *tmp;
-
- static char *kwlist[] = {"first", "last", "number", NULL};
-
- if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist,
- &first, &last,
- &self->number))
- return -1;
-
- if (first) {
- tmp = self->first;
- Py_INCREF(first);
- self->first = first;
- Py_DECREF(tmp);
- }
-
- if (last) {
- tmp = self->last;
- Py_INCREF(last);
- self->last = last;
- Py_DECREF(tmp);
- }
-
- return 0;
-}
-
-static PyMemberDef Noddy_members[] = {
- {"number", T_INT, offsetof(Noddy, number), 0,
- "noddy number"},
- {NULL} /* Sentinel */
-};
-
-static PyObject *
-Noddy_getfirst(Noddy *self, void *closure)
-{
- Py_INCREF(self->first);
- return self->first;
-}
-
-static int
-Noddy_setfirst(Noddy *self, PyObject *value, void *closure)
-{
- if (value == NULL) {
- PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute");
- return -1;
- }
-
- if (! PyUnicode_Check(value)) {
- PyErr_SetString(PyExc_TypeError,
- "The first attribute value must be a string");
- return -1;
- }
-
- Py_DECREF(self->first);
- Py_INCREF(value);
- self->first = value;
-
- return 0;
-}
-
-static PyObject *
-Noddy_getlast(Noddy *self, void *closure)
-{
- Py_INCREF(self->last);
- return self->last;
-}
-
-static int
-Noddy_setlast(Noddy *self, PyObject *value, void *closure)
-{
- if (value == NULL) {
- PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute");
- return -1;
- }
-
- if (! PyUnicode_Check(value)) {
- PyErr_SetString(PyExc_TypeError,
- "The last attribute value must be a string");
- return -1;
- }
-
- Py_DECREF(self->last);
- Py_INCREF(value);
- self->last = value;
-
- return 0;
-}
-
-static PyGetSetDef Noddy_getseters[] = {
- {"first",
- (getter)Noddy_getfirst, (setter)Noddy_setfirst,
- "first name",
- NULL},
- {"last",
- (getter)Noddy_getlast, (setter)Noddy_setlast,
- "last name",
- NULL},
- {NULL} /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
- return PyUnicode_FromFormat("%S %S", self->first, self->last);
-}
-
-static PyMethodDef Noddy_methods[] = {
- {"name", (PyCFunction)Noddy_name, METH_NOARGS,
- "Return the name, combining the first and last name"
- },
- {NULL} /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
- PyVarObject_HEAD_INIT(NULL, 0)
- "noddy.Noddy", /* tp_name */
- sizeof(Noddy), /* tp_basicsize */
- 0, /* tp_itemsize */
- (destructor)Noddy_dealloc, /* tp_dealloc */
- 0, /* tp_print */
- 0, /* tp_getattr */
- 0, /* tp_setattr */
- 0, /* tp_reserved */
- 0, /* 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 */
- Py_TPFLAGS_DEFAULT |
- Py_TPFLAGS_BASETYPE, /* tp_flags */
- "Noddy objects", /* tp_doc */
- 0, /* tp_traverse */
- 0, /* tp_clear */
- 0, /* tp_richcompare */
- 0, /* tp_weaklistoffset */
- 0, /* tp_iter */
- 0, /* tp_iternext */
- Noddy_methods, /* tp_methods */
- Noddy_members, /* tp_members */
- Noddy_getseters, /* tp_getset */
- 0, /* tp_base */
- 0, /* tp_dict */
- 0, /* tp_descr_get */
- 0, /* tp_descr_set */
- 0, /* tp_dictoffset */
- (initproc)Noddy_init, /* tp_init */
- 0, /* tp_alloc */
- Noddy_new, /* tp_new */
-};
-
-static PyModuleDef noddy3module = {
- PyModuleDef_HEAD_INIT,
- "noddy3",
- "Example module that creates an extension type.",
- -1,
- NULL, NULL, NULL, NULL, NULL
-};
-
-PyMODINIT_FUNC
-PyInit_noddy3(void)
-{
- PyObject* m;
-
- if (PyType_Ready(&NoddyType) < 0)
- return NULL;
-
- m = PyModule_Create(&noddy3module);
- if (m == NULL)
- return NULL;
-
- Py_INCREF(&NoddyType);
- PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
- return m;
-}
diff --git a/Doc/includes/noddy4.c b/Doc/includes/noddy4.c
deleted file mode 100644
index eb9622a87d99cc9..000000000000000
--- a/Doc/includes/noddy4.c
+++ /dev/null
@@ -1,207 +0,0 @@
-#include
-#include "structmember.h"
-
-typedef struct {
- PyObject_HEAD
- PyObject *first;
- PyObject *last;
- int number;
-} Noddy;
-
-static int
-Noddy_traverse(Noddy *self, visitproc visit, void *arg)
-{
- int vret;
-
- if (self->first) {
- vret = visit(self->first, arg);
- if (vret != 0)
- return vret;
- }
- if (self->last) {
- vret = visit(self->last, arg);
- if (vret != 0)
- return vret;
- }
-
- return 0;
-}
-
-static int
-Noddy_clear(Noddy *self)
-{
- PyObject *tmp;
-
- tmp = self->first;
- self->first = NULL;
- Py_XDECREF(tmp);
-
- tmp = self->last;
- self->last = NULL;
- Py_XDECREF(tmp);
-
- return 0;
-}
-
-static void
-Noddy_dealloc(Noddy* self)
-{
- Noddy_clear(self);
- Py_TYPE(self)->tp_free((PyObject*)self);
-}
-
-static PyObject *
-Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
-{
- Noddy *self;
-
- self = (Noddy *)type->tp_alloc(type, 0);
- if (self != NULL) {
- self->first = PyUnicode_FromString("");
- if (self->first == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->last = PyUnicode_FromString("");
- if (self->last == NULL) {
- Py_DECREF(self);
- return NULL;
- }
-
- self->number = 0;
- }
-
- return (PyObject *)self;
-}
-
-static int
-Noddy_init(Noddy *self, PyObject *args, PyObject *kwds)
-{
- PyObject *first=NULL, *last=NULL, *tmp;
-
- static char *kwlist[] = {"first", "last", "number", NULL};
-
- if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist,
- &first, &last,
- &self->number))
- return -1;
-
- if (first) {
- tmp = self->first;
- Py_INCREF(first);
- self->first = first;
- Py_XDECREF(tmp);
- }
-
- if (last) {
- tmp = self->last;
- Py_INCREF(last);
- self->last = last;
- Py_XDECREF(tmp);
- }
-
- return 0;
-}
-
-
-static PyMemberDef Noddy_members[] = {
- {"first", T_OBJECT_EX, offsetof(Noddy, first), 0,
- "first name"},
- {"last", T_OBJECT_EX, offsetof(Noddy, last), 0,
- "last name"},
- {"number", T_INT, offsetof(Noddy, number), 0,
- "noddy number"},
- {NULL} /* Sentinel */
-};
-
-static PyObject *
-Noddy_name(Noddy* self)
-{
- if (self->first == NULL) {
- PyErr_SetString(PyExc_AttributeError, "first");
- return NULL;
- }
-
- if (self->last == NULL) {
- PyErr_SetString(PyExc_AttributeError, "last");
- return NULL;
- }
-
- return PyUnicode_FromFormat("%S %S", self->first, self->last);
-}
-
-static PyMethodDef Noddy_methods[] = {
- {"name", (PyCFunction)Noddy_name, METH_NOARGS,
- "Return the name, combining the first and last name"
- },
- {NULL} /* Sentinel */
-};
-
-static PyTypeObject NoddyType = {
- PyVarObject_HEAD_INIT(NULL, 0)
- "noddy.Noddy", /* tp_name */
- sizeof(Noddy), /* tp_basicsize */
- 0, /* tp_itemsize */
- (destructor)Noddy_dealloc, /* tp_dealloc */
- 0, /* tp_print */
- 0, /* tp_getattr */
- 0, /* tp_setattr */
- 0, /* tp_reserved */
- 0, /* 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 */
- Py_TPFLAGS_DEFAULT |
- Py_TPFLAGS_BASETYPE |
- Py_TPFLAGS_HAVE_GC, /* tp_flags */
- "Noddy objects", /* tp_doc */
- (traverseproc)Noddy_traverse, /* tp_traverse */
- (inquiry)Noddy_clear, /* tp_clear */
- 0, /* tp_richcompare */
- 0, /* tp_weaklistoffset */
- 0, /* tp_iter */
- 0, /* tp_iternext */
- Noddy_methods, /* tp_methods */
- Noddy_members, /* tp_members */
- 0, /* tp_getset */
- 0, /* tp_base */
- 0, /* tp_dict */
- 0, /* tp_descr_get */
- 0, /* tp_descr_set */
- 0, /* tp_dictoffset */
- (initproc)Noddy_init, /* tp_init */
- 0, /* tp_alloc */
- Noddy_new, /* tp_new */
-};
-
-static PyModuleDef noddy4module = {
- PyModuleDef_HEAD_INIT,
- "noddy4",
- "Example module that creates an extension type.",
- -1,
- NULL, NULL, NULL, NULL, NULL
-};
-
-PyMODINIT_FUNC
-PyInit_noddy4(void)
-{
- PyObject* m;
-
- if (PyType_Ready(&NoddyType) < 0)
- return NULL;
-
- m = PyModule_Create(&noddy4module);
- if (m == NULL)
- return NULL;
-
- Py_INCREF(&NoddyType);
- PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType);
- return m;
-}
diff --git a/Doc/includes/run-func.c b/Doc/includes/run-func.c
index ead7bdd23209a3d..9caf1fdb20104af 100644
--- a/Doc/includes/run-func.c
+++ b/Doc/includes/run-func.c
@@ -3,7 +3,7 @@
int
main(int argc, char *argv[])
{
- PyObject *pName, *pModule, *pDict, *pFunc;
+ PyObject *pName, *pModule, *pFunc;
PyObject *pArgs, *pValue;
int i;
diff --git a/Doc/includes/setup.py b/Doc/includes/setup.py
index b853d23b170985a..a38a39de3e7c86c 100644
--- a/Doc/includes/setup.py
+++ b/Doc/includes/setup.py
@@ -5,4 +5,5 @@
Extension("noddy2", ["noddy2.c"]),
Extension("noddy3", ["noddy3.c"]),
Extension("noddy4", ["noddy4.c"]),
+ Extension("shoddy", ["shoddy.c"]),
])
diff --git a/Doc/includes/shoddy.c b/Doc/includes/shoddy.c
deleted file mode 100644
index 07a272124ceabaa..000000000000000
--- a/Doc/includes/shoddy.c
+++ /dev/null
@@ -1,99 +0,0 @@
-#include
-
-typedef struct {
- PyListObject list;
- int state;
-} Shoddy;
-
-
-static PyObject *
-Shoddy_increment(Shoddy *self, PyObject *unused)
-{
- self->state++;
- return PyLong_FromLong(self->state);
-}
-
-
-static PyMethodDef Shoddy_methods[] = {
- {"increment", (PyCFunction)Shoddy_increment, METH_NOARGS,
- PyDoc_STR("increment state counter")},
- {NULL, NULL},
-};
-
-static int
-Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds)
-{
- if (PyList_Type.tp_init((PyObject *)self, args, kwds) < 0)
- return -1;
- self->state = 0;
- return 0;
-}
-
-
-static PyTypeObject ShoddyType = {
- PyObject_HEAD_INIT(NULL)
- "shoddy.Shoddy", /* tp_name */
- sizeof(Shoddy), /* tp_basicsize */
- 0, /* tp_itemsize */
- 0, /* tp_dealloc */
- 0, /* tp_print */
- 0, /* tp_getattr */
- 0, /* tp_setattr */
- 0, /* tp_reserved */
- 0, /* 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 */
- Py_TPFLAGS_DEFAULT |
- Py_TPFLAGS_BASETYPE, /* tp_flags */
- 0, /* tp_doc */
- 0, /* tp_traverse */
- 0, /* tp_clear */
- 0, /* tp_richcompare */
- 0, /* tp_weaklistoffset */
- 0, /* tp_iter */
- 0, /* tp_iternext */
- Shoddy_methods, /* 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 */
- (initproc)Shoddy_init, /* tp_init */
- 0, /* tp_alloc */
- 0, /* tp_new */
-};
-
-static PyModuleDef shoddymodule = {
- PyModuleDef_HEAD_INIT,
- "shoddy",
- "Shoddy module",
- -1,
- NULL, NULL, NULL, NULL, NULL
-};
-
-PyMODINIT_FUNC
-PyInit_shoddy(void)
-{
- PyObject *m;
-
- ShoddyType.tp_base = &PyList_Type;
- if (PyType_Ready(&ShoddyType) < 0)
- return NULL;
-
- m = PyModule_Create(&shoddymodule);
- if (m == NULL)
- return NULL;
-
- Py_INCREF(&ShoddyType);
- PyModule_AddObject(m, "Shoddy", (PyObject *) &ShoddyType);
- return m;
-}
diff --git a/Doc/includes/sqlite3/load_extension.py b/Doc/includes/sqlite3/load_extension.py
index 015aa0de8c46d4d..b997c70668ace41 100644
--- a/Doc/includes/sqlite3/load_extension.py
+++ b/Doc/includes/sqlite3/load_extension.py
@@ -11,7 +11,7 @@
# alternatively you can load the extension using an API call:
# con.load_extension("./fts3.so")
-# disable extension laoding again
+# disable extension loading again
con.enable_load_extension(False)
# example from SQLite wiki
diff --git a/Doc/includes/sublist.c b/Doc/includes/sublist.c
new file mode 100644
index 000000000000000..376dddfac09c685
--- /dev/null
+++ b/Doc/includes/sublist.c
@@ -0,0 +1,63 @@
+#include
+
+typedef struct {
+ PyListObject list;
+ int state;
+} SubListObject;
+
+static PyObject *
+SubList_increment(SubListObject *self, PyObject *unused)
+{
+ self->state++;
+ return PyLong_FromLong(self->state);
+}
+
+static PyMethodDef SubList_methods[] = {
+ {"increment", (PyCFunction) SubList_increment, METH_NOARGS,
+ PyDoc_STR("increment state counter")},
+ {NULL},
+};
+
+static int
+SubList_init(SubListObject *self, PyObject *args, PyObject *kwds)
+{
+ if (PyList_Type.tp_init((PyObject *) self, args, kwds) < 0)
+ return -1;
+ self->state = 0;
+ return 0;
+}
+
+static PyTypeObject SubListType = {
+ PyVarObject_HEAD_INIT(NULL, 0)
+ .tp_name = "sublist.SubList",
+ .tp_doc = "SubList objects",
+ .tp_basicsize = sizeof(SubListObject),
+ .tp_itemsize = 0,
+ .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE,
+ .tp_init = (initproc) SubList_init,
+ .tp_methods = SubList_methods,
+};
+
+static PyModuleDef sublistmodule = {
+ PyModuleDef_HEAD_INIT,
+ .m_name = "sublist",
+ .m_doc = "Example module that creates an extension type.",
+ .m_size = -1,
+};
+
+PyMODINIT_FUNC
+PyInit_sublist(void)
+{
+ PyObject *m;
+ SubListType.tp_base = &PyList_Type;
+ if (PyType_Ready(&SubListType) < 0)
+ return NULL;
+
+ m = PyModule_Create(&sublistmodule);
+ if (m == NULL)
+ return NULL;
+
+ Py_INCREF(&SubListType);
+ PyModule_AddObject(m, "SubList", (PyObject *) &SubListType);
+ return m;
+}
diff --git a/Doc/includes/test.py b/Doc/includes/test.py
index 9e9d4a67121cae1..09ebe3fec0bdbe3 100644
--- a/Doc/includes/test.py
+++ b/Doc/includes/test.py
@@ -1,181 +1,168 @@
-"""Test module for the noddy examples
+"""Test module for the custom examples
-Noddy 1:
+Custom 1:
->>> import noddy
->>> n1 = noddy.Noddy()
->>> n2 = noddy.Noddy()
->>> del n1
->>> del n2
+>>> import custom
+>>> c1 = custom.Custom()
+>>> c2 = custom.Custom()
+>>> del c1
+>>> del c2
-Noddy 2
+Custom 2
->>> import noddy2
->>> n1 = noddy2.Noddy('jim', 'fulton', 42)
->>> n1.first
+>>> import custom2
+>>> c1 = custom2.Custom('jim', 'fulton', 42)
+>>> c1.first
'jim'
->>> n1.last
+>>> c1.last
'fulton'
->>> n1.number
+>>> c1.number
42
->>> n1.name()
+>>> c1.name()
'jim fulton'
->>> n1.first = 'will'
->>> n1.name()
+>>> c1.first = 'will'
+>>> c1.name()
'will fulton'
->>> n1.last = 'tell'
->>> n1.name()
+>>> c1.last = 'tell'
+>>> c1.name()
'will tell'
->>> del n1.first
->>> n1.name()
+>>> del c1.first
+>>> c1.name()
Traceback (most recent call last):
...
AttributeError: first
->>> n1.first
+>>> c1.first
Traceback (most recent call last):
...
AttributeError: first
->>> n1.first = 'drew'
->>> n1.first
+>>> c1.first = 'drew'
+>>> c1.first
'drew'
->>> del n1.number
+>>> del c1.number
Traceback (most recent call last):
...
TypeError: can't delete numeric/char attribute
->>> n1.number=2
->>> n1.number
+>>> c1.number=2
+>>> c1.number
2
->>> n1.first = 42
->>> n1.name()
+>>> c1.first = 42
+>>> c1.name()
'42 tell'
->>> n2 = noddy2.Noddy()
->>> n2.name()
+>>> c2 = custom2.Custom()
+>>> c2.name()
' '
->>> n2.first
+>>> c2.first
''
->>> n2.last
+>>> c2.last
''
->>> del n2.first
->>> n2.first
+>>> del c2.first
+>>> c2.first
Traceback (most recent call last):
...
AttributeError: first
->>> n2.first
+>>> c2.first
Traceback (most recent call last):
...
AttributeError: first
->>> n2.name()
+>>> c2.name()
Traceback (most recent call last):
File "", line 1, in ?
AttributeError: first
->>> n2.number
+>>> c2.number
0
->>> n3 = noddy2.Noddy('jim', 'fulton', 'waaa')
+>>> n3 = custom2.Custom('jim', 'fulton', 'waaa')
Traceback (most recent call last):
File "", line 1, in ?
-TypeError: an integer is required
->>> del n1
->>> del n2
+TypeError: an integer is required (got type str)
+>>> del c1
+>>> del c2
-Noddy 3
+Custom 3
->>> import noddy3
->>> n1 = noddy3.Noddy('jim', 'fulton', 42)
->>> n1 = noddy3.Noddy('jim', 'fulton', 42)
->>> n1.name()
+>>> import custom3
+>>> c1 = custom3.Custom('jim', 'fulton', 42)
+>>> c1 = custom3.Custom('jim', 'fulton', 42)
+>>> c1.name()
'jim fulton'
->>> del n1.first
+>>> del c1.first
Traceback (most recent call last):
File "", line 1, in ?
TypeError: Cannot delete the first attribute
->>> n1.first = 42
+>>> c1.first = 42
Traceback (most recent call last):
File "", line 1, in ?
TypeError: The first attribute value must be a string
->>> n1.first = 'will'
->>> n1.name()
+>>> c1.first = 'will'
+>>> c1.name()
'will fulton'
->>> n2 = noddy3.Noddy()
->>> n2 = noddy3.Noddy()
->>> n2 = noddy3.Noddy()
->>> n3 = noddy3.Noddy('jim', 'fulton', 'waaa')
+>>> c2 = custom3.Custom()
+>>> c2 = custom3.Custom()
+>>> c2 = custom3.Custom()
+>>> n3 = custom3.Custom('jim', 'fulton', 'waaa')
Traceback (most recent call last):
File "", line 1, in ?
-TypeError: an integer is required
->>> del n1
->>> del n2
+TypeError: an integer is required (got type str)
+>>> del c1
+>>> del c2
-Noddy 4
+Custom 4
->>> import noddy4
->>> n1 = noddy4.Noddy('jim', 'fulton', 42)
->>> n1.first
+>>> import custom4
+>>> c1 = custom4.Custom('jim', 'fulton', 42)
+>>> c1.first
'jim'
->>> n1.last
+>>> c1.last
'fulton'
->>> n1.number
+>>> c1.number
42
->>> n1.name()
+>>> c1.name()
'jim fulton'
->>> n1.first = 'will'
->>> n1.name()
+>>> c1.first = 'will'
+>>> c1.name()
'will fulton'
->>> n1.last = 'tell'
->>> n1.name()
+>>> c1.last = 'tell'
+>>> c1.name()
'will tell'
->>> del n1.first
->>> n1.name()
+>>> del c1.first
Traceback (most recent call last):
...
-AttributeError: first
->>> n1.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n1.first = 'drew'
->>> n1.first
+TypeError: Cannot delete the first attribute
+>>> c1.name()
+'will tell'
+>>> c1.first = 'drew'
+>>> c1.first
'drew'
->>> del n1.number
+>>> del c1.number
Traceback (most recent call last):
...
TypeError: can't delete numeric/char attribute
->>> n1.number=2
->>> n1.number
+>>> c1.number=2
+>>> c1.number
2
->>> n1.first = 42
->>> n1.name()
-'42 tell'
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2 = noddy4.Noddy()
->>> n2.name()
+>>> c1.first = 42
+Traceback (most recent call last):
+...
+TypeError: The first attribute value must be a string
+>>> c1.name()
+'drew tell'
+>>> c2 = custom4.Custom()
+>>> c2 = custom4.Custom()
+>>> c2 = custom4.Custom()
+>>> c2 = custom4.Custom()
+>>> c2.name()
' '
->>> n2.first
+>>> c2.first
''
->>> n2.last
+>>> c2.last
''
->>> del n2.first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.first
-Traceback (most recent call last):
-...
-AttributeError: first
->>> n2.name()
-Traceback (most recent call last):
- File "", line 1, in ?
-AttributeError: first
->>> n2.number
+>>> c2.number
0
->>> n3 = noddy4.Noddy('jim', 'fulton', 'waaa')
+>>> n3 = custom4.Custom('jim', 'fulton', 'waaa')
Traceback (most recent call last):
- File "", line 1, in ?
-TypeError: an integer is required
+...
+TypeError: an integer is required (got type str)
Test cyclic gc(?)
@@ -183,15 +170,14 @@
>>> import gc
>>> gc.disable()
->>> x = []
->>> l = [x]
->>> n2.first = l
->>> n2.first
-[[]]
->>> l.append(n2)
->>> del l
->>> del n1
->>> del n2
+>>> class Subclass(custom4.Custom): pass
+...
+>>> s = Subclass()
+>>> s.cycle = [s]
+>>> s.cycle.append(s.cycle)
+>>> x = object()
+>>> s.x = x
+>>> del s
>>> sys.getrefcount(x)
3
>>> ignore = gc.collect()
diff --git a/Doc/install/index.rst b/Doc/install/index.rst
index bc080b00c59a82e..5a59b4d80388b9e 100644
--- a/Doc/install/index.rst
+++ b/Doc/install/index.rst
@@ -283,7 +283,9 @@ Windows, choose :menuselection:`Start --> Programs --> Python X.Y -->
Python (command line)`. Once the interpreter is started, you type Python code
at the prompt. For example, on my Linux system, I type the three Python
statements shown below, and get the output as shown, to find out my
-:file:`{prefix}` and :file:`{exec-prefix}`::
+:file:`{prefix}` and :file:`{exec-prefix}`:
+
+.. code-block:: pycon
Python 2.4 (#26, Aug 7 2004, 17:19:02)
Type "help", "copyright", "credits" or "license" for more information.
@@ -552,10 +554,10 @@ C headers ``--install-headers``
These override options can be relative, absolute,
or explicitly defined in terms of one of the installation base directories.
-(There are two installation base directories, and they are normally the same---
-they only differ when you use the Unix "prefix scheme" and supply different
-``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will
-override values computed or given for ``--install-purelib`` and
+(There are two installation base directories, and they are normally the
+same---they only differ when you use the Unix "prefix scheme" and supply
+different ``--prefix`` and ``--exec-prefix`` options; using ``--install-lib``
+will override values computed or given for ``--install-purelib`` and
``--install-platlib``, and is recommended for schemes that don't make a
difference between Python and extension modules.)
@@ -582,10 +584,10 @@ in this case.)
If you maintain Python on Windows, you might want third-party modules to live in
a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}`
-itself. This is almost as easy as customizing the script installation directory
----you just have to remember that there are two types of modules to worry about,
-Python and extension modules, which can conveniently be both controlled by one
-option::
+itself. This is almost as easy as customizing the script installation
+directory---you just have to remember that there are two types of modules
+to worry about, Python and extension modules, which can conveniently be both
+controlled by one option::
python setup.py install --install-lib=Site
@@ -622,7 +624,9 @@ parsing your configuration file(s).
Obviously, specifying the entire installation scheme every time you install a
new module distribution would be very tedious. Thus, you can put these options
-into your Distutils config file (see section :ref:`inst-config-files`)::
+into your Distutils config file (see section :ref:`inst-config-files`):
+
+.. code-block:: ini
[install]
install-base=$HOME
@@ -631,7 +635,9 @@ into your Distutils config file (see section :ref:`inst-config-files`)::
install-scripts=python/scripts
install-data=python/data
-or, equivalently, ::
+or, equivalently,
+
+.. code-block:: ini
[install]
install-base=$HOME/python
@@ -718,7 +724,9 @@ A slightly less convenient way is to edit the :file:`site.py` file in Python's
standard library, and modify ``sys.path``. :file:`site.py` is automatically
imported when the Python interpreter is executed, unless the :option:`-S` switch
is supplied to suppress this behaviour. So you could simply edit
-:file:`site.py` and add two lines to it::
+:file:`site.py` and add two lines to it:
+
+.. code-block:: python
import sys
sys.path.append('/www/python/')
@@ -839,7 +847,9 @@ plus a ``global`` section for global options that affect every command. Each
section consists of one option per line, specified as ``option=value``.
For example, the following is a complete config file that just forces all
-commands to run quietly by default::
+commands to run quietly by default:
+
+.. code-block:: ini
[global]
verbose=0
@@ -853,7 +863,9 @@ distribution.
You could override the default "build base" directory and make the
:command:`build\*` commands always forcibly rebuild all files with the
-following::
+following:
+
+.. code-block:: ini
[build]
build-base=blib
diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst
index b22465df2910eb0..18f5b29396c9c26 100644
--- a/Doc/installing/index.rst
+++ b/Doc/installing/index.rst
@@ -44,7 +44,7 @@ Key terms
``venv``. It allows virtual environments to be used on versions of
Python prior to 3.4, which either don't provide ``venv`` at all, or
aren't able to automatically install ``pip`` into created environments.
-* The `Python Packaging Index `__ is a public
+* The `Python Packaging Index `__ is a public
repository of open source licensed packages made available for use by
other Python users.
* the `Python Packaging Authority
@@ -211,6 +211,17 @@ On such systems, it is often better to use a virtual environment or a
per-user installation when installing packages with ``pip``.
+Pip not installed
+-----------------
+
+It is possible that ``pip`` does not get installed by default. One potential fix is::
+
+ python -m ensurepip --default-pip
+
+There are also additional resources for `installing pip.
+`__
+
+
Installing binary extensions
----------------------------
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst
index ace1bfaf8cb9d6d..1ab05a62ad458fb 100644
--- a/Doc/library/2to3.rst
+++ b/Doc/library/2to3.rst
@@ -199,13 +199,6 @@ and off individually. They are described here in more detail.
because the :class:`memoryview` API is similar but not exactly the same as
that of :class:`buffer`.
-.. 2to3fixer:: callable
-
- Converts ``callable(x)`` to ``isinstance(x, collections.Callable)``, adding
- an import to :mod:`collections` if needed. Note ``callable(x)`` has returned
- in Python 3.2, so if you do not intend to support Python 3.1, you can disable
- this fixer.
-
.. 2to3fixer:: dict
Fixes dictionary iteration methods. :meth:`dict.iteritems` is converted to
@@ -295,7 +288,8 @@ and off individually. They are described here in more detail.
Fixes duplicate types in the second argument of :func:`isinstance`. For
example, ``isinstance(x, (int, int))`` is converted to ``isinstance(x,
- (int))``.
+ int)`` and ``isinstance(x, (int, float, int))`` is converted to
+ ``isinstance(x, (int, float))``.
.. 2to3fixer:: itertools_imports
diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst
index 0d2d818f5f90b00..06e2c02afc1e8b5 100644
--- a/Doc/library/_thread.rst
+++ b/Doc/library/_thread.rst
@@ -57,8 +57,12 @@ It defines the following constants and functions:
.. function:: interrupt_main()
- Raise a :exc:`KeyboardInterrupt` exception in the main thread. A subthread can
- use this function to interrupt the main thread.
+ Simulate the effect of a :data:`signal.SIGINT` signal arriving in the main
+ thread. A thread can use this function to interrupt the main thread.
+
+ If :data:`signal.SIGINT` isn't handled by Python (it was set to
+ :data:`signal.SIG_DFL` or :data:`signal.SIG_IGN`), this function does
+ nothing.
.. function:: exit()
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
index 966003bd45ada1f..fc39a2e7582b3a8 100644
--- a/Doc/library/abc.rst
+++ b/Doc/library/abc.rst
@@ -18,13 +18,39 @@ see the PEP for why this was added to Python. (See also :pep:`3141` and the
:mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.)
The :mod:`collections` module has some concrete classes that derive from
-ABCs; these can, of course, be further derived. In addition the
+ABCs; these can, of course, be further derived. In addition, the
:mod:`collections.abc` submodule has some ABCs that can be used to test whether
-a class or instance provides a particular interface, for example, is it
-hashable or a mapping.
+a class or instance provides a particular interface, for example, if it is
+hashable or if it is a mapping.
-This module provides the following classes:
+This module provides the metaclass :class:`ABCMeta` for defining ABCs and
+a helper class :class:`ABC` to alternatively define ABCs through inheritance:
+
+.. class:: ABC
+
+ A helper class that has :class:`ABCMeta` as its metaclass. With this class,
+ an abstract base class can be created by simply deriving from :class:`ABC`
+ avoiding sometimes confusing metaclass usage, for example::
+
+ from abc import ABC
+
+ class MyABC(ABC):
+ pass
+
+ Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
+ inheriting from :class:`ABC` requires the usual precautions regarding
+ metaclass usage, as multiple inheritance may lead to metaclass conflicts.
+ One may also define an abstract base class by passing the metaclass
+ keyword and using :class:`ABCMeta` directly, for example::
+
+ from abc import ABCMeta
+
+ class MyABC(metaclass=ABCMeta):
+ pass
+
+ .. versionadded:: 3.4
+
.. class:: ABCMeta
@@ -46,15 +72,15 @@ This module provides the following classes:
Register *subclass* as a "virtual subclass" of this ABC. For
example::
- from abc import ABCMeta
+ from abc import ABC
- class MyABC(metaclass=ABCMeta):
- pass
+ class MyABC(ABC):
+ pass
- MyABC.register(tuple)
+ MyABC.register(tuple)
- assert issubclass(tuple, MyABC)
- assert isinstance((), MyABC)
+ assert issubclass(tuple, MyABC)
+ assert isinstance((), MyABC)
.. versionchanged:: 3.3
Returns the registered subclass, to allow usage as a class decorator.
@@ -95,7 +121,7 @@ This module provides the following classes:
def get_iterator(self):
return iter(self)
- class MyIterable(metaclass=ABCMeta):
+ class MyIterable(ABC):
@abstractmethod
def __iter__(self):
@@ -132,20 +158,9 @@ This module provides the following classes:
available as a method of ``Foo``, so it is provided separately.
-.. class:: ABC
-
- A helper class that has :class:`ABCMeta` as its metaclass. With this class,
- an abstract base class can be created by simply deriving from :class:`ABC`,
- avoiding sometimes confusing metaclass usage.
-
- Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore
- inheriting from :class:`ABC` requires the usual precautions regarding metaclass
- usage, as multiple inheritance may lead to metaclass conflicts.
-
- .. versionadded:: 3.4
-The :mod:`abc` module also provides the following decorators:
+The :mod:`abc` module also provides the following decorator:
.. decorator:: abstractmethod
@@ -168,7 +183,7 @@ The :mod:`abc` module also provides the following decorators:
descriptors, it should be applied as the innermost decorator, as shown in
the following usage examples::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@abstractmethod
def my_abstract_method(self, ...):
...
@@ -202,7 +217,7 @@ The :mod:`abc` module also provides the following decorators:
the descriptor must identify itself as abstract using
:attr:`__isabstractmethod__`. In general, this attribute should be ``True``
if any of the methods used to compose the descriptor are abstract. For
- example, Python's built-in property does the equivalent of::
+ example, Python's built-in :class:`property` does the equivalent of::
class Descriptor:
...
@@ -221,8 +236,15 @@ The :mod:`abc` module also provides the following decorators:
multiple-inheritance.
+The :mod:`abc` module also supports the following legacy decorators:
+
.. decorator:: abstractclassmethod
+ .. versionadded:: 3.2
+ .. deprecated:: 3.3
+ It is now possible to use :class:`classmethod` with
+ :func:`abstractmethod`, making this decorator redundant.
+
A subclass of the built-in :func:`classmethod`, indicating an abstract
classmethod. Otherwise it is similar to :func:`abstractmethod`.
@@ -230,20 +252,20 @@ The :mod:`abc` module also provides the following decorators:
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@classmethod
@abstractmethod
def my_abstract_classmethod(cls, ...):
...
+
+.. decorator:: abstractstaticmethod
+
.. versionadded:: 3.2
.. deprecated:: 3.3
- It is now possible to use :class:`classmethod` with
+ It is now possible to use :class:`staticmethod` with
:func:`abstractmethod`, making this decorator redundant.
-
-.. decorator:: abstractstaticmethod
-
A subclass of the built-in :func:`staticmethod`, indicating an abstract
staticmethod. Otherwise it is similar to :func:`abstractmethod`.
@@ -251,34 +273,28 @@ The :mod:`abc` module also provides the following decorators:
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@staticmethod
@abstractmethod
def my_abstract_staticmethod(...):
...
- .. versionadded:: 3.2
- .. deprecated:: 3.3
- It is now possible to use :class:`staticmethod` with
- :func:`abstractmethod`, making this decorator redundant.
+.. decorator:: abstractproperty
-.. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
+ .. deprecated:: 3.3
+ It is now possible to use :class:`property`, :meth:`property.getter`,
+ :meth:`property.setter` and :meth:`property.deleter` with
+ :func:`abstractmethod`, making this decorator redundant.
A subclass of the built-in :func:`property`, indicating an abstract
property.
- Using this function requires that the class's metaclass is :class:`ABCMeta`
- or is derived from it. A class that has a metaclass derived from
- :class:`ABCMeta` cannot be instantiated unless all of its abstract methods
- and properties are overridden. The abstract properties can be called using
- any of the normal 'super' call mechanisms.
-
This special case is deprecated, as the :func:`property` decorator
is now correctly identified as abstract when applied to an abstract
method::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@property
@abstractmethod
def my_abstract_property(self):
@@ -288,7 +304,7 @@ The :mod:`abc` module also provides the following decorators:
read-write abstract property by appropriately marking one or more of the
underlying methods as abstract::
- class C(metaclass=ABCMeta):
+ class C(ABC):
@property
def x(self):
...
@@ -307,12 +323,6 @@ The :mod:`abc` module also provides the following decorators:
...
- .. deprecated:: 3.3
- It is now possible to use :class:`property`, :meth:`property.getter`,
- :meth:`property.setter` and :meth:`property.deleter` with
- :func:`abstractmethod`, making this decorator redundant.
-
-
The :mod:`abc` module also provides the following functions:
.. function:: get_cache_token()
diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
index 23a96207d083894..970a7aeb98a7139 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -18,12 +18,6 @@ AIFF is Audio Interchange File Format, a format for storing digital audio
samples in a file. AIFF-C is a newer version of the format that includes the
ability to compress the audio data.
-.. note::
-
- Some operations may only work under IRIX; these will raise :exc:`ImportError`
- when attempting to import the :mod:`cl` module, which is only available on
- IRIX.
-
Audio files have a number of parameters that describe the audio data. The
sampling rate or frame rate is the number of times per second the sound is
sampled. The number of channels indicate if the audio is mono, stereo, or
diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 45303048174dfab..5196202c47231b4 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -426,7 +426,9 @@ should not be line-wrapped::
-h, --help show this help message and exit
:class:`RawTextHelpFormatter` maintains whitespace for all sorts of help text,
-including argument descriptions.
+including argument descriptions. However, multiple new lines are replaced with
+one. If you wish to preserve multiple blank lines, add spaces between the
+newlines.
:class:`ArgumentDefaultsHelpFormatter` automatically adds information about
default values to each of the argument help messages::
@@ -710,7 +712,7 @@ be positional::
Namespace(bar='BAR', foo='FOO')
>>> parser.parse_args(['--foo', 'FOO'])
usage: PROG [-h] [-f FOO] bar
- PROG: error: too few arguments
+ PROG: error: the following arguments are required: bar
action
@@ -842,6 +844,8 @@ values are:
Note that ``nargs=1`` produces a list of one item. This is different from
the default, in which the item is produced by itself.
+.. index:: single: ? (question mark); in argparse module
+
* ``'?'``. One argument will be consumed from the command line if possible, and
produced as a single item. If no command-line argument is present, the value from
default_ will be produced. Note that for optional arguments, there is an
@@ -874,6 +878,8 @@ values are:
Namespace(infile=<_io.TextIOWrapper name='' encoding='UTF-8'>,
outfile=<_io.TextIOWrapper name='' encoding='UTF-8'>)
+.. index:: single: * (asterisk); in argparse module
+
* ``'*'``. All command-line arguments present are gathered into a list. Note that
it generally doesn't make much sense to have more than one positional argument
with ``nargs='*'``, but multiple optional arguments with ``nargs='*'`` is
@@ -886,6 +892,8 @@ values are:
>>> parser.parse_args('a b --foo x y --bar 1 2'.split())
Namespace(bar=['1', '2'], baz=['a', 'b'], foo=['x', 'y'])
+.. index:: single: + (plus); in argparse module
+
* ``'+'``. Just like ``'*'``, all command-line args present are gathered into a
list. Additionally, an error message will be generated if there wasn't at
least one command-line argument present. For example::
@@ -896,7 +904,9 @@ values are:
Namespace(foo=['a', 'b'])
>>> parser.parse_args([])
usage: PROG [-h] foo [foo ...]
- PROG: error: too few arguments
+ PROG: error: the following arguments are required: foo
+
+.. _`argparse.REMAINDER`:
* ``argparse.REMAINDER``. All the remaining command-line arguments are gathered
into a list. This is commonly useful for command line utilities that dispatch
@@ -977,7 +987,7 @@ is used when no command-line argument was present::
Providing ``default=argparse.SUPPRESS`` causes no attribute to be added if the
-command-line argument was not present.::
+command-line argument was not present::
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default=argparse.SUPPRESS)
@@ -1324,8 +1334,11 @@ The parse_args() method
created and how they are assigned. See the documentation for
:meth:`add_argument` for details.
- By default, the argument strings are taken from :data:`sys.argv`, and a new empty
- :class:`Namespace` object is created for the attributes.
+ * args_ - List of strings to parse. The default is taken from
+ :data:`sys.argv`.
+
+ * namespace_ - An object to take the attributes. The default is a new empty
+ :class:`Namespace` object.
Option value syntax
@@ -1467,6 +1480,7 @@ unambiguous (the prefix matches a unique option)::
An error is produced for arguments that could produce more than one options.
This feature can be disabled by setting :ref:`allow_abbrev` to ``False``.
+.. _args:
Beyond ``sys.argv``
^^^^^^^^^^^^^^^^^^^
@@ -1488,6 +1502,7 @@ interactive prompt::
>>> parser.parse_args(['1', '2', '3', '4', '--sum'])
Namespace(accumulate=, integers=[1, 2, 3, 4])
+.. _namespace:
The Namespace object
^^^^^^^^^^^^^^^^^^^^
@@ -2008,7 +2023,12 @@ A partial upgrade path from :mod:`optparse` to :mod:`argparse`:
* Replace ``(options, args) = parser.parse_args()`` with ``args =
parser.parse_args()`` and add additional :meth:`ArgumentParser.add_argument`
calls for the positional arguments. Keep in mind that what was previously
- called ``options``, now in :mod:`argparse` context is called ``args``.
+ called ``options``, now in the :mod:`argparse` context is called ``args``.
+
+* Replace :meth:`optparse.OptionParser.disable_interspersed_args`
+ by setting ``nargs`` of a positional argument to `argparse.REMAINDER`_, or
+ use :meth:`~ArgumentParser.parse_known_args` to collect unparsed argument
+ strings in a separate list.
* Replace callback actions and the ``callback_*`` keyword arguments with
``type`` or ``action`` arguments.
diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst
index 8d4ae2cc616fa3a..eb6675497f97343 100644
--- a/Doc/library/ast.rst
+++ b/Doc/library/ast.rst
@@ -41,6 +41,9 @@ Node classes
with alternatives (aka "sums"), the left-hand side class is abstract: only
instances of specific constructor nodes are ever created.
+ .. index:: single: ? (question mark); in AST grammar
+ .. index:: single: * (asterisk); in AST grammar
+
.. attribute:: _fields
Each concrete class has an attribute :attr:`_fields` which gives the names
@@ -113,6 +116,11 @@ and classes for traversing abstract syntax trees:
Parse the source into an AST node. Equivalent to ``compile(source,
filename, mode, ast.PyCF_ONLY_AST)``.
+ .. warning::
+ It is possible to crash the Python interpreter with a
+ sufficiently large/complex string due to stack depth limitations
+ in Python's AST compiler.
+
.. function:: literal_eval(node_or_string)
@@ -126,6 +134,11 @@ and classes for traversing abstract syntax trees:
capable of evaluating arbitrarily complex expressions, for example involving
operators or indexing.
+ .. warning::
+ It is possible to crash the Python interpreter with a
+ sufficiently large/complex string due to stack depth limitations
+ in Python's AST compiler.
+
.. versionchanged:: 3.2
Now allows bytes and set literals.
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index cc4a14b2016226c..e2ad3eb0196c93c 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -52,7 +52,7 @@ Cancellation
------------
Cancellation of tasks is not common in classic programming. In asynchronous
-programming, not only it is something common, but you have to prepare your
+programming, not only is it something common, but you have to prepare your
code to handle it.
Futures and tasks can be cancelled explicitly with their :meth:`Future.cancel`
@@ -209,9 +209,9 @@ The fix is to call the :func:`ensure_future` function or the
Detect exceptions never consumed
--------------------------------
-Python usually calls :func:`sys.displayhook` on unhandled exceptions. If
+Python usually calls :func:`sys.excepthook` on unhandled exceptions. If
:meth:`Future.set_exception` is called, but the exception is never consumed,
-:func:`sys.displayhook` is not called. Instead, :ref:`a log is emitted
+:func:`sys.excepthook` is not called. Instead, :ref:`a log is emitted
` when the future is deleted by the garbage collector, with the
traceback where the exception was raised.
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index fa6a29604ca2ba4..d053a60a9ea6c32 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -5,6 +5,8 @@
Base Event Loop
===============
+**Source code:** :source:`Lib/asyncio/events.py`
+
The event loop is the central execution device provided by :mod:`asyncio`.
It provides multiple facilities, including:
@@ -339,6 +341,23 @@ Creating connections
.. coroutinemethod:: AbstractEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
+ .. note::
+ The parameter *reuse_address* is no longer supported, as using
+ :py:data:`~sockets.SO_REUSEADDR` poses a significant security concern for
+ UDP. Explicitly passing ``reuse_address=True`` will raise an exception.
+
+ When multiple processes with differing UIDs assign sockets to an
+ indentical UDP socket address with ``SO_REUSEADDR``, incoming packets can
+ become randomly distributed among the sockets.
+
+ For supported platforms, *reuse_port* can be used as a replacement for
+ similar functionality. With *reuse_port*,
+ :py:data:`~sockets.SO_REUSEPORT` is used instead, which specifically
+ prevents processes with differing UIDs from assigning sockets to the same
+ socket address.
+
+ Create a datagram connection.
+
Create datagram connection: socket family :py:data:`~socket.AF_INET` or
:py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
socket type :py:data:`~socket.SOCK_DGRAM`. *protocol_factory* must be a
@@ -363,11 +382,6 @@ Creating connections
resolution. If given, these should all be integers from the
corresponding :mod:`socket` module constants.
- * *reuse_address* tells the kernel to reuse a local socket in
- TIME_WAIT state, without waiting for its natural timeout to
- expire. If not specified will automatically be set to ``True`` on
- UNIX.
-
* *reuse_port* tells the kernel to allow this endpoint to be bound to the
same port as other existing endpoints are bound to, so long as they all
set this flag when being created. This option is not supported on Windows
@@ -387,6 +401,14 @@ Creating connections
See :ref:`UDP echo client protocol ` and
:ref:`UDP echo server protocol ` examples.
+ .. versionchanged:: 3.4.4
+ The *family*, *proto*, *flags*, *reuse_address*, *reuse_port,
+ *allow_broadcast*, and *sock* parameters were added.
+
+ .. versionchanged:: 3.6.10
+ The *reuse_address* parameter is no longer supporter due to security
+ concerns
+
.. coroutinemethod:: AbstractEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
@@ -498,6 +520,9 @@ Creating listening connections
This method is a :ref:`coroutine `. When completed, the
coroutine returns a ``(transport, protocol)`` pair.
+ .. versionadded:: 3.5.3
+
+
Watch file descriptors
----------------------
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
index 1dc18fce79d021f..3aa9ffeff268c42 100644
--- a/Doc/library/asyncio-eventloops.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -3,6 +3,8 @@
Event loops
===========
+**Source code:** :source:`Lib/asyncio/events.py`
+
Event loop functions
--------------------
@@ -146,10 +148,9 @@ process based on the calling context. A policy is an object implementing the
:class:`AbstractEventLoopPolicy` interface.
For most users of :mod:`asyncio`, policies never have to be dealt with
-explicitly, since the default global policy is sufficient.
+explicitly, since the default global policy is sufficient (see below).
-The default policy defines context as the current thread, and manages an event
-loop per thread that interacts with :mod:`asyncio`. The module-level functions
+The module-level functions
:func:`get_event_loop` and :func:`set_event_loop` provide convenient access to
event loops managed by the default policy.
@@ -168,12 +169,15 @@ An event loop policy must implement the following interface:
Get the event loop for the current context.
Returns an event loop object implementing the :class:`AbstractEventLoop`
- interface.
+ interface. In case called from coroutine, it returns the currently
+ running event loop.
Raises an exception in case no event loop has been set for the current
context and the current policy does not specify to create one. It must
never return ``None``.
+ .. versionchanged:: 3.6
+
.. method:: set_event_loop(loop)
Set the event loop for the current context to *loop*.
@@ -187,6 +191,13 @@ An event loop policy must implement the following interface:
context, :meth:`set_event_loop` must be called explicitly.
+The default policy defines context as the current thread, and manages an event
+loop per thread that interacts with :mod:`asyncio`. If the current thread
+doesn't already have an event loop associated with it, the default policy's
+:meth:`~AbstractEventLoopPolicy.get_event_loop` method creates one when
+called from the main thread, but raises :exc:`RuntimeError` otherwise.
+
+
Access to the global loop policy
--------------------------------
@@ -198,3 +209,24 @@ Access to the global loop policy
Set the current event loop policy. If *policy* is ``None``, the default
policy is restored.
+
+
+Customizing the event loop policy
+---------------------------------
+
+To implement a new event loop policy, it is recommended you subclass the
+concrete default event loop policy :class:`DefaultEventLoopPolicy`
+and override the methods for which you want to change behavior, for example::
+
+ class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+
+ def get_event_loop(self):
+ """Get the event loop.
+
+ This may be None or an instance of EventLoop.
+ """
+ loop = super().get_event_loop()
+ # Do something with loop ...
+ return loop
+
+ asyncio.set_event_loop_policy(MyEventLoopPolicy())
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
index 3fbf51058673d92..9605261c0a3f46c 100644
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -1,8 +1,12 @@
.. currentmodule:: asyncio
-++++++++++++++++++++++++++++++++++++++++++++++
-Transports and protocols (callback based API)
-++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++
+Transports and protocols (callback based API)
++++++++++++++++++++++++++++++++++++++++++++++
+
+**Source code:** :source:`Lib/asyncio/transports.py`
+
+**Source code:** :source:`Lib/asyncio/protocols.py`
.. _asyncio-transport:
@@ -36,7 +40,7 @@ BaseTransport
Base class for transports.
- .. method:: close(self)
+ .. method:: close()
Close the transport. If the transport has a buffer for outgoing
data, buffered data will be flushed asynchronously. No more data
@@ -44,7 +48,7 @@ BaseTransport
protocol's :meth:`connection_lost` method will be called with
:const:`None` as its argument.
- .. method:: is_closing(self)
+ .. method:: is_closing()
Return ``True`` if the transport is closing or is closed.
@@ -120,11 +124,19 @@ ReadTransport
the protocol's :meth:`data_received` method until :meth:`resume_reading`
is called.
+ .. versionchanged:: 3.6.7
+ The method is idempotent, i.e. it can be called when the
+ transport is already paused or closed.
+
.. method:: resume_reading()
Resume the receiving end. The protocol's :meth:`data_received` method
will be called once again if some data is available for reading.
+ .. versionchanged:: 3.6.7
+ The method is idempotent, i.e. it can be called when the
+ transport is already reading.
+
WriteTransport
--------------
@@ -163,11 +175,17 @@ WriteTransport
Set the *high*- and *low*-water limits for write flow control.
- These two values control when call the protocol's
+ These two values (measured in number of
+ bytes) control when the protocol's
:meth:`pause_writing` and :meth:`resume_writing` methods are called.
If specified, the low-water limit must be less than or equal to the
high-water limit. Neither *high* nor *low* can be negative.
+ :meth:`pause_writing` is called when the buffer size becomes greater
+ than or equal to the *high* value. If writing has been paused,
+ :meth:`resume_writing` is called when the buffer size becomes less
+ than or equal to the *low* value.
+
The defaults are implementation-specific. If only the
high-water limit is given, the low-water limit defaults to an
implementation-specific value less than or equal to the
@@ -251,7 +269,7 @@ BaseSubprocessTransport
if it hasn't returned, similarly to the
:attr:`subprocess.Popen.returncode` attribute.
- .. method:: kill(self)
+ .. method:: kill()
Kill the subprocess, as in :meth:`subprocess.Popen.kill`.
@@ -384,7 +402,7 @@ The following callbacks are called on :class:`Protocol` instances:
.. method:: Protocol.eof_received()
- Calls when the other end signals it won't send any more data
+ Called when the other end signals it won't send any more data
(for example by calling :meth:`write_eof`, if the other end also uses
asyncio).
diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index f11c09ac29055e9..ea78755008244d8 100644
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -3,6 +3,8 @@
Queues
======
+**Source code:** :source:`Lib/asyncio/queues.py`
+
Queues:
* :class:`Queue`
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 6177b4bb0f8b14f..a510e1e638a73d8 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -6,6 +6,8 @@
Streams (coroutine based API)
+++++++++++++++++++++++++++++
+**Source code:** :source:`Lib/asyncio/streams.py`
+
Stream functions
================
@@ -86,10 +88,12 @@ Stream functions
StreamReader
============
-.. class:: StreamReader(limit=None, loop=None)
+.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
This class is :ref:`not thread safe `.
+ The *limit* argument's default value is set to _DEFAULT_LIMIT which is 2**16 (64 KiB)
+
.. method:: exception()
Get the exception.
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
index dc93a74c6dee126..1c1d0be918da74c 100644
--- a/Doc/library/asyncio-subprocess.rst
+++ b/Doc/library/asyncio-subprocess.rst
@@ -5,6 +5,8 @@
Subprocess
==========
+**Source code:** :source:`Lib/asyncio/subprocess.py`
+
Windows event loop
------------------
@@ -80,7 +82,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
however, where :class:`~subprocess.Popen` takes a single argument which is
list of strings, :func:`subprocess_exec` takes multiple string arguments.
- The *protocol_factory* must instanciate a subclass of the
+ The *protocol_factory* must instantiate a subclass of the
:class:`asyncio.SubprocessProtocol` class.
Other parameters:
@@ -123,7 +125,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
using the platform's "shell" syntax. This is similar to the standard library
:class:`subprocess.Popen` class called with ``shell=True``.
- The *protocol_factory* must instanciate a subclass of the
+ The *protocol_factory* must instantiate a subclass of the
:class:`asyncio.SubprocessProtocol` class.
See :meth:`~AbstractEventLoop.subprocess_exec` for more details about
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
index 09093521524a89b..14e3defbf4118a6 100644
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -4,6 +4,8 @@
Synchronization primitives
==========================
+**Source code:** :source:`Lib/asyncio/locks.py`
+
Locks:
* :class:`Lock`
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 558d17c09697931..c0383331c1edf67 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -3,6 +3,10 @@
Tasks and coroutines
====================
+**Source code:** :source:`Lib/asyncio/tasks.py`
+
+**Source code:** :source:`Lib/asyncio/coroutines.py`
+
.. _coroutine:
Coroutines
@@ -212,7 +216,7 @@ Future
raise an exception when the future isn't done yet.
- Callbacks registered with :meth:`add_done_callback` are always called
- via the event loop's :meth:`~AbstractEventLoop.call_soon_threadsafe`.
+ via the event loop's :meth:`~AbstractEventLoop.call_soon`.
- This class is not compatible with the :func:`~concurrent.futures.wait` and
:func:`~concurrent.futures.as_completed` functions in the
@@ -540,6 +544,11 @@ Task functions
.. deprecated:: 3.4.4
+.. function:: wrap_future(future, \*, loop=None)
+
+ Wrap a :class:`concurrent.futures.Future` object in a :class:`Future`
+ object.
+
.. function:: gather(\*coros_or_futures, loop=None, return_exceptions=False)
Return a future aggregating results from the given coroutine objects or
@@ -559,6 +568,10 @@ Task functions
outer Future is *not* cancelled in this case. (This is to prevent the
cancellation of one child to cause other children to be cancelled.)
+ .. versionchanged:: 3.6.6
+ If the *gather* itself is cancelled, the cancellation is propagated
+ regardless of *return_exceptions*.
+
.. function:: iscoroutine(obj)
Return ``True`` if *obj* is a :ref:`coroutine object `,
@@ -621,7 +634,7 @@ Task functions
This function is a :ref:`coroutine `.
-.. function:: shield(arg, \*, loop=None)
+.. coroutinefunction:: shield(arg, \*, loop=None)
Wait for a future, shielding it from cancellation.
diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index 1d84d4587fd9c00..5c60b604c68301e 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -21,7 +21,7 @@ program is killed by a signal not handled by Python, when a Python fatal
internal error is detected, or when :func:`os._exit` is called.
-.. function:: register(func, *args, **kargs)
+.. function:: register(func, *args, **kwargs)
Register *func* as a function to be executed at termination. Any optional
arguments that are to be passed to *func* must be passed as arguments to
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 080d9d77ec984ea..ad9f5f58bee2aac 100644
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -218,14 +218,6 @@ The modern interface provides:
.. versionadded:: 3.4
-.. note::
- Both Base85 and Ascii85 have an expansion factor of 5 to 4 (5 Base85 or
- Ascii85 characters can encode 4 binary bytes), while the better-known
- Base64 has an expansion factor of 6 to 4. They are therefore more
- efficient when space expensive. They differ by details such as the
- character map used for encoding.
-
-
The legacy interface:
.. function:: decode(input, output)
@@ -237,14 +229,18 @@ The legacy interface:
.. function:: decodebytes(s)
- decodestring(s)
Decode the :term:`bytes-like object` *s*, which must contain one or more
lines of base64 encoded data, and return the decoded :class:`bytes`.
- ``decodestring`` is a deprecated alias.
.. versionadded:: 3.1
+.. function:: decodestring(s)
+
+ Deprecated alias of :func:`decodebytes`.
+
+ .. deprecated:: 3.1
+
.. function:: encode(input, output)
@@ -257,14 +253,19 @@ The legacy interface:
.. function:: encodebytes(s)
- encodestring(s)
Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary
data, and return :class:`bytes` containing the base64-encoded data, with newlines
(``b'\n'``) inserted after every 76 bytes of output, and ensuring that
there is a trailing newline, as per :rfc:`2045` (MIME).
- ``encodestring`` is a deprecated alias.
+ .. versionadded:: 3.1
+
+.. function:: encodestring(s)
+
+ Deprecated alias of :func:`encodebytes`.
+
+ .. deprecated:: 3.1
An example usage of the module:
diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
index 0476f507717cda3..adb087ef8826bf0 100644
--- a/Doc/library/binascii.rst
+++ b/Doc/library/binascii.rst
@@ -77,7 +77,7 @@ The :mod:`binascii` module defines the following functions:
*quotetabs* is present and true, all tabs and spaces will be encoded. If the
optional argument *istext* is present and true, newlines are not encoded but
trailing whitespace will be encoded. If the optional argument *header* is
- present and true, spaces will be encoded as underscores per RFC1522. If the
+ present and true, spaces will be encoded as underscores per :rfc:`1522`. If the
optional argument *header* is present and false, newline characters will be
encoded as well; otherwise linefeed conversion might corrupt the binary data
stream.
diff --git a/Doc/library/binhex.rst b/Doc/library/binhex.rst
index 359ab23b2f9787d..2966e0dbfbcfe87 100644
--- a/Doc/library/binhex.rst
+++ b/Doc/library/binhex.rst
@@ -55,5 +55,3 @@ the source for details.
If you code or decode textfiles on non-Macintosh platforms they will still use
the old Macintosh newline convention (carriage-return as end of line).
-As of this writing, :func:`hexbin` appears to not work in all cases.
-
diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index 41219eeaabae087..a3dad1b8b03188c 100644
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -277,13 +277,12 @@ These are useful if you want more control, or if you want to employ some of the
algorithms implemented in this module in other circumstances.
-.. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False)
+.. function:: parse(fp=None, environ=os.environ, keep_blank_values=False, strict_parsing=False, separator="&")
Parse a query in the environment or from a file (the file defaults to
- ``sys.stdin``). The *keep_blank_values* and *strict_parsing* parameters are
+ ``sys.stdin``). The *keep_blank_values*, *strict_parsing* and *separator* parameters are
passed to :func:`urllib.parse.parse_qs` unchanged.
-
.. function:: parse_qs(qs, keep_blank_values=False, strict_parsing=False)
This function is deprecated in this module. Use :func:`urllib.parse.parse_qs`
@@ -308,6 +307,9 @@ algorithms implemented in this module in other circumstances.
Note that this does not parse nested multipart parts --- use
:class:`FieldStorage` for that.
+ .. versionchanged:: 3.6.13
+ Added the *separator* parameter.
+
.. function:: parse_header(string)
diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst
index f40cfdfd5921632..d57edb7eb1698d2 100644
--- a/Doc/library/cmd.rst
+++ b/Doc/library/cmd.rst
@@ -61,6 +61,10 @@ A :class:`Cmd` instance has the following methods:
An end-of-file on input is passed back as the string ``'EOF'``.
+ .. index::
+ single: ? (question mark); in a command interpreter
+ single: ! (exclamation); in a command interpreter
+
An interpreter instance will recognize a command name ``foo`` if and only if it
has a method :meth:`do_foo`. As a special case, a line beginning with the
character ``'?'`` is dispatched to the method :meth:`do_help`. As another
@@ -266,10 +270,10 @@ immediate playback::
'Draw circle with given radius an options extent and steps: CIRCLE 50'
circle(*parse(arg))
def do_position(self, arg):
- 'Print the current turle position: POSITION'
+ 'Print the current turtle position: POSITION'
print('Current position is %d %d\n' % position())
def do_heading(self, arg):
- 'Print the current turle heading in degrees: HEADING'
+ 'Print the current turtle heading in degrees: HEADING'
print('Current heading is %d\n' % (heading(),))
def do_color(self, arg):
'Set the color: COLOR BLUE'
diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 0ecd89ba75b617b..992135154fd6c05 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -312,6 +312,14 @@ defined and implemented by all standard Python codecs:
The following error handlers are only applicable to
:term:`text encodings `:
+.. index::
+ single: ? (question mark); replacement character
+ single: \ (backslash); escape sequence
+ single: \x; escape sequence
+ single: \u; escape sequence
+ single: \U; escape sequence
+ single: \N; escape sequence
+
+-------------------------+-----------------------------------------------+
| Value | Meaning |
+=========================+===============================================+
@@ -554,19 +562,19 @@ define in order to be compatible with the Python codec registry.
if necessary, to reset the encoder and to get the output.
-.. method:: IncrementalEncoder.getstate()
+ .. method:: getstate()
- Return the current state of the encoder which must be an integer. The
- implementation should make sure that ``0`` is the most common state. (States
- that are more complicated than integers can be converted into an integer by
- marshaling/pickling the state and encoding the bytes of the resulting string
- into an integer).
+ Return the current state of the encoder which must be an integer. The
+ implementation should make sure that ``0`` is the most common
+ state. (States that are more complicated than integers can be converted
+ into an integer by marshaling/pickling the state and encoding the bytes
+ of the resulting string into an integer).
-.. method:: IncrementalEncoder.setstate(state)
+ .. method:: setstate(state)
- Set the state of the encoder to *state*. *state* must be an encoder state
- returned by :meth:`getstate`.
+ Set the state of the encoder to *state*. *state* must be an encoder state
+ returned by :meth:`getstate`.
.. _incremental-decoder-objects:
@@ -802,7 +810,7 @@ The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
-.. class:: StreamReaderWriter(stream, Reader, Writer, errors)
+.. class:: StreamReaderWriter(stream, Reader, Writer, errors='strict')
Creates a :class:`StreamReaderWriter` instance. *stream* must be a file-like
object. *Reader* and *Writer* must be factory functions or classes providing the
@@ -826,7 +834,7 @@ The design is such that one can use the factory functions returned by the
:func:`lookup` function to construct the instance.
-.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors)
+.. class:: StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')
Creates a :class:`StreamRecoder` instance which implements a two-way conversion:
*encode* and *decode* work on the frontend — the data visible to
@@ -977,10 +985,14 @@ e.g. ``'utf-8'`` is a valid alias for the ``'utf_8'`` codec.
Some common encodings can bypass the codecs lookup machinery to
improve performance. These optimization opportunities are only
- recognized by CPython for a limited set of aliases: utf-8, utf8,
- latin-1, latin1, iso-8859-1, mbcs (Windows only), ascii, utf-16,
- and utf-32. Using alternative spellings for these encodings may
- result in slower execution.
+ recognized by CPython for a limited set of (case insensitive)
+ aliases: utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs
+ (Windows only), ascii, us-ascii, utf-16, utf16, utf-32, utf32, and
+ the same using underscores instead of dashes. Using alternative
+ aliases for these encodings may result in slower execution.
+
+ .. versionchanged:: 3.6
+ Optimization opportunity recognized for us-ascii.
Many of the character sets support the same languages. They vary in individual
characters (e.g. whether the EURO SIGN is supported or not), and in the
@@ -1109,10 +1121,10 @@ particular, the following variants typically exist:
| | ks_c-5601, ks_c-5601-1987, | |
| | ksx1001, ks_x-1001 | |
+-----------------+--------------------------------+--------------------------------+
-| gb2312 | chinese, csiso58gb231280, euc- | Simplified Chinese |
-| | cn, euccn, eucgb2312-cn, | |
-| | gb2312-1980, gb2312-80, iso- | |
-| | ir-58 | |
+| gb2312 | chinese, csiso58gb231280, | Simplified Chinese |
+| | euc-cn, euccn, eucgb2312-cn, | |
+| | gb2312-1980, gb2312-80, | |
+| | iso-ir-58 | |
+-----------------+--------------------------------+--------------------------------+
| gbk | 936, cp936, ms936 | Unified Chinese |
+-----------------+--------------------------------+--------------------------------+
@@ -1421,7 +1433,7 @@ to the user.
Python supports this conversion in several ways: the ``idna`` codec performs
conversion between Unicode and ACE, separating an input string into labels
-based on the separator characters defined in `section 3.1`_ (1) of :rfc:`3490`
+based on the separator characters defined in :rfc:`section 3.1 of RFC 3490 <3490#section-3.1>`
and converting each label to ACE as required, and conversely separating an input
byte string into labels based on the ``.`` separator and converting any ACE
labels found into unicode. Furthermore, the :mod:`socket` module
@@ -1432,8 +1444,6 @@ parameters, such as :mod:`http.client` and :mod:`ftplib`, accept Unicode host
names (:mod:`http.client` then also transparently sends an IDNA hostname in the
:mailheader:`Host` field if it sends that field at all).
-.. _section 3.1: https://tools.ietf.org/html/rfc3490#section-3.1
-
When receiving host names from the wire (such as in reverse name lookup), no
automatic conversion to Unicode is performed: Applications wishing to present
such host names to the user should decode them to Unicode.
diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 58b03b9bd768042..60154532094423b 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -107,7 +107,12 @@ ABC Inherits from Abstract Methods Mixin
.. class:: Iterable
ABC for classes that provide the :meth:`__iter__` method.
- See also the definition of :term:`iterable`.
+
+ Checking ``isinstance(obj, Iterable)`` detects classes that are registered
+ as :class:`Iterable` or that have an :meth:`__iter__` method, but it does
+ not detect classes that iterate with the :meth:`__getitem__` method.
+ The only reliable way to determine whether an object is :term:`iterable`
+ is to call ``iter(obj)``.
.. class:: Collection
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
index 8e2eb4d9b0382f4..25687348d16deef 100644
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -198,6 +198,7 @@ updates keys found deeper in the chain::
>>> d['lion'] = 'orange' # update an existing key two levels down
>>> d['snake'] = 'red' # new keys get added to the topmost dict
>>> del d['elephant'] # remove an existing key one level down
+ >>> d # display result
DeepChainMap({'zebra': 'black', 'snake': 'red'}, {}, {'lion': 'orange'})
@@ -509,11 +510,14 @@ or subtracting from an empty counter.
.. versionadded:: 3.2
- .. method:: rotate(n)
+ .. method:: rotate(n=1)
- Rotate the deque *n* steps to the right. If *n* is negative, rotate to
- the left. Rotating one step to the right is equivalent to:
- ``d.appendleft(d.pop())``.
+ Rotate the deque *n* steps to the right. If *n* is negative, rotate
+ to the left.
+
+ When the deque is not empty, rotating one step to the right is equivalent
+ to ``d.appendleft(d.pop())``, and rotating one step to the left is
+ equivalent to ``d.append(d.popleft())``.
Deque objects also provide one read-only attribute:
@@ -771,9 +775,9 @@ they add the ability to access fields by name instead of position index.
helpful docstring (with typename and field_names) and a helpful :meth:`__repr__`
method which lists the tuple contents in a ``name=value`` format.
- The *field_names* are a single string with each fieldname separated by whitespace
- and/or commas, for example ``'x y'`` or ``'x, y'``. Alternatively, *field_names*
- can be a sequence of strings such as ``['x', 'y']``.
+ The *field_names* are a sequence of strings such as ``['x', 'y']``.
+ Alternatively, *field_names* can be a single string with each fieldname
+ separated by whitespace and/or commas, for example ``'x y'`` or ``'x, y'``.
Any valid Python identifier may be used for a fieldname except for names
starting with an underscore. Valid identifiers consist of letters, digits,
@@ -866,7 +870,7 @@ field names, the method and attribute names start with an underscore.
.. versionchanged:: 3.1
Returns an :class:`OrderedDict` instead of a regular :class:`dict`.
-.. method:: somenamedtuple._replace(kwargs)
+.. method:: somenamedtuple._replace(**kwargs)
Return a new instance of the named tuple replacing specified fields with new
values::
diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst
index d85576b8bedd8ee..319f757aa9063d9 100644
--- a/Doc/library/concurrent.futures.rst
+++ b/Doc/library/concurrent.futures.rst
@@ -40,21 +40,29 @@ Executor Objects
.. method:: map(func, *iterables, timeout=None, chunksize=1)
- Equivalent to :func:`map(func, *iterables)