From: DongHun Kwak Date: Wed, 22 Aug 2018 06:55:10 +0000 (+0900) Subject: Imported Upstream version 2.7.14 X-Git-Tag: upstream/2.7.14 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F49%2F187349%2F1;p=platform%2Fupstream%2Fpython.git Imported Upstream version 2.7.14 Change-Id: Icfe8dc39f6e866f9cdf059cfd57789fed01f9469 Signed-off-by: DongHun Kwak --- diff --git a/Demo/turtle/tdemo_two_canvases.py b/Demo/turtle/tdemo_two_canvases.py old mode 100644 new mode 100755 diff --git a/Doc/Makefile b/Doc/Makefile index c3f1b37..ebabc02 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -10,7 +10,7 @@ PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) -ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ +ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_elements.papersize=$(PAPER) \ $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) .PHONY: help build html htmlhelp latex text changes linkcheck \ @@ -157,12 +157,12 @@ serve: # for development releases: always build autobuild-dev: - make dist SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' + make dist SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A switchers=1' -make suspicious # for quick rebuilds (HTML only) autobuild-dev-html: - make html SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A versionswitcher=1' + make html SPHINXOPTS='$(SPHINXOPTS) -A daily=1 -A switchers=1' # for stable releases: only build if not in pre-release stage (alpha, beta) # release candidate downloads are okay, since the stable tree can be in that stage diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 10e2c4c..db302d8 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -286,16 +286,11 @@ is a separate error indicator for each thread. exception handling (for example, :c:func:`Py_DECREF` owned references and return an error value). - Warning categories must be subclasses of :c:data:`Warning`; the default warning - category is :c:data:`RuntimeWarning`. The standard Python warning categories are - available as global variables whose names are ``PyExc_`` followed by the Python - exception name. These have the type :c:type:`PyObject\*`; they are all class - objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`, - :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`, - :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and - :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of - :c:data:`PyExc_Exception`; the other warning categories are subclasses of - :c:data:`PyExc_Warning`. + Warning categories must be subclasses of :c:data:`PyExc_Warning`; + :c:data:`PyExc_Warning` is a subclass of :c:data:`PyExc_Exception`; + the default warning category is :c:data:`PyExc_RuntimeWarning`. The standard + Python warning categories are available as global variables whose names are + enumerated at :ref:`standardwarningcategories`. For information about warning control, see the documentation for the :mod:`warnings` module and the :option:`-W` option in the command line @@ -525,84 +520,25 @@ All standard Python exceptions are available as global variables whose names are :c:type:`PyObject\*`; they are all class objects. For completeness, here are all the variables: -+-------------------------------------+----------------------------+----------+ -| C Name | Python Name | Notes | -+=====================================+============================+==========+ -| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_EOFError` | :exc:`EOFError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_IOError` | :exc:`IOError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_ImportError` | :exc:`ImportError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_IndexError` | :exc:`IndexError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_KeyError` | :exc:`KeyError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_NameError` | :exc:`NameError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_OSError` | :exc:`OSError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_SystemError` | :exc:`SystemError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_TypeError` | :exc:`TypeError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_ValueError` | :exc:`ValueError` | | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | -+-------------------------------------+----------------------------+----------+ -| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | -+-------------------------------------+----------------------------+----------+ - .. index:: single: PyExc_BaseException single: PyExc_Exception single: PyExc_StandardError single: PyExc_ArithmeticError - single: PyExc_LookupError single: PyExc_AssertionError single: PyExc_AttributeError - single: PyExc_EOFError + single: PyExc_BufferError single: PyExc_EnvironmentError + single: PyExc_EOFError single: PyExc_FloatingPointError - single: PyExc_IOError + single: PyExc_GeneratorExit single: PyExc_ImportError + single: PyExc_IndentationError single: PyExc_IndexError + single: PyExc_IOError single: PyExc_KeyError single: PyExc_KeyboardInterrupt + single: PyExc_LookupError single: PyExc_MemoryError single: PyExc_NameError single: PyExc_NotImplementedError @@ -610,14 +546,106 @@ the variables: single: PyExc_OverflowError single: PyExc_ReferenceError single: PyExc_RuntimeError + single: PyExc_StopIteration single: PyExc_SyntaxError single: PyExc_SystemError single: PyExc_SystemExit + single: PyExc_TabError single: PyExc_TypeError + single: PyExc_UnboundLocalError + single: PyExc_UnicodeDecodeError + single: PyExc_UnicodeEncodeError + single: PyExc_UnicodeError + single: PyExc_UnicodeTranslateError + single: PyExc_VMSError single: PyExc_ValueError single: PyExc_WindowsError single: PyExc_ZeroDivisionError ++-----------------------------------------+---------------------------------+----------+ +| C Name | Python Name | Notes | ++=========================================+=================================+==========+ +| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_BufferError` | :exc:`BufferError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_EOFError` | :exc:`EOFError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ImportError` | :exc:`ImportError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_IndexError` | :exc:`IndexError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_IOError` | :exc:`IOError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_KeyError` | :exc:`KeyError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_NameError` | :exc:`NameError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_OSError` | :exc:`OSError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_SystemError` | :exc:`SystemError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_TabError` | :exc:`TabError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_TypeError` | :exc:`TypeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ValueError` | :exc:`ValueError` | | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | ++-----------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | ++-----------------------------------------+---------------------------------+----------+ + Notes: (1) @@ -633,6 +661,60 @@ Notes: (4) .. versionadded:: 2.5 +(5) + Only defined on VMS; protect code that uses this by testing that the + preprocessor macro ``__VMS`` is defined. + +.. _standardwarningcategories: + +Standard Warning Categories +=========================== + +All standard Python warning categories are available as global variables whose +names are ``PyExc_`` followed by the Python exception name. These have the type +:c:type:`PyObject\*`; they are all class objects. For completeness, here are all +the variables: + +.. index:: + single: PyExc_Warning + single: PyExc_BytesWarning + single: PyExc_DeprecationWarning + single: PyExc_FutureWarning + single: PyExc_ImportWarning + single: PyExc_PendingDeprecationWarning + single: PyExc_RuntimeWarning + single: PyExc_SyntaxWarning + single: PyExc_UnicodeWarning + single: PyExc_UserWarning + ++------------------------------------------+---------------------------------+----------+ +| C Name | Python Name | Notes | ++==========================================+=================================+==========+ +| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | | ++------------------------------------------+---------------------------------+----------+ +| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | | ++------------------------------------------+---------------------------------+----------+ + +Notes: + +(1) + This is a base class for other standard warning categories. String Exceptions ================= @@ -640,4 +722,3 @@ String Exceptions .. versionchanged:: 2.6 All exceptions to be raised or caught must be derived from :exc:`BaseException`. Trying to raise a string exception now raises :exc:`TypeError`. - diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index 0de950a..08d5b94 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -66,3 +66,14 @@ Slice Objects :c:type:`int *` type for *start*, *stop*, *step*, and *slicelength*. This might require changes in your code for properly supporting 64-bit systems. + + +Ellipsis Object +--------------- + + +.. c:var:: PyObject *Py_Ellipsis + + The Python ``Ellipsis`` object. This object has no methods. It needs to be + treated just like any other object with respect to reference counts. Like + :c:data:`Py_None` it is a singleton object. diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index fdee5f9..782cec2 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -265,7 +265,7 @@ definition with the same method name. +==================+=============+===============================+ | :attr:`name` | char \* | name of the member | +------------------+-------------+-------------------------------+ - | :attr:`type` | int | the type of the member in the | + | :attr:`!type` | int | the type of the member in the | | | | C struct | +------------------+-------------+-------------------------------+ | :attr:`offset` | Py_ssize_t | the offset in bytes that the | @@ -280,7 +280,7 @@ definition with the same method name. | | | docstring | +------------------+-------------+-------------------------------+ - :attr:`type` can be one of many ``T_`` macros corresponding to various C + :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. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 9233278..2ebbd52 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -1377,23 +1377,23 @@ member in the :c:type:`PyTypeObject` structure should be *NULL*. Otherwise, the Structure used to hold the function pointers which define an implementation of the buffer protocol. - The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`getreadbufferproc`. + The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`readbufferproc`. If this slot is *NULL*, then the object does not support reading from the internal data. This is non-sensical, so implementors should fill this in, but callers should test that the slot contains a non-*NULL* value. The next slot is :attr:`bf_getwritebuffer` having type - :c:type:`getwritebufferproc`. This slot may be *NULL* if the object does not + :c:type:`writebufferproc`. This slot may be *NULL* if the object does not allow writing into its returned buffers. - The third slot is :attr:`bf_getsegcount`, with type :c:type:`getsegcountproc`. + The third slot is :attr:`bf_getsegcount`, with type :c:type:`segcountproc`. This slot must not be *NULL* and is used to inform the caller how many segments the object contains. Simple objects such as :c:type:`PyString_Type` and :c:type:`PyBuffer_Type` objects contain a single segment. .. index:: single: PyType_HasFeature() - The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`getcharbufferproc`. + The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`charbufferproc`. This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER` flag is present in the :c:member:`~PyTypeObject.tp_flags` field of the object's :c:type:`PyTypeObject`. Before using this slot, the caller should test whether it diff --git a/Doc/conf.py b/Doc/conf.py index 2c271e8..14bb641 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -82,11 +82,24 @@ html_split_index = True # Options for LaTeX output # ------------------------ +# Get LaTeX to handle Unicode correctly +latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''} + +# Additional stuff for the LaTeX preamble. +latex_elements['preamble'] = r''' +\authoraddress{ + \strong{Python Software Foundation}\\ + Email: \email{docs@python.org} +} +\let\Verbatim=\OriginalVerbatim +\let\endVerbatim=\endOriginalVerbatim +''' + # The paper size ('letter' or 'a4'). -latex_paper_size = 'a4' +latex_elements['papersize'] = 'a4' # The font size ('10pt', '11pt' or '12pt'). -latex_font_size = '10pt' +latex_elements['font_size'] = '10pt' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). @@ -119,30 +132,15 @@ latex_documents.extend(('howto/' + fn[:-4], 'howto-' + fn[:-4] + '.tex', for fn in os.listdir('howto') if fn.endswith('.rst') and fn != 'index.rst') -# Additional stuff for the LaTeX preamble. -latex_preamble = r''' -\authoraddress{ - \strong{Python Software Foundation}\\ - Email: \email{docs@python.org} -} -\let\Verbatim=\OriginalVerbatim -\let\endVerbatim=\endOriginalVerbatim -''' - # Documents to append as an appendix to all manuals. latex_appendices = ['glossary', 'about', 'license', 'copyright'] -# Get LaTeX to handle Unicode correctly -latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''} - - # Options for Epub output # ----------------------- epub_author = 'Python Documentation Authors' epub_publisher = 'Python Software Foundation' - # Options for the coverage checker # -------------------------------- diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index 6e275e5..5959e4f 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -79,27 +79,26 @@ Python integers:: Moving on, we come to the crunch --- the type object. :: static PyTypeObject noddy_NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /*ob_size*/ - "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_compare*/ - 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*/ + 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_compare */ + 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 */ }; @@ -111,23 +110,16 @@ it's common practice to not specify them explicitly unless you need them. This is so important that we're going to pick the top of it apart still further:: - PyObject_HEAD_INIT(NULL) + PyVarObject_HEAD_INIT(NULL, 0) This line is a bit of a wart; what we'd like to write is:: - PyObject_HEAD_INIT(&PyType_Type) + PyVarObject_HEAD_INIT(&PyType_Type, 0) as the type of a type object is "type", but this isn't strictly conforming C and some compilers complain. Fortunately, this member will be filled in for us by :c:func:`PyType_Ready`. :: - 0, /* ob_size */ - -The :attr:`ob_size` field of the header is not used; its presence in the type -structure is a historical artifact that is maintained for binary compatibility -with extension modules compiled for older versions of Python. Always set this -field to zero. :: - "noddy.Noddy", /* tp_name */ The name of our type. This will appear in the default textual representation of @@ -135,7 +127,7 @@ our objects and in some error messages, for example:: >>> "" + noddy.new_noddy() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: cannot add type "noddy.Noddy" to string Note that the name is a dotted name that includes both the module name and the @@ -171,7 +163,7 @@ for now. Skipping a number of type methods that we don't provide, we set the class flags to :const:`Py_TPFLAGS_DEFAULT`. :: - Py_TPFLAGS_DEFAULT, /*tp_flags*/ + Py_TPFLAGS_DEFAULT, /* tp_flags */ All types should include this constant in their flags. It enables all of the members defined by the current version of Python. @@ -244,7 +236,7 @@ doesn't do anything. It can't even be subclassed. Adding data and methods to the Basic example -------------------------------------------- -Let's expend the basic example to add some data and methods. Let's also make +Let's extend the basic example to add some data and methods. Let's also make the type usable as a base class. We'll create a new module, :mod:`noddy2` that adds these capabilities: @@ -284,7 +276,7 @@ allocation and deallocation. At a minimum, we need a deallocation method:: { Py_XDECREF(self->first); Py_XDECREF(self->last); - self->ob_type->tp_free((PyObject*)self); + Py_TYPE(self)->tp_free((PyObject*)self); } which is assigned to the :c:member:`~PyTypeObject.tp_dealloc` member:: @@ -497,7 +489,7 @@ concatenation of the first and last names. :: The method is implemented as a C function that takes a :class:`Noddy` (or :class:`Noddy` subclass) instance as the first argument. Methods always take an instance as the first argument. Methods often take positional and keyword -arguments as well, but in this cased we don't take any and don't need to accept +arguments as well, but in this case we don't take any and don't need to accept a positional argument tuple or keyword argument dictionary. This method is equivalent to the Python method:: @@ -806,7 +798,7 @@ decrementing of reference counts. With :c:func:`Py_CLEAR`, the Finally, we add the :const:`Py_TPFLAGS_HAVE_GC` flag to the class flags:: - Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /*tp_flags*/ + Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, /* tp_flags */ That's pretty much it. If we had written custom :c:member:`~PyTypeObject.tp_alloc` or :c:member:`~PyTypeObject.tp_free` slots, we'd need to modify them for cyclic-garbage collection. @@ -965,14 +957,15 @@ Finalization and De-allocation This function is called when the reference count of the instance of your type is reduced to zero and the Python interpreter wants to reclaim it. If your type -has memory to free or other clean-up to perform, put it here. The object itself -needs to be freed here as well. Here is an example of this function:: +has memory to free or other clean-up to perform, you can put it here. The +object itself needs to be freed here as well. Here is an example of this +function:: static void newdatatype_dealloc(newdatatypeobject * obj) { free(obj->obj_UnderlyingDatatypePtr); - obj->ob_type->tp_free(obj); + Py_TYPE(obj)->tp_free(obj); } .. index:: @@ -1015,7 +1008,7 @@ done. This can be done using the :c:func:`PyErr_Fetch` and Py_DECREF(self->my_callback); } - obj->ob_type->tp_free((PyObject*)self); + Py_TYPE(obj)->tp_free((PyObject*)self); } diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 2de378d..35cad55 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -159,7 +159,7 @@ How do I obtain a copy of the Python source? The latest Python source distribution is always available from python.org, at https://www.python.org/downloads/. The latest development sources can be obtained -via anonymous Mercurial access at https://hg.python.org/cpython. +at https://github.com/python/cpython/. The source distribution is a gzipped tar file containing the complete C source, Sphinx-formatted documentation, Python library modules, example programs, and @@ -222,8 +222,8 @@ releases are announced on the comp.lang.python and comp.lang.python.announce newsgroups and on the Python home page at https://www.python.org/; an RSS feed of news is available. -You can also access the development version of Python through Mercurial. See -https://docs.python.org/devguide/faq.html for details. +You can also access the development version of Python through Git. See +`The Python Developer's Guide `_ for details. How do I submit bug reports and patches for Python? diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst index 832c1e0..9228fdd 100644 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@ -70,15 +70,6 @@ Python bindings for `the FLTK toolkit `_, a simple yet powerful and mature cross-platform windowing system, are available from `the PyFLTK project `_. - -FOX ----- - -A wrapper for `the FOX toolkit `_ called `FXpy -`_ is available. FOX supports both Unix variants -and Windows. - - OpenGL ------ diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index 25c73b8..f8e23cf 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -295,7 +295,7 @@ this respect, and is easily configured to use spaces: Take :menuselection:`Tools size" to 4, and select the "Insert spaces" radio button. If you suspect mixed tabs and spaces are causing problems in leading whitespace, -run Python with the :option:`-t` switch or run ``Tools/Scripts/tabnanny.py`` to +run Python with the :option:`-t` switch or run the :mod:`tabnanny` module to check a directory tree in batch mode. diff --git a/Doc/howto/argparse.rst b/Doc/howto/argparse.rst index 02bfc70..63b0b28 100644 --- a/Doc/howto/argparse.rst +++ b/Doc/howto/argparse.rst @@ -223,7 +223,7 @@ before proceeding. Introducing Optional arguments ============================== -So far we, have been playing with positional arguments. Let us +So far we have been playing with positional arguments. Let us have a look on how to add optional ones:: import argparse diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst index 493f6ae..37ba6a8 100644 --- a/Doc/howto/descriptor.rst +++ b/Doc/howto/descriptor.rst @@ -258,10 +258,10 @@ to wrap access to the value attribute in a property data descriptor:: class Cell(object): . . . - def getvalue(self, obj): - "Recalculate cell before returning value" + def getvalue(self): + "Recalculate the cell before returning value" self.recalc() - return obj._value + return self._value value = property(getvalue) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index ee9a5f6..a06e29c 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -207,7 +207,7 @@ You can experiment with the iteration interface manually: 3 >>> it.next() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in StopIteration >>> @@ -477,7 +477,7 @@ Here's a sample usage of the ``generate_ints()`` generator: 2 >>> gen.next() Traceback (most recent call last): - File "stdin", line 1, in ? + File "stdin", line 1, in File "stdin", line 2, in generate_ints StopIteration @@ -581,7 +581,7 @@ And here's an example of changing the counter: 9 >>> print it.next() Traceback (most recent call last): - File "t.py", line 15, in ? + File "t.py", line 15, in print it.next() StopIteration diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index b7f0fa5..b9b5120 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -814,7 +814,7 @@ Implementing structured logging ------------------------------- Although most logging messages are intended for reading by humans, and thus not -readily machine-parseable, there might be cirumstances where you want to output +readily machine-parseable, there might be circumstances where you want to output messages in a structured format which *is* capable of being parsed by a program (without needing complex regular expressions to parse the log message). This is straightforward to achieve using the logging package. There are a number of @@ -1179,8 +1179,8 @@ Speaking logging messages ------------------------- There might be situations when it is desirable to have logging messages rendered -in an audible rather than a visible format. This is easy to do if you have text- -to-speech (TTS) functionality available in your system, even if it doesn't have +in an audible rather than a visible format. This is easy to do if you have +text-to-speech (TTS) functionality available in your system, even if it doesn't have a Python binding. Most TTS systems have a command line program you can run, and this can be invoked from a handler using :mod:`subprocess`. It's assumed here that TTS command line programs won't expect to interact with users or take a diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst index 59b283a..8562d23 100644 --- a/Doc/howto/pyporting.rst +++ b/Doc/howto/pyporting.rst @@ -17,7 +17,8 @@ Porting Python 2 Code to Python 3 please see :ref:`cporting-howto`. If you would like to read one core Python developer's take on why Python 3 - came into existence, you can read Nick Coghlan's `Python 3 Q & A`_. + came into existence, you can read Nick Coghlan's `Python 3 Q & A`_ or + Brett Cannon's `Why Python 3 exists`_. For help with porting, you can email the python-porting_ mailing list with questions. @@ -28,24 +29,21 @@ The Short Explanation To make your project be single-source Python 2/3 compatible, the basic steps are: -#. Update your code to drop support for Python 2.5 or older (supporting only - Python 2.7 is ideal) +#. Only worry about supporting Python 2.7 #. Make sure you have good test coverage (coverage.py_ can help; ``pip install coverage``) #. Learn the differences between Python 2 & 3 -#. Use Modernize_ or Futurize_ to update your code (``pip install modernize`` or - ``pip install future``, respectively) +#. Use Futurize_ (or Modernize_) to update your code (e.g. ``pip install future``) #. Use Pylint_ to help make sure you don't regress on your Python 3 support - (if only supporting Python 2.7/3.4 or newer; ``pip install pylint``) + (``pip install pylint``) #. Use caniusepython3_ to find out which of your dependencies are blocking your use of Python 3 (``pip install caniusepython3``) #. Once your dependencies are no longer blocking you, use continuous integration to make sure you stay compatible with Python 2 & 3 (tox_ can help test against multiple versions of Python; ``pip install tox``) - -If you are dropping support for Python 2 entirely, then after you learn the -differences between Python 2 & 3 you can run 2to3_ over your code and skip the -rest of the steps outlined above. +#. Consider using optional static type checking to make sure your type usage + works in both Python 2 & 3 (e.g. use mypy_ to check your typing under both + Python 2 & Python 3). Details @@ -55,7 +53,7 @@ A key point about supporting Python 2 & 3 simultaneously is that you can start **today**! Even if your dependencies are not supporting Python 3 yet that does not mean you can't modernize your code **now** to support Python 3. Most changes required to support Python 3 lead to cleaner code using newer practices even in -Python 2. +Python 2 code. Another key point is that modernizing your Python 2 code to also support Python 3 is largely automated for you. While you might have to make some API @@ -67,26 +65,28 @@ Keep those key points in mind while you read on about the details of porting your code to support Python 2 & 3 simultaneously. -Drop support for Python 2.5 and older (at least) ------------------------------------------------- +Drop support for Python 2.6 and older +------------------------------------- While you can make Python 2.5 work with Python 3, it is **much** easier if you -only have to work with Python 2.6 or newer (and easier still if you only have -to work with Python 2.7). If dropping Python 2.5 is not an option then the six_ -project can help you support Python 2.5 & 3 simultaneously +only have to work with Python 2.7. If dropping Python 2.5 is not an +option then the six_ project can help you support Python 2.5 & 3 simultaneously (``pip install six``). Do realize, though, that nearly all the projects listed in this HOWTO will not be available to you. -If you are able to only support Python 2.6 or newer, then the required changes +If you are able to skip Python 2.5 and older, then the required changes to your code should continue to look and feel like idiomatic Python code. At worst you will have to use a function instead of a method in some instances or have to import a function instead of using a built-in one, but otherwise the overall transformation should not feel foreign to you. -But please aim for Python 2.7. Bugfixes for that version of Python will continue -until 2020 while Python 2.6 is no longer supported. There are also some tools -mentioned in this HOWTO which do not support Python 2.6 (e.g., Pylint_), and -this will become more commonplace as time goes on. +But you should aim for only supporting Python 2.7. Python 2.6 is no longer +freely supported and thus is not receiving bugfixes. This means **you** will have +to work around any issues you come across with Python 2.6. There are also some +tools mentioned in this HOWTO which do not support Python 2.6 (e.g., Pylint_), +and this will become more commonplace as time goes on. It will simply be easier +for you if you only support the versions of Python that you have to support. + Make sure you specify the proper version support in your ``setup.py`` file -------------------------------------------------------------------------- @@ -98,6 +98,7 @@ Python 3 yet you should at least have also specify each major/minor version of Python that you do support, e.g. ``Programming Language :: Python :: 2.7``. + Have good test coverage ----------------------- @@ -106,9 +107,10 @@ to, you will want to make sure your test suite has good coverage. A good rule of thumb is that if you want to be confident enough in your test suite that any failures that appear after having tools rewrite your code are actual bugs in the tools and not in your code. If you want a number to aim for, try to get over 80% -coverage (and don't feel bad if you can't easily get past 90%). If you -don't already have a tool to measure test coverage then coverage.py_ is -recommended. +coverage (and don't feel bad if you find it hard to get better than 90% +coverage). If you don't already have a tool to measure test coverage then +coverage.py_ is recommended. + Learn the differences between Python 2 & 3 ------------------------------------------- @@ -127,13 +129,15 @@ Update your code Once you feel like you know what is different in Python 3 compared to Python 2, it's time to update your code! You have a choice between two tools in porting -your code automatically: Modernize_ and Futurize_. Which tool you choose will +your code automatically: Futurize_ and Modernize_. Which tool you choose will depend on how much like Python 3 you want your code to be. Futurize_ does its best to make Python 3 idioms and practices exist in Python 2, e.g. backporting the ``bytes`` type from Python 3 so that you have semantic parity between the major versions of Python. Modernize_, on the other hand, is more conservative and targets a Python 2/3 subset of -Python, relying on six_ to help provide compatibility. +Python, directly relying on six_ to help provide compatibility. As Python 3 is +the future, it might be best to consider Futurize to begin adjusting to any new +practices that Python 3 introduces which you are not accustomed to yet. Regardless of which tool you choose, they will update your code to run under Python 3 while staying compatible with the version of Python 2 you started with. @@ -153,6 +157,7 @@ the built-in ``open()`` function is off by default in Modernize). Luckily, though, there are only a couple of things to watch out for which can be considered large issues that may be hard to debug if not watched for. + Division ++++++++ @@ -169,8 +174,10 @@ things: division or continue using ``/`` and expect a float The reason that ``/`` isn't simply translated to ``//`` automatically is that if -an object defines its own ``__div__`` method but not ``__floordiv__`` then your -code would begin to fail. +an object defines a ``__truediv__`` method but not ``__floordiv__`` then your +code would begin to fail (e.g. a user-defined class that uses ``/`` to +signify some operation but not ``//`` for the same thing or at all). + Text versus binary data +++++++++++++++++++++++ @@ -188,7 +195,7 @@ To make the distinction between text and binary data clearer and more pronounced, Python 3 did what most languages created in the age of the internet have done and made text and binary data distinct types that cannot blindly be mixed together (Python predates widespread access to the internet). For any code -that only deals with text or only binary data, this separation doesn't pose an +that deals only with text or only binary data, this separation doesn't pose an issue. But for code that has to deal with both, it does mean you might have to now care about when you are using text compared to binary data, which is why this cannot be entirely automated. @@ -197,22 +204,21 @@ To start, you will need to decide which APIs take text and which take binary (it is **highly** recommended you don't design APIs that can take both due to the difficulty of keeping the code working; as stated earlier it is difficult to do well). In Python 2 this means making sure the APIs that take text can work -with ``unicode`` in Python 2 and those that work with binary data work with the -``bytes`` type from Python 3 and thus a subset of ``str`` in Python 2 (which the -``bytes`` type in Python 2 is an alias for). Usually the biggest issue is -realizing which methods exist for which types in Python 2 & 3 simultaneously +with ``unicode`` and those that work with binary data work with the +``bytes`` type from Python 3 (which is a subset of ``str`` in Python 2 and acts +as an alias for ``bytes`` type in Python 2). Usually the biggest issue is +realizing which methods exist on which types in Python 2 & 3 simultaneously (for text that's ``unicode`` in Python 2 and ``str`` in Python 3, for binary that's ``str``/``bytes`` in Python 2 and ``bytes`` in Python 3). The following table lists the **unique** methods of each data type across Python 2 & 3 (e.g., the ``decode()`` method is usable on the equivalent binary data type in -either Python 2 or 3, but it can't be used by the text data type consistently -between Python 2 and 3 because ``str`` in Python 3 doesn't have the method). +either Python 2 or 3, but it can't be used by the textual data type consistently +between Python 2 and 3 because ``str`` in Python 3 doesn't have the method). Do +note that as of Python 3.5 the ``__mod__`` method was added to the bytes type. ======================== ===================== **Text data** **Binary data** ------------------------ --------------------- -__mod__ (``%`` operator) ------------------------- --------------------- \ decode ------------------------ --------------------- encode @@ -232,10 +238,11 @@ This allows your code to work with only text internally and thus eliminates having to keep track of what type of data you are working with. The next issue is making sure you know whether the string literals in your code -represent text or binary data. At minimum you should add a ``b`` prefix to any -literal that presents binary data. For text you should either use the -``from __future__ import unicode_literals`` statement or add a ``u`` prefix to -the text literal. +represent text or binary data. You should add a ``b`` prefix to any +literal that presents binary data. For text you should add a ``u`` prefix to +the text literal. (there is a :mod:`__future__` import to force all unspecified +literals to be Unicode, but usage has shown it isn't as effective as adding a +``b`` or ``u`` prefix to all literals explicitly) As part of this dichotomy you also need to be careful about opening files. Unless you have been working on Windows, there is a chance you have not always @@ -243,11 +250,13 @@ bothered to add the ``b`` mode when opening a binary file (e.g., ``rb`` for binary reading). Under Python 3, binary files and text files are clearly distinct and mutually incompatible; see the :mod:`io` module for details. Therefore, you **must** make a decision of whether a file will be used for -binary access (allowing binary data to be read and/or written) or text access +binary access (allowing binary data to be read and/or written) or textual access (allowing text data to be read and/or written). You should also use :func:`io.open` for opening files instead of the built-in :func:`open` function as the :mod:`io` module is consistent from Python 2 to 3 while the built-in :func:`open` function -is not (in Python 3 it's actually :func:`io.open`). +is not (in Python 3 it's actually :func:`io.open`). Do not bother with the +outdated practice of using :func:`codecs.open` as that's only necessary for +keeping compatibility with Python 2.5. The constructors of both ``str`` and ``bytes`` have different semantics for the same arguments between Python 2 & 3. Passing an integer to ``bytes`` in Python 2 @@ -274,13 +283,58 @@ To summarize: #. Make sure that your code that works with text also works with ``unicode`` and code for binary data works with ``bytes`` in Python 2 (see the table above for what methods you cannot use for each type) -#. Mark all binary literals with a ``b`` prefix, use a ``u`` prefix or - :mod:`__future__` import statement for text literals +#. Mark all binary literals with a ``b`` prefix, textual literals with a ``u`` + prefix #. Decode binary data to text as soon as possible, encode text as binary data as late as possible #. Open files using :func:`io.open` and make sure to specify the ``b`` mode when appropriate -#. Be careful when indexing binary data +#. Be careful when indexing into binary data + + +Use feature detection instead of version detection +++++++++++++++++++++++++++++++++++++++++++++++++++ + +Inevitably you will have code that has to choose what to do based on what +version of Python is running. The best way to do this is with feature detection +of whether the version of Python you're running under supports what you need. +If for some reason that doesn't work then you should make the version check be +against Python 2 and not Python 3. To help explain this, let's look at an +example. + +Let's pretend that you need access to a feature of importlib_ that +is available in Python's standard library since Python 3.3 and available for +Python 2 through importlib2_ on PyPI. You might be tempted to write code to +access e.g. the ``importlib.abc`` module by doing the following:: + + import sys + + if sys.version_info[0] == 3: + from importlib import abc + else: + from importlib2 import abc + +The problem with this code is what happens when Python 4 comes out? It would +be better to treat Python 2 as the exceptional case instead of Python 3 and +assume that future Python versions will be more compatible with Python 3 than +Python 2:: + + import sys + + if sys.version_info[0] > 2: + from importlib import abc + else: + from importlib2 import abc + +The best solution, though, is to do no version detection at all and instead rely +on feature detection. That avoids any potential issues of getting the version +detection wrong and helps keep you future-compatible:: + + try: + from importlib import abc + except ImportError: + from importlib2 import abc + Prevent compatibility regressions --------------------------------- @@ -296,14 +350,12 @@ at least the following block of code at the top of it:: from __future__ import absolute_import from __future__ import division from __future__ import print_function - from __future__ import unicode_literals You can also run Python 2 with the ``-3`` flag to be warned about various compatibility issues your code triggers during execution. If you turn warnings into errors with ``-Werror`` then you can make sure that you don't accidentally miss a warning. - You can also use the Pylint_ project and its ``--py3k`` flag to lint your code to receive warnings when your code begins to deviate from Python 3 compatibility. This also prevents you from having to run Modernize_ or Futurize_ @@ -320,22 +372,23 @@ care about whether your dependencies have also been ported. The caniusepython3_ project was created to help you determine which projects -- directly or indirectly -- are blocking you from supporting Python 3. There is both a command-line tool as well as a web interface at -https://caniusepython3.com . +https://caniusepython3.com. The project also provides code which you can integrate into your test suite so that you will have a failing test when you no longer have dependencies blocking you from using Python 3. This allows you to avoid having to manually check your dependencies and to be notified quickly when you can start running on Python 3. + Update your ``setup.py`` file to denote Python 3 compatibility -------------------------------------------------------------- Once your code works under Python 3, you should update the classifiers in your ``setup.py`` to contain ``Programming Language :: Python :: 3`` and to not -specify sole Python 2 support. This will tell -anyone using your code that you support Python 2 **and** 3. Ideally you will -also want to add classifiers for each major/minor version of Python you now -support. +specify sole Python 2 support. This will tell anyone using your code that you +support Python 2 **and** 3. Ideally you will also want to add classifiers for +each major/minor version of Python you now support. + Use continuous integration to stay compatible --------------------------------------------- @@ -347,10 +400,12 @@ tox with your continuous integration system so that you never accidentally break Python 2 or 3 support. You may also want to use the ``-bb`` flag with the Python 3 interpreter to -trigger an exception when you are comparing bytes to strings. Usually it's -simply ``False``, but if you made a mistake in your separation of text/binary -data handling you may be accidentally comparing text and binary data. This flag -will raise an exception when that occurs to help track down such cases. +trigger an exception when you are comparing bytes to strings or bytes to an int +(the latter is available starting in Python 3.5). By default type-differing +comparisons simply return ``False``, but if you made a mistake in your +separation of text/binary data handling or indexing on bytes you wouldn't easily +find the mistake. This flag will raise an exception when these kinds of +comparisons occur, making the mistake much easier to track down. And that's mostly it! At this point your code base is compatible with both Python 2 and 3 simultaneously. Your testing will also be set up so that you @@ -358,20 +413,17 @@ don't accidentally break Python 2 or 3 compatibility regardless of which version you typically run your tests under while developing. -Dropping Python 2 support completely -==================================== - -If you are able to fully drop support for Python 2, then the steps required -to transition to Python 3 simplify greatly. - -#. Update your code to only support Python 2.7 -#. Make sure you have good test coverage (coverage.py_ can help) -#. Learn the differences between Python 2 & 3 -#. Use 2to3_ to rewrite your code to run only under Python 3 +Consider using optional static type checking +-------------------------------------------- -After this your code will be fully Python 3 compliant but in a way that is not -supported by Python 2. You should also update the classifiers in your -``setup.py`` to contain ``Programming Language :: Python :: 3 :: Only``. +Another way to help port your code is to use a static type checker like +mypy_ or pytype_ on your code. These tools can be used to analyze your code as +if it's being run under Python 2, then you can run the tool a second time as if +your code is running under Python 3. By running a static type checker twice like +this you can discover if you're e.g. misusing binary data type in one version +of Python compared to another. If you add optional type hints to your code you +can also explicitly state whether your APIs use textual or binary data, helping +to make sure everything functions as expected in both versions of Python. .. _2to3: https://docs.python.org/3/library/2to3.html @@ -379,14 +431,22 @@ supported by Python 2. You should also update the classifiers in your .. _cheat sheet: http://python-future.org/compatible_idioms.html .. _coverage.py: https://pypi.python.org/pypi/coverage .. _Futurize: http://python-future.org/automatic_conversion.html +.. _importlib: https://docs.python.org/3/library/importlib.html#module-importlib +.. _importlib2: https://pypi.python.org/pypi/importlib2 .. _Modernize: https://python-modernize.readthedocs.org/en/latest/ +.. _mypy: http://mypy-lang.org/ .. _Porting to Python 3: http://python3porting.com/ .. _Pylint: https://pypi.python.org/pypi/pylint + .. _Python 3 Q & A: https://ncoghlan-devs-python-notes.readthedocs.org/en/latest/python3/questions_and_answers.html +.. _pytype: https://github.com/google/pytype .. _python-future: http://python-future.org/ .. _python-porting: https://mail.python.org/mailman/listinfo/python-porting .. _six: https://pypi.python.org/pypi/six .. _tox: https://pypi.python.org/pypi/tox .. _trove classifier: https://pypi.python.org/pypi?%3Aaction=list_classifiers + .. _"What's New": https://docs.python.org/3/whatsnew/index.html + +.. _Why Python 3 exists: http://www.snarky.ca/why-python-3-exists diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst index bf7ebff..6724039 100644 --- a/Doc/howto/unicode.rst +++ b/Doc/howto/unicode.rst @@ -43,9 +43,9 @@ hold values ranging from 0 to 255. ASCII codes only went up to 127, so some machines assigned values between 128 and 255 to accented characters. Different machines had different codes, however, which led to problems exchanging files. Eventually various commonly used sets of values for the 128--255 range emerged. -Some were true standards, defined by the International Standards Organization, -and some were **de facto** conventions that were invented by one company or -another and managed to catch on. +Some were true standards, defined by the International Organization for +Standardization, and some were *de facto* conventions that were invented by one +company or another and managed to catch on. 255 characters aren't very many. For example, you can't fit both the accented characters used in Western Europe and the Cyrillic alphabet used for Russian diff --git a/Doc/howto/urllib2.rst b/Doc/howto/urllib2.rst index f6cba75..d697c21 100644 --- a/Doc/howto/urllib2.rst +++ b/Doc/howto/urllib2.rst @@ -34,8 +34,8 @@ handling common situations - like basic authentication, cookies, proxies and so on. These are provided by objects called handlers and openers. urllib2 supports fetching URLs for many "URL schemes" (identified by the string -before the ":" in URL - for example "ftp" is the URL scheme of -"ftp://python.org/") using their associated network protocols (e.g. FTP, HTTP). +before the ``":"`` in URL - for example ``"ftp"`` is the URL scheme of +``"ftp://python.org/"``) using their associated network protocols (e.g. FTP, HTTP). This tutorial focuses on the most common case, HTTP. For straightforward situations *urlopen* is very easy to use. But as soon as you @@ -498,10 +498,10 @@ than the URL you pass to .add_password() will also match. :: ``top_level_url`` is in fact *either* a full URL (including the 'http:' scheme component and the hostname and optionally the port number) -e.g. "http://example.com/" *or* an "authority" (i.e. the hostname, -optionally including the port number) e.g. "example.com" or "example.com:8080" +e.g. ``"http://example.com/"`` *or* an "authority" (i.e. the hostname, +optionally including the port number) e.g. ``"example.com"`` or ``"example.com:8080"`` (the latter example includes a port number). The authority, if present, must -NOT contain the "userinfo" component - for example "joe:password@example.com" is +NOT contain the "userinfo" component - for example ``"joe:password@example.com"`` is not correct. diff --git a/Doc/includes/noddy.c b/Doc/includes/noddy.c index ec2d669..9d80bbe 100644 --- a/Doc/includes/noddy.c +++ b/Doc/includes/noddy.c @@ -6,27 +6,26 @@ typedef struct { } noddy_NoddyObject; static PyTypeObject noddy_NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /*ob_size*/ - "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_compare*/ - 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*/ + 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_compare */ + 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 */ }; diff --git a/Doc/includes/noddy2.c b/Doc/includes/noddy2.c index 2caf985..94b92be 100644 --- a/Doc/includes/noddy2.c +++ b/Doc/includes/noddy2.c @@ -13,7 +13,7 @@ Noddy_dealloc(Noddy* self) { Py_XDECREF(self->first); Py_XDECREF(self->last); - self->ob_type->tp_free((PyObject*)self); + Py_TYPE(self)->tp_free((PyObject*)self); } static PyObject * @@ -24,18 +24,16 @@ Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds) self = (Noddy *)type->tp_alloc(type, 0); if (self != NULL) { self->first = PyString_FromString(""); - if (self->first == NULL) - { + if (self->first == NULL) { Py_DECREF(self); return NULL; - } - + } + self->last = PyString_FromString(""); - if (self->last == NULL) - { + if (self->last == NULL) { Py_DECREF(self); return NULL; - } + } self->number = 0; } @@ -50,10 +48,10 @@ Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) static char *kwlist[] = {"first", "last", "number", NULL}; - if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, - &first, &last, + if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, + &first, &last, &self->number)) - return -1; + return -1; if (first) { tmp = self->first; @@ -111,7 +109,7 @@ Noddy_name(Noddy* self) result = PyString_Format(format, args); Py_DECREF(args); - + return result; } @@ -123,34 +121,34 @@ static PyMethodDef Noddy_methods[] = { }; static PyTypeObject NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /*ob_size*/ - "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_compare*/ - 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*/ + 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_compare */ + 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 */ + 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 */ @@ -172,7 +170,7 @@ static PyMethodDef module_methods[] = { #define PyMODINIT_FUNC void #endif PyMODINIT_FUNC -initnoddy2(void) +initnoddy2(void) { PyObject* m; @@ -183,7 +181,7 @@ initnoddy2(void) "Example module that creates an extension type."); if (m == NULL) - return; + return; Py_INCREF(&NoddyType); PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType); diff --git a/Doc/includes/noddy3.c b/Doc/includes/noddy3.c index 60260ad..43ec42b 100644 --- a/Doc/includes/noddy3.c +++ b/Doc/includes/noddy3.c @@ -13,7 +13,7 @@ Noddy_dealloc(Noddy* self) { Py_XDECREF(self->first); Py_XDECREF(self->last); - self->ob_type->tp_free((PyObject*)self); + Py_TYPE(self)->tp_free((PyObject*)self); } static PyObject * @@ -24,18 +24,16 @@ Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds) self = (Noddy *)type->tp_alloc(type, 0); if (self != NULL) { self->first = PyString_FromString(""); - if (self->first == NULL) - { + if (self->first == NULL) { Py_DECREF(self); return NULL; - } - + } + self->last = PyString_FromString(""); - if (self->last == NULL) - { + if (self->last == NULL) { Py_DECREF(self); return NULL; - } + } self->number = 0; } @@ -50,10 +48,10 @@ Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) static char *kwlist[] = {"first", "last", "number", NULL}; - if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist, - &first, &last, + if (! PyArg_ParseTupleAndKeywords(args, kwds, "|SSi", kwlist, + &first, &last, &self->number)) - return -1; + return -1; if (first) { tmp = self->first; @@ -88,22 +86,22 @@ Noddy_getfirst(Noddy *self, void *closure) 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 (! PyString_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; + if (value == NULL) { + PyErr_SetString(PyExc_TypeError, "Cannot delete the first attribute"); + return -1; + } + + if (! PyString_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 * @@ -116,30 +114,30 @@ Noddy_getlast(Noddy *self, void *closure) 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 (! PyString_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; + if (value == NULL) { + PyErr_SetString(PyExc_TypeError, "Cannot delete the last attribute"); + return -1; + } + + if (! PyString_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", + {"first", (getter)Noddy_getfirst, (setter)Noddy_setfirst, "first name", NULL}, - {"last", + {"last", (getter)Noddy_getlast, (setter)Noddy_setlast, "last name", NULL}, @@ -164,7 +162,7 @@ Noddy_name(Noddy* self) result = PyString_Format(format, args); Py_DECREF(args); - + return result; } @@ -176,34 +174,34 @@ static PyMethodDef Noddy_methods[] = { }; static PyTypeObject NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /*ob_size*/ - "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_compare*/ - 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*/ + 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_compare */ + 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 */ + 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 */ @@ -225,7 +223,7 @@ static PyMethodDef module_methods[] = { #define PyMODINIT_FUNC void #endif PyMODINIT_FUNC -initnoddy3(void) +initnoddy3(void) { PyObject* m; @@ -236,7 +234,7 @@ initnoddy3(void) "Example module that creates an extension type."); if (m == NULL) - return; + return; Py_INCREF(&NoddyType); PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType); diff --git a/Doc/includes/noddy4.c b/Doc/includes/noddy4.c index 878e086..9feb71a 100644 --- a/Doc/includes/noddy4.c +++ b/Doc/includes/noddy4.c @@ -27,7 +27,7 @@ Noddy_traverse(Noddy *self, visitproc visit, void *arg) return 0; } -static int +static int Noddy_clear(Noddy *self) { PyObject *tmp; @@ -47,7 +47,7 @@ static void Noddy_dealloc(Noddy* self) { Noddy_clear(self); - self->ob_type->tp_free((PyObject*)self); + Py_TYPE(self)->tp_free((PyObject*)self); } static PyObject * @@ -58,18 +58,16 @@ Noddy_new(PyTypeObject *type, PyObject *args, PyObject *kwds) self = (Noddy *)type->tp_alloc(type, 0); if (self != NULL) { self->first = PyString_FromString(""); - if (self->first == NULL) - { + if (self->first == NULL) { Py_DECREF(self); return NULL; - } - + } + self->last = PyString_FromString(""); - if (self->last == NULL) - { + if (self->last == NULL) { Py_DECREF(self); return NULL; - } + } self->number = 0; } @@ -84,10 +82,10 @@ Noddy_init(Noddy *self, PyObject *args, PyObject *kwds) static char *kwlist[] = {"first", "last", "number", NULL}; - if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, - &first, &last, + if (! PyArg_ParseTupleAndKeywords(args, kwds, "|OOi", kwlist, + &first, &last, &self->number)) - return -1; + return -1; if (first) { tmp = self->first; @@ -145,7 +143,7 @@ Noddy_name(Noddy* self) result = PyString_Format(format, args); Py_DECREF(args); - + return result; } @@ -157,34 +155,35 @@ static PyMethodDef Noddy_methods[] = { }; static PyTypeObject NoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /*ob_size*/ - "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_compare*/ - 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*/ + 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_compare */ + 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 */ + 0, /* tp_richcompare */ + 0, /* tp_weaklistoffset */ + 0, /* tp_iter */ + 0, /* tp_iternext */ Noddy_methods, /* tp_methods */ Noddy_members, /* tp_members */ 0, /* tp_getset */ @@ -206,7 +205,7 @@ static PyMethodDef module_methods[] = { #define PyMODINIT_FUNC void #endif PyMODINIT_FUNC -initnoddy4(void) +initnoddy4(void) { PyObject* m; @@ -217,7 +216,7 @@ initnoddy4(void) "Example module that creates an extension type."); if (m == NULL) - return; + return; Py_INCREF(&NoddyType); PyModule_AddObject(m, "Noddy", (PyObject *)&NoddyType); diff --git a/Doc/includes/setup.py b/Doc/includes/setup.py index b853d23..a38a39d 100644 --- a/Doc/includes/setup.py +++ b/Doc/includes/setup.py @@ -5,4 +5,5 @@ setup(name="noddy", version="1.0", 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 index 07a4177..4cb39db 100644 --- a/Doc/includes/shoddy.c +++ b/Doc/includes/shoddy.c @@ -31,8 +31,7 @@ Shoddy_init(Shoddy *self, PyObject *args, PyObject *kwds) static PyTypeObject ShoddyType = { - PyObject_HEAD_INIT(NULL) - 0, /* ob_size */ + PyVarObject_HEAD_INIT(NULL, 0) "shoddy.Shoddy", /* tp_name */ sizeof(Shoddy), /* tp_basicsize */ 0, /* tp_itemsize */ @@ -52,7 +51,7 @@ static PyTypeObject ShoddyType = { 0, /* tp_setattro */ 0, /* tp_as_buffer */ Py_TPFLAGS_DEFAULT | - Py_TPFLAGS_BASETYPE, /* tp_flags */ + Py_TPFLAGS_BASETYPE, /* tp_flags */ 0, /* tp_doc */ 0, /* tp_traverse */ 0, /* tp_clear */ diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst index e5b3165..cbbb882 100644 --- a/Doc/installing/index.rst +++ b/Doc/installing/index.rst @@ -193,6 +193,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 0632f3c..b782875 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 diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst index 3d9042c..a87cb9c 100644 --- a/Doc/library/_winreg.rst +++ b/Doc/library/_winreg.rst @@ -1,5 +1,5 @@ -:mod:`_winreg` -- Windows registry access -========================================= +:mod:`_winreg` --- Windows registry access +========================================== .. module:: _winreg :platform: Windows diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 4ce6835..1ea1f3f 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -173,7 +173,7 @@ ArgumentParser objects * conflict_handler_ - The strategy for resolving conflicting optionals (usually unnecessary) - * add_help_ - Add a -h/--help option to the parser (default: ``True``) + * add_help_ - Add a ``-h/--help`` option to the parser (default: ``True``) The following sections describe how each of these are used. @@ -204,7 +204,7 @@ The help for this program will display ``myprogram.py`` as the program name -h, --help show this help message and exit --foo FOO foo help $ cd .. - $ python subdir\myprogram.py --help + $ python subdir/myprogram.py --help usage: myprogram.py [-h] [--foo FOO] optional arguments: diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst index 5eb7c4b..38f616a 100644 --- a/Doc/library/binascii.rst +++ b/Doc/library/binascii.rst @@ -101,8 +101,10 @@ The :mod:`binascii` module defines the following functions: .. function:: crc_hqx(data, crc) - Compute the binhex4 crc value of *data*, starting with an initial *crc* and - returning the result. + Compute a 16-bit CRC value of *data*, starting with an initial *crc* and + returning the result. This uses the CRC-CCITT polynomial + *x*:sup:`16` + *x*:sup:`12` + *x*:sup:`5` + 1, often represented as + 0x1021. This CRC is used in the binhex4 format. .. function:: crc32(data[, crc]) diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index 3c8c05f..25e5e22 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -200,6 +200,7 @@ counts, but the output will exclude results with counts of zero or less. adapted for Python 2.5 and an early `Bag recipe `_ for Python 2.4. + * `Bag class `_ in Smalltalk. * Wikipedia entry for `Multisets `_. @@ -703,7 +704,7 @@ field names, the method and attribute names start with an underscore. .. versionchanged:: 2.7 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/configparser.rst b/Doc/library/configparser.rst index b83397c..5c40f5c 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -35,8 +35,8 @@ easily. .. seealso:: Module :mod:`shlex` - Support for a creating Unix shell-like mini-languages which can be used - as an alternate format for application configuration files. + Support for creating Unix shell-like mini-languages which can be used as + an alternate format for application configuration files. Module :mod:`json` The json module implements a subset of JavaScript syntax which can also diff --git a/Doc/library/copy.rst b/Doc/library/copy.rst index a5378e5..67cf65a 100644 --- a/Doc/library/copy.rst +++ b/Doc/library/copy.rst @@ -43,8 +43,8 @@ copy operations: * Recursive objects (compound objects that, directly or indirectly, contain a reference to themselves) may cause a recursive loop. -* Because deep copy copies *everything* it may copy too much, e.g., - even administrative data structures that should be shared even between copies. +* Because deep copy copies everything it may copy too much, such as data + which is intended to be shared between copies. The :func:`deepcopy` function avoids these problems by: diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 052cdee..df9ccbf 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -87,7 +87,7 @@ Functions are accessed as attributes of dll objects:: <_FuncPtr object at 0x...> >>> print windll.kernel32.MyOwnFunction # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "ctypes.py", line 239, in __getattr__ func = _StdcallFuncPtr(name, self) AttributeError: function 'MyOwnFunction' not found @@ -126,7 +126,7 @@ functions can be accessed by indexing the dll object with the ordinal number:: <_FuncPtr object at 0x...> >>> cdll.kernel32[0] # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "ctypes.py", line 310, in __getitem__ func = _StdcallFuncPtr(name, self) AttributeError: function ordinal 0 not found @@ -159,11 +159,11 @@ although an error is raised the function *has* been called:: >>> windll.kernel32.GetModuleHandleA() # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: Procedure probably called with not enough arguments (4 bytes missing) >>> windll.kernel32.GetModuleHandleA(0, 0) # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: Procedure probably called with too many arguments (4 bytes in excess) >>> @@ -172,13 +172,13 @@ The same exception is raised when you call an ``stdcall`` function with the >>> cdll.kernel32.GetModuleHandleA(None) # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: Procedure probably called with not enough arguments (4 bytes missing) >>> >>> windll.msvcrt.printf("spam") # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: Procedure probably called with too many arguments (4 bytes in excess) >>> @@ -191,7 +191,7 @@ argument values:: >>> windll.kernel32.GetModuleHandleA(32) # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in WindowsError: exception: access violation reading 0x00000020 >>> @@ -354,7 +354,7 @@ from within *IDLE* or *PythonWin*:: 19 >>> printf("%f bottles of beer\n", 42.5) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ArgumentError: argument 2: exceptions.TypeError: Don't know how to convert parameter 2 >>> @@ -417,7 +417,7 @@ prototype for a C function), and tries to convert the arguments to valid types:: >>> printf("%d %d %d", 1, 2, 3) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ArgumentError: argument 2: exceptions.TypeError: wrong type >>> printf("%s %d %f\n", "X", 2, 3) X 2 3.000000 @@ -467,7 +467,7 @@ single character Python string into a C char:: 'def' >>> strchr("abcdef", "def") Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ArgumentError: argument 2: exceptions.TypeError: one character string expected >>> print strchr("abcdef", "x") None @@ -493,7 +493,7 @@ useful to check for error return values and automatically raise an exception:: 486539264 >>> GetModuleHandle("something silly") # doctest: +WINDOWS Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "", line 3, in ValidHandle WindowsError: [Errno 126] The specified module could not be found. >>> @@ -564,7 +564,7 @@ Here is a simple example of a POINT structure, which contains two integers named 0 5 >>> POINT(1, 2, 3) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: too many initializers >>> @@ -767,7 +767,7 @@ a new type:: >>> PI(42) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: expected c_long instead of int >>> PI(c_int(42)) @@ -843,7 +843,7 @@ but not instances of other types:: >>> bar.values = (c_byte * 4)() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance >>> @@ -894,7 +894,7 @@ work:: ... ("next", POINTER(cell))] ... Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "", line 2, in cell NameError: name 'cell' is not defined >>> diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index c70afe3..7b56ad7 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -1234,27 +1234,63 @@ The :mod:`curses` module defines the following data members: A string representing the current version of the module. Also available as :const:`__version__`. -Several constants are available to specify character cell attributes: +Some constants are available to specify character cell attributes. +The exact constants available are system dependent. +------------------+-------------------------------+ | Attribute | Meaning | +==================+===============================+ -| ``A_ALTCHARSET`` | Alternate character set mode. | +| ``A_ALTCHARSET`` | Alternate character set mode | +------------------+-------------------------------+ -| ``A_BLINK`` | Blink mode. | +| ``A_BLINK`` | Blink mode | +------------------+-------------------------------+ -| ``A_BOLD`` | Bold mode. | +| ``A_BOLD`` | Bold mode | +------------------+-------------------------------+ -| ``A_DIM`` | Dim mode. | +| ``A_DIM`` | Dim mode | +------------------+-------------------------------+ -| ``A_NORMAL`` | Normal attribute. | +| ``A_INVIS`` | Invisible or blank mode | ++------------------+-------------------------------+ +| ``A_NORMAL`` | Normal attribute | ++------------------+-------------------------------+ +| ``A_PROTECT`` | Protected mode | +------------------+-------------------------------+ | ``A_REVERSE`` | Reverse background and | -| | foreground colors. | +| | foreground colors | ++------------------+-------------------------------+ +| ``A_STANDOUT`` | Standout mode | ++------------------+-------------------------------+ +| ``A_UNDERLINE`` | Underline mode | ++------------------+-------------------------------+ +| ``A_HORIZONTAL`` | Horizontal highlight | ++------------------+-------------------------------+ +| ``A_LEFT`` | Left highlight | ++------------------+-------------------------------+ +| ``A_LOW`` | Low highlight | ++------------------+-------------------------------+ +| ``A_RIGHT`` | Right highlight | ++------------------+-------------------------------+ +| ``A_TOP`` | Top highlight | ++------------------+-------------------------------+ +| ``A_VERTICAL`` | Vertical highlight | ++------------------+-------------------------------+ +| ``A_CHARTEXT`` | Bit-mask to extract a | +| | character | ++------------------+-------------------------------+ + +Several constants are available to extract corresponding attributes returned +by some methods. + ++------------------+-------------------------------+ +| Bit-mask | Meaning | ++==================+===============================+ +| ``A_ATTRIBUTES`` | Bit-mask to extract | +| | attributes | +------------------+-------------------------------+ -| ``A_STANDOUT`` | Standout mode. | +| ``A_CHARTEXT`` | Bit-mask to extract a | +| | character | +------------------+-------------------------------+ -| ``A_UNDERLINE`` | Underline mode. | +| ``A_COLOR`` | Bit-mask to extract | +| | color-pair field information | +------------------+-------------------------------+ Keys are referred to by integer constants with names starting with ``KEY_``. @@ -1406,7 +1442,7 @@ The exact keycaps available are system dependent. +-------------------+--------------------------------------------+ | ``KEY_SEOL`` | Shifted Clear line | +-------------------+--------------------------------------------+ -| ``KEY_SEXIT`` | Shifted Dxit | +| ``KEY_SEXIT`` | Shifted Exit | +-------------------+--------------------------------------------+ | ``KEY_SFIND`` | Shifted Find | +-------------------+--------------------------------------------+ diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 5c4ff38..b8d86e3 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1323,7 +1323,7 @@ Instance methods: Example: - >>> from datetime import time, tzinfo + >>> from datetime import time, tzinfo, timedelta >>> class GMT1(tzinfo): ... def utcoffset(self, dt): ... return timedelta(hours=1) diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 4506805..cf67b23 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -425,7 +425,7 @@ Simple example:: >>> [1, 2, 3].remove(42) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: list.remove(x): x not in list That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): @@ -449,7 +449,7 @@ multi-line detail:: >>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: multi line detail @@ -530,8 +530,8 @@ Option Flags A number of option flags control various aspects of doctest's behavior. Symbolic names for the flags are supplied as module constants, which can be -or'ed together and passed to various functions. The names can also be used in -:ref:`doctest directives `. +:ref:`bitwise ORed ` together and passed to various functions. +The names can also be used in :ref:`doctest directives `. The first group of options define test semantics, controlling aspects of how doctest decides whether actual output matches an example's expected output: @@ -607,7 +607,7 @@ doctest decides whether actual output matches an example's expected output: >>> (1, 2)[3] = 'moo' Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: object doesn't support item assignment passes under Python 2.3 and later Python versions with the flag specified, @@ -1161,10 +1161,11 @@ reporting flags specific to :mod:`unittest` support, via this function: the option flags specified for the test case when the :class:`DocTestCase` instance was constructed. If no reporting flags were specified (which is the typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are - or'ed into the option flags, and the option flags so augmented are passed to the - :class:`DocTestRunner` instance created to run the doctest. If any reporting - flags were specified when the :class:`DocTestCase` instance was constructed, - :mod:`doctest`'s :mod:`unittest` reporting flags are ignored. + :ref:`bitwise ORed ` into the option flags, and the option flags + so augmented are passed to the :class:`DocTestRunner` instance created to + run the doctest. If any reporting flags were specified when the + :class:`DocTestCase` instance was constructed, :mod:`doctest`'s + :mod:`unittest` reporting flags are ignored. The value of the :mod:`unittest` reporting flags in effect before the function was called is returned by the function. diff --git a/Doc/library/email.mime.rst b/Doc/library/email.mime.rst index dcf7b59..5cbb4dd 100644 --- a/Doc/library/email.mime.rst +++ b/Doc/library/email.mime.rst @@ -210,7 +210,7 @@ Here are the classes: Unless the ``_charset`` parameter is explicitly set to ``None``, the MIMEText object created will have both a :mailheader:`Content-Type` header - with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Endcoding` + with a ``charset`` parameter, and a :mailheader:`Content-Transfer-Encoding` header. This means that a subsequent ``set_payload`` call will not result in an encoded payload, even if a charset is passed in the ``set_payload`` command. You can "reset" this behavior by deleting the diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst index 3dfec2d..42bbf74 100644 --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -44,9 +44,8 @@ patterns. .. function:: fnmatch(filename, pattern) Test whether the *filename* string matches the *pattern* string, returning - :const:`True` or :const:`False`. If the operating system is case-insensitive, - then both parameters will be normalized to all lower- or upper-case before - the comparison is performed. :func:`fnmatchcase` can be used to perform a + :const:`True` or :const:`False`. Both parameters are case-normalized + using :func:`os.path.normcase`. :func:`fnmatchcase` can be used to perform a case-sensitive comparison, regardless of whether that's standard for the operating system. @@ -64,7 +63,8 @@ patterns. .. function:: fnmatchcase(filename, pattern) Test whether *filename* matches *pattern*, returning :const:`True` or - :const:`False`; the comparison is case-sensitive. + :const:`False`; the comparison is case-sensitive and does not apply + :func:`os.path.normcase`. .. function:: filter(names, pattern) diff --git a/Doc/library/fpectl.rst b/Doc/library/fpectl.rst index 8ca671b..d48b820 100644 --- a/Doc/library/fpectl.rst +++ b/Doc/library/fpectl.rst @@ -88,7 +88,7 @@ The following example demonstrates how to start up and test operation of the >>> import math >>> math.exp(1000) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in FloatingPointError: in math_1 diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index b155daf..4fe4074 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -243,17 +243,17 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. the trailing CRLF stripped. The default *callback* prints the line to ``sys.stdout``. -.. method:: FTP.set_pasv(boolean) +.. method:: FTP.set_pasv(val) - Enable "passive" mode if *boolean* is true, other disable passive mode. (In + Enable "passive" mode if *val* is true, otherwise disable passive mode. (In Python 2.0 and before, passive mode was off by default; in Python 2.1 and later, it is on by default.) -.. method:: FTP.storbinary(command, file[, blocksize, callback, rest]) +.. method:: FTP.storbinary(command, fp[, blocksize, callback, rest]) Store a file in binary transfer mode. *command* should be an appropriate - ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is + ``STOR`` command: ``"STOR filename"``. *fp* is an open file object which is read until EOF using its :meth:`read` method in blocks of size *blocksize* to provide the data to be stored. The *blocksize* argument defaults to 8192. *callback* is an optional single parameter callable that is called @@ -269,11 +269,11 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. .. versionchanged:: 2.7 *rest* parameter added. -.. method:: FTP.storlines(command, file[, callback]) +.. method:: FTP.storlines(command, fp[, callback]) Store a file in ASCII transfer mode. *command* should be an appropriate ``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the - open file object *file* using its :meth:`~file.readline` method to provide + open file object *fp* using its :meth:`~file.readline` method to provide the data to be stored. *callback* is an optional single parameter callable that is called on each line after it is sent. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index f294b6e..4386e60 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -16,7 +16,7 @@ available. They are listed here in alphabetical order. :func:`basestring` :func:`execfile` :func:`issubclass` :func:`print` :func:`super` :func:`bin` :func:`file` :func:`iter` :func:`property` :func:`tuple` :func:`bool` :func:`filter` :func:`len` :func:`range` :func:`type` -:func:`bytearray` :func:`float` :func:`list` :func:`raw_input` :func:`unichr` +:func:`bytearray` :func:`float` |func-list|_ :func:`raw_input` :func:`unichr` :func:`callable` :func:`format` :func:`locals` :func:`reduce` :func:`unicode` :func:`chr` |func-frozenset|_ :func:`long` :func:`reload` :func:`vars` :func:`classmethod` :func:`getattr` :func:`map` |func-repr|_ :func:`xrange` @@ -38,6 +38,7 @@ section. .. |func-dict| replace:: ``dict()`` .. |func-frozenset| replace:: ``frozenset()`` +.. |func-list| replace:: ``list()`` .. |func-memoryview| replace:: ``memoryview()`` .. |func-repr| replace:: ``repr()`` .. |func-set| replace:: ``set()`` @@ -617,7 +618,7 @@ section. '0x1L' If x is not a Python :class:`int` or :class:`long` object, it has to - define an __index__() method that returns an integer. + define a __hex__() method that returns a string. See also :func:`int` for converting a hexadecimal string to an integer using a base of 16. @@ -740,7 +741,9 @@ section. (such as a dictionary, set, or frozen set). +.. _func-list: .. class:: list([iterable]) + :noindex: Return 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 diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst index 0a9a6dc..8bc8947 100644 --- a/Doc/library/httplib.rst +++ b/Doc/library/httplib.rst @@ -473,7 +473,7 @@ HTTPConnection Objects .. method:: HTTPConnection.set_tunnel(host,port=None, headers=None) Set the host and the port for HTTP Connect Tunnelling. Normally used when - it is required to do HTTPS Conection through a proxy server. + it is required to do HTTPS Connection through a proxy server. The headers argument should be a mapping of extra HTTP headers to send with the CONNECT request. diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 34f9a89..a461e51 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -240,7 +240,7 @@ Go to File/Line single: stack viewer Debugger (toggle) - When actived, code entered in the Shell or run from an Editor will run + When activated, code entered in the Shell or run from an Editor will run under the debugger. In the Editor, breakpoints can be set with the context menu. This feature is still incomplete and somewhat experimental. @@ -368,7 +368,7 @@ the :kbd:`Command` key on Mac OSX. * :kbd:`C-l` center window around the insertion point - * :kbd:`C-b` go backwards one character without deleting (usually you can + * :kbd:`C-b` go backward one character without deleting (usually you can also use the cursor key for this) * :kbd:`C-f` go forward one character without deleting (usually you can @@ -390,7 +390,7 @@ After a block-opening statement, the next line is indented by 4 spaces (in the Python Shell window by one tab). After certain keywords (break, return etc.) the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python -Shell window one tab), number depends on Indent width. Currently tabs +Shell window one tab), number depends on Indent width. Currently, tabs are restricted to four spaces due to Tcl/Tk limitations. See also the indent/dedent region commands in the edit menu. @@ -414,7 +414,7 @@ If there is only one possible completion for the characters entered, a :kbd:`C-space` will open a completions window. In an empty string, this will contain the files in the current directory. On a blank line, it will contain the built-in and user-defined functions and -classes in the current name spaces, plus any modules imported. If some +classes in the current namespaces, plus any modules imported. If some characters have been entered, the ACW will attempt to be more specific. If a string of characters is typed, the ACW selection will jump to the @@ -553,7 +553,7 @@ IDLE-console differences As much as possible, the result of executing Python code with IDLE is the same as executing the same code in a console window. However, the different -interface and operation occasionally affects visible results. For instance, +interface and operation occasionally affect visible results. For instance, ``sys.modules`` starts with more entries. IDLE also replaces ``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` with @@ -579,7 +579,7 @@ If firewall software complains anyway, you can ignore it. If the attempt to make the socket connection fails, Idle will notify you. Such failures are sometimes transient, but if persistent, the problem -may be either a firewall blocking the connecton or misconfiguration of +may be either a firewall blocking the connection or misconfiguration of a particular system. Until the problem is fixed, one can run Idle with the -n command line switch. @@ -615,14 +615,14 @@ Setting preferences The font preferences, highlighting, keys, and general preferences can be changed via Configure IDLE on the Option menu. Keys can be user defined; -IDLE ships with four built in key sets. In addition a user can create a +IDLE ships with four built-in key sets. In addition, a user can create a custom key set in the Configure IDLE dialog under the keys tab. Extensions ^^^^^^^^^^ -IDLE contains an extension facility. Peferences for extensions can be +IDLE contains an extension facility. Preferences for extensions can be changed with Configure Extensions. See the beginning of config-extensions.def in the idlelib directory for further information. The default extensions are currently: diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index c4307b5..f93e945 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1,5 +1,5 @@ -:mod:`importlib` -- Convenience wrappers for :func:`__import__` -=============================================================== +:mod:`importlib` --- Convenience wrappers for :func:`__import__` +================================================================ .. module:: importlib :synopsis: Convenience wrappers for __import__ diff --git a/Doc/library/json.rst b/Doc/library/json.rst index c4d5ee6..87dc054 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -89,7 +89,7 @@ Extending :class:`JSONEncoder`:: ... # Let the base class default method raise the TypeError ... return json.JSONEncoder.default(self, obj) ... - >>> dumps(2 + 1j, cls=ComplexEncoder) + >>> json.dumps(2 + 1j, cls=ComplexEncoder) '[2.0, 1.0]' >>> ComplexEncoder().encode(2 + 1j) '[2.0, 1.0]' diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index 23333ed..b331fbb 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -93,8 +93,8 @@ in :mod:`logging` itself) and defining handlers which are declared either in :param disable_existing_loggers: If specified as ``False``, loggers which exist when this call is made are left enabled. The default is ``True`` because this - enables old behaviour in a backward- - compatible way. This behaviour is to + enables old behaviour in a + backward-compatible way. This behaviour is to disable any existing loggers unless they or their ancestors are explicitly named in the logging configuration. diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst index 43c4ea0..c6e157c 100644 --- a/Doc/library/mimetypes.rst +++ b/Doc/library/mimetypes.rst @@ -186,78 +186,78 @@ than one MIME-type database; it provides an interface similar to the one of the loaded "on top" of the default database. -.. attribute:: MimeTypes.suffix_map + .. attribute:: MimeTypes.suffix_map - Dictionary mapping suffixes to suffixes. This is used to allow recognition of - encoded files for which the encoding and the type are indicated by the same - extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz` - to allow the encoding and type to be recognized separately. This is initially a - copy of the global :data:`suffix_map` defined in the module. + Dictionary mapping suffixes to suffixes. This is used to allow recognition of + encoded files for which the encoding and the type are indicated by the same + extension. For example, the :file:`.tgz` extension is mapped to :file:`.tar.gz` + to allow the encoding and type to be recognized separately. This is initially a + copy of the global :data:`suffix_map` defined in the module. -.. attribute:: MimeTypes.encodings_map + .. attribute:: MimeTypes.encodings_map - Dictionary mapping filename extensions to encoding types. This is initially a - copy of the global :data:`encodings_map` defined in the module. + Dictionary mapping filename extensions to encoding types. This is initially a + copy of the global :data:`encodings_map` defined in the module. -.. attribute:: MimeTypes.types_map + .. attribute:: MimeTypes.types_map - Tuple containing two dictionaries, mapping filename extensions to MIME types: - the first dictionary is for the non-standards types and the second one is for - the standard types. They are initialized by :data:`common_types` and - :data:`types_map`. + Tuple containing two dictionaries, mapping filename extensions to MIME types: + the first dictionary is for the non-standards types and the second one is for + the standard types. They are initialized by :data:`common_types` and + :data:`types_map`. -.. attribute:: MimeTypes.types_map_inv + .. attribute:: MimeTypes.types_map_inv - Tuple containing two dictionaries, mapping MIME types to a list of filename - extensions: the first dictionary is for the non-standards types and the - second one is for the standard types. They are initialized by - :data:`common_types` and :data:`types_map`. + Tuple containing two dictionaries, mapping MIME types to a list of filename + extensions: the first dictionary is for the non-standards types and the + second one is for the standard types. They are initialized by + :data:`common_types` and :data:`types_map`. -.. method:: MimeTypes.guess_extension(type, strict=True) + .. method:: MimeTypes.guess_extension(type, strict=True) - Similar to the :func:`guess_extension` function, using the tables stored as part - of the object. + Similar to the :func:`guess_extension` function, using the tables stored as part + of the object. -.. method:: MimeTypes.guess_type(url, strict=True) + .. method:: MimeTypes.guess_type(url, strict=True) - Similar to the :func:`guess_type` function, using the tables stored as part of - the object. + Similar to the :func:`guess_type` function, using the tables stored as part of + the object. -.. method:: MimeTypes.guess_all_extensions(type, strict=True) + .. method:: MimeTypes.guess_all_extensions(type, strict=True) - Similar to the :func:`guess_all_extensions` function, using the tables stored - as part of the object. + Similar to the :func:`guess_all_extensions` function, using the tables stored + as part of the object. -.. method:: MimeTypes.read(filename, strict=True) + .. method:: MimeTypes.read(filename, strict=True) - Load MIME information from a file named *filename*. This uses :meth:`readfp` to - parse the file. + Load MIME information from a file named *filename*. This uses :meth:`readfp` to + parse the file. - If *strict* is ``True``, information will be added to list of standard types, - else to the list of non-standard types. + If *strict* is ``True``, information will be added to list of standard types, + else to the list of non-standard types. -.. method:: MimeTypes.readfp(fp, strict=True) + .. method:: MimeTypes.readfp(fp, strict=True) - Load MIME type information from an open file *fp*. The file must have the format of - the standard :file:`mime.types` files. + Load MIME type information from an open file *fp*. The file must have the format of + the standard :file:`mime.types` files. - If *strict* is ``True``, information will be added to the list of standard - types, else to the list of non-standard types. + If *strict* is ``True``, information will be added to the list of standard + types, else to the list of non-standard types. -.. method:: MimeTypes.read_windows_registry(strict=True) + .. method:: MimeTypes.read_windows_registry(strict=True) - Load MIME type information from the Windows registry. Availability: Windows. + Load MIME type information from the Windows registry. Availability: Windows. - If *strict* is ``True``, information will be added to the list of standard - types, else to the list of non-standard types. + If *strict* is ``True``, information will be added to the list of standard + types, else to the list of non-standard types. - .. versionadded:: 2.7 + .. versionadded:: 2.7 diff --git a/Doc/library/msvcrt.rst b/Doc/library/msvcrt.rst index 87b8166..5e6d523 100644 --- a/Doc/library/msvcrt.rst +++ b/Doc/library/msvcrt.rst @@ -1,6 +1,6 @@ -:mod:`msvcrt` -- Useful routines from the MS VC++ runtime -========================================================= +:mod:`msvcrt` --- Useful routines from the MS VC++ runtime +========================================================== .. module:: msvcrt :platform: Windows diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index b393ad1..97a7b53 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -822,7 +822,7 @@ Connection objects are usually created using :func:`Pipe` -- see also .. method:: recv() Return an object sent from the other end of the connection using - :meth:`send`. Blocks until there its something to receive. Raises + :meth:`send`. Blocks until there is something to receive. Raises :exc:`EOFError` if there is nothing left to receive and the other end was closed. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 9caebf1..5bfa351 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -329,7 +329,7 @@ process and user. .. function:: setpgrp() - Call the system call :c:func:`setpgrp` or :c:func:`setpgrp(0, 0)` depending on + 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. diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst index 9177f95..33d7750 100644 --- a/Doc/library/pdb.rst +++ b/Doc/library/pdb.rst @@ -70,7 +70,7 @@ The typical usage to inspect a crashed program is:: >>> import mymodule >>> mymodule.test() Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in File "./mymodule.py", line 4, in test test2() File "./mymodule.py", line 3, in test2 diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 41be2c4..67f27de 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -418,10 +418,11 @@ Pickling and unpickling normal class instances When a pickled class instance is unpickled, its :meth:`__init__` method is normally *not* invoked. If it is desirable that the :meth:`__init__` method be called on unpickling, an old-style class can define a method - :meth:`__getinitargs__`, which should return a *tuple* containing the + :meth:`__getinitargs__`, which should return a *tuple* of positional arguments to be passed to the class constructor (:meth:`__init__` for - example). The :meth:`__getinitargs__` method is called at pickle time; the - tuple it returns is incorporated in the pickle for the instance. + example). Keyword arguments are not supported. The :meth:`__getinitargs__` + method is called at pickle time; the tuple it returns is incorporated in the + pickle for the instance. .. method:: object.__getnewargs__() diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 28b6f08..9f64095 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -33,8 +33,8 @@ Cross Platform returned as strings. Values that cannot be determined are returned as given by the parameter presets. - If bits is given as ``''``, the :c:func:`sizeof(pointer)` (or - :c:func:`sizeof(long)` on Python version < 1.5.2) is used as indicator for the + If bits is given as ``''``, the ``sizeof(pointer)`` (or + ``sizeof(long)`` on Python version < 1.5.2) is used as indicator for the supported pointer size. The function relies on the system's :file:`file` command to do the actual work. diff --git a/Doc/library/pyexpat.rst b/Doc/library/pyexpat.rst index ffa042b..9ac5572 100644 --- a/Doc/library/pyexpat.rst +++ b/Doc/library/pyexpat.rst @@ -911,7 +911,7 @@ The ``errors`` object has the following attributes: .. rubric:: Footnotes -.. [#] The encoding string included in XML output should conform to the +.. [1] The encoding string included in XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml. diff --git a/Doc/library/random.rst b/Doc/library/random.rst index 2a3c3af..852fe7c 100644 --- a/Doc/library/random.rst +++ b/Doc/library/random.rst @@ -71,17 +71,17 @@ from sources provided by the operating system. Bookkeeping functions: -.. function:: seed([x]) +.. function:: seed(a=None) - Initialize the basic random number generator. Optional argument *x* can be any - :term:`hashable` object. If *x* is omitted or ``None``, current system time is used; - current system time is also used to initialize the generator when the module is - first imported. If randomness sources are provided by the operating system, - they are used instead of the system time (see the :func:`os.urandom` function - for details on availability). + Initialize internal state of the random number generator. - If a :term:`hashable` object is given, deterministic results are only assured - when :envvar:`PYTHONHASHSEED` is disabled. + ``None`` or no argument seeds from current time or from an operating + system specific randomness source if available (see the :func:`os.urandom` + function for details on availability). + + If *a* is not ``None`` or an :class:`int` or a :class:`long`, then + ``hash(a)`` is used instead. Note that the hash values for some types + are nondeterministic when :envvar:`PYTHONHASHSEED` is enabled. .. versionchanged:: 2.4 formerly, operating system resources were not used. diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 7b76d0c..d0798b7 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -33,6 +33,12 @@ module-level functions and :class:`RegexObject` methods. The functions are shortcuts that don't require you to compile a regex object first, but miss some fine-tuning parameters. +.. seealso:: + + The third-party `regex `_ module, + which has an API compatible with the standard library :mod:`re` module, + but offers additional functionality and a more thorough Unicode support. + .. _re-syntax: @@ -480,7 +486,9 @@ form. IGNORECASE Perform case-insensitive matching; expressions like ``[A-Z]`` will match - lowercase letters, too. This is not affected by the current locale. + lowercase letters, too. This is not affected by the current locale. To + get this effect on non-ASCII Unicode characters such as ``ü`` and ``Ü``, + add the :const:`UNICODE` flag. .. data:: L @@ -511,8 +519,9 @@ form. .. data:: U UNICODE - Make ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S`` dependent - on the Unicode character properties database. + Make the ``\w``, ``\W``, ``\b``, ``\B``, ``\d``, ``\D``, ``\s`` and ``\S`` + sequences dependent on the Unicode character properties database. Also + enables non-ASCII matching for :const:`IGNORECASE`. .. versionadded:: 2.0 @@ -689,11 +698,22 @@ form. Added the optional flags argument. -.. function:: escape(string) +.. function:: escape(pattern) + + Escape all the characters in *pattern* except ASCII letters and numbers. + This is useful if you want to match an arbitrary literal string that may + have regular expression metacharacters in it. For example:: + + >>> print re.escape('python.exe') + python\.exe + + >>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:" + >>> print '[%s]+' % re.escape(legal_chars) + [abcdefghijklmnopqrstuvwxyz0123456789\!\#\$\%\&\'\*\+\-\.\^\_\`\|\~\:]+ - Return *string* with all non-alphanumerics backslashed; this is useful if you - want to match an arbitrary literal string that may have regular expression - metacharacters in it. + >>> operators = ['+', '-', '*', '/', '**'] + >>> print '|'.join(map(re.escape, sorted(operators, reverse=True))) + \/|\-|\+|\*\*|\* .. function:: purge() diff --git a/Doc/library/sgmllib.rst b/Doc/library/sgmllib.rst index 1fc650c..ffd0102 100644 --- a/Doc/library/sgmllib.rst +++ b/Doc/library/sgmllib.rst @@ -166,7 +166,7 @@ A single exception is defined as well: passing it to :meth:`convert_entityref`. If a translation is returned, it calls the method :meth:`handle_data` with the translation; otherwise, it calls the method ``unknown_entityref(ref)``. The default :attr:`entitydefs` defines - translations for ``&``, ``&apos``, ``>``, ``<``, and ``"``. + translations for ``&``, ``'``, ``>``, ``<``, and ``"``. .. versionchanged:: 2.5 Use :meth:`convert_entityref` instead of hard-coding the conversion. diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 527cbd0..6bd8f05 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -267,7 +267,9 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. *base_name* is the name of the file to create, including the path, minus any format-specific extension. *format* is the archive format: one of - "zip", "tar", "bztar" or "gztar". + "zip" (if the :mod:`zlib` module or external ``zip`` executable is + available), "tar", "gztar" (if the :mod:`zlib` module is available), or + "bztar" (if the :mod:`bz2` module is available). *root_dir* is a directory that will be the root directory of the archive; ie. we typically chdir into *root_dir* before creating the @@ -295,10 +297,11 @@ provided. They rely on the :mod:`zipfile` and :mod:`tarfile` modules. By default :mod:`shutil` provides these formats: - - *gztar*: gzip'ed tar-file - - *bztar*: bzip2'ed tar-file - - *tar*: uncompressed tar file - - *zip*: ZIP file + - *zip*: ZIP file (if the :mod:`zlib` module or external ``zip`` + executable is available). + - *tar*: uncompressed tar file. + - *gztar*: gzip'ed tar-file (if the :mod:`zlib` module is available). + - *bztar*: bzip2'ed tar-file (if the :mod:`bz2` module is available). You can register new formats or provide your own archiver for any existing formats, by using :func:`register_archive_format`. diff --git a/Doc/library/signal.rst b/Doc/library/signal.rst index fe7983b..3b02a39 100644 --- a/Doc/library/signal.rst +++ b/Doc/library/signal.rst @@ -197,8 +197,10 @@ The :mod:`signal` module defines the following functions: written to the fd. This can be used by a library to wakeup a poll or select call, allowing the signal to be fully processed. - The old wakeup fd is returned. *fd* must be non-blocking. It is up to the - library to remove any bytes before calling poll or select again. + The old wakeup fd is returned (or -1 if file descriptor wakeup was not + enabled). If *fd* is -1, file descriptor wakeup is disabled. + If not -1, *fd* must be non-blocking. It is up to the library to remove + any bytes from *fd* before calling poll or select again. When threads are enabled, this function can only be called from the main thread; attempting to call it from other threads will cause a :exc:`ValueError` diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 8849d0f..183c17b 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -1124,6 +1124,10 @@ to speed up repeated connections from the same clients. does not contain certificates from *capath* unless a certificate was requested and loaded by a SSL connection. + .. note:: + Certificates in a capath directory aren't loaded unless they have + been used at least once. + .. method:: SSLContext.set_default_verify_paths() Load a set of default "certification authority" (CA) certificates from @@ -1158,8 +1162,9 @@ to speed up repeated connections from the same clients. This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is False. - OpenSSL 1.1.0+ will abort the handshake and raise :exc:`SSLError` when - both sides support ALPN but cannot agree on a protocol. + OpenSSL 1.1.0 to 1.1.0e will abort the handshake and raise :exc:`SSLError` + when both sides support ALPN but cannot agree on a protocol. 1.1.0f+ + behaves like 1.0.2, :meth:`SSLSocket.selected_alpn_protocol` returns None. .. versionadded:: 2.7.10 @@ -1287,16 +1292,6 @@ to speed up repeated connections from the same clients. >>> stats['hits'], stats['misses'] (0, 0) -.. method:: SSLContext.get_ca_certs(binary_form=False) - - Returns a list of dicts with information of loaded CA certs. If the - optional argument is true, returns a DER-encoded copy of the CA - certificate. - - .. note:: - Certificates in a capath directory aren't loaded unless they have - been used at least once. - .. attribute:: SSLContext.check_hostname Wether to match the peer cert's hostname with :func:`match_hostname` in diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 9f5255a..bc7411c 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -113,11 +113,11 @@ Notes: (1) This is a short-circuit operator, so it only evaluates the second - argument if the first one is :const:`False`. + 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 :const:`True`. + argument if the first one is true. (3) ``not`` has a lower priority than non-Boolean operators, so ``not a == b`` is @@ -423,10 +423,12 @@ Bitwise Operations on Integer Types pair: bitwise; operations pair: shifting; operations pair: masking; operations + operator: | operator: ^ operator: & operator: << operator: >> + operator: ~ Bitwise operations only make sense for integers. Negative numbers are treated as their 2's complement value (this assumes a sufficiently large number of bits @@ -819,7 +821,7 @@ Notes: :ref:`faq-multidimensional-list`. (3) - If *i* or *j* is negative, the index is relative to the end of the string: + 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``. @@ -834,8 +836,10 @@ Notes: 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*). If *i* or *j* is greater than - ``len(s)``, use ``len(s)``. If *i* or *j* are omitted or ``None``, they become + *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``. @@ -1066,9 +1070,10 @@ string functions based on regular expressions. .. method:: str.join(iterable) - Return a string which is the concatenation of the strings in the - :term:`iterable` *iterable*. The separator between elements is the string - providing this method. + 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]) @@ -1551,9 +1556,7 @@ Notes: (2) The alternate form causes a leading ``'0x'`` or ``'0X'`` (depending on whether - the ``'x'`` or ``'X'`` format was used) to be inserted between left-hand padding - and the formatting of the number if the leading character of the result is not - already a zero. + 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 @@ -2003,9 +2006,7 @@ The constructors for both classes work the same: 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, the *elem* set is temporarily mutated during the search and then - restored. During the search, the *elem* set should not be read or mutated - since it does not have a meaningful value. + frozenset, a temporary one is created from *elem*. .. seealso:: diff --git a/Doc/library/sunau.rst b/Doc/library/sunau.rst index 5d57d4b..5bf4803 100644 --- a/Doc/library/sunau.rst +++ b/Doc/library/sunau.rst @@ -117,7 +117,7 @@ AU_read objects, as returned by :func:`.open` above, have the following methods: .. method:: AU_read.getnchannels() - Returns number of audio channels (1 for mone, 2 for stereo). + Returns number of audio channels (1 for mono, 2 for stereo). .. method:: AU_read.getsampwidth() diff --git a/Doc/library/tabnanny.rst b/Doc/library/tabnanny.rst index f447f12..f241cef 100644 --- a/Doc/library/tabnanny.rst +++ b/Doc/library/tabnanny.rst @@ -47,14 +47,14 @@ described below. .. exception:: NannyNag - Raised by :func:`tokeneater` if detecting an ambiguous indent. Captured and + Raised by :func:`process_tokens` if detecting an ambiguous indent. Captured and handled in :func:`check`. -.. function:: tokeneater(type, token, start, end, line) +.. function:: process_tokens(tokens) - This function is used by :func:`check` as a callback parameter to the function - :func:`tokenize.tokenize`. + This function is used by :func:`check` to process tokens generated by the + :mod:`tokenize` module. .. XXX document errprint, format_witnesses, Whitespace, check_equal, indents, reset_globals diff --git a/Doc/library/test.rst b/Doc/library/test.rst index be5a9e9..eef5d16 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -15,8 +15,8 @@ The :mod:`test` package contains all regression tests for Python as well as the -modules :mod:`test.test_support` and :mod:`test.regrtest`. -:mod:`test.test_support` is used to enhance your tests while +modules :mod:`test.support` and :mod:`test.regrtest`. +:mod:`test.support` is used to enhance your tests while :mod:`test.regrtest` drives the testing suite. Each module in the :mod:`test` package whose name starts with ``test_`` is a @@ -54,7 +54,7 @@ stated. A basic boilerplate is often used:: import unittest - from test import test_support + from test import support class MyTestCase1(unittest.TestCase): @@ -82,10 +82,10 @@ A basic boilerplate is often used:: ... more test classes ... def test_main(): - test_support.run_unittest(MyTestCase1, - MyTestCase2, - ... list other tests ... - ) + support.run_unittest(MyTestCase1, + MyTestCase2, + ... list other tests ... + ) if __name__ == '__main__': test_main() @@ -185,19 +185,24 @@ top-level directory where Python was built. On Windows, executing :program:`rt.bat` from your :file:`PCBuild` directory will run all regression tests. +.. versionchanged:: 2.7.14 + The :mod:`test` package can be run as a script: :program:`python -m test`. + This works the same as running the :mod:`test.regrtest` module. -:mod:`test.test_support` --- Utility functions for tests -======================================================== -.. module:: test.test_support +:mod:`test.support` --- Utility functions for tests +=================================================== + +.. module:: test.support :synopsis: Support for Python regression tests. .. note:: The :mod:`test.test_support` module has been renamed to :mod:`test.support` - in Python 3.x. + in Python 3.x and 2.7.14. The name ``test.test_support`` has been retained + as an alias in 2.7. -The :mod:`test.test_support` module provides support for Python's regression +The :mod:`test.support` module provides support for Python's regression tests. This module defines the following exceptions: @@ -216,7 +221,7 @@ This module defines the following exceptions: network connection) is not available. Raised by the :func:`requires` function. -The :mod:`test.test_support` module defines the following constants: +The :mod:`test.support` module defines the following constants: .. data:: verbose @@ -241,7 +246,7 @@ The :mod:`test.test_support` module defines the following constants: Set to a name that is safe to use as the name of a temporary file. Any temporary file that is created should be closed and unlinked (removed). -The :mod:`test.test_support` module defines the following functions: +The :mod:`test.support` module defines the following functions: .. function:: forget(module_name) @@ -284,7 +289,7 @@ The :mod:`test.test_support` module defines the following functions: following :func:`test_main` function:: def test_main(): - test_support.run_unittest(__name__) + support.run_unittest(__name__) This will run all tests defined in the named module. @@ -433,7 +438,7 @@ The :mod:`test.test_support` module defines the following functions: .. versionadded:: 2.7 -The :mod:`test.test_support` module defines the following classes: +The :mod:`test.support` module defines the following classes: .. class:: TransientResource(exc[, **kwargs]) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index b4de643..b2a9253 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -464,8 +464,13 @@ The module defines the following functions and data items: .. function:: tzset() - Resets the time conversion rules used by the library routines. The environment - variable :envvar:`TZ` specifies how this is done. + Reset the time conversion rules used by the library routines. The environment + variable :envvar:`TZ` specifies how this is done. It will also set the variables + ``tzname`` (from the :envvar:`TZ` environment variable), ``timezone`` (non-DST + seconds West of UTC), ``altzone`` (DST seconds west of UTC) and ``daylight`` + (to 0 if this timezone does not have any daylight saving time rules, or to + nonzero if there is a time, past, present or future when daylight saving time + applies). .. versionadded:: 2.3 diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 7c78235..5e61141 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -67,7 +67,7 @@ The module defines the following functions: This function prints a stack trace from its invocation point. The optional *f* argument can be used to specify an alternate stack frame to start. The - optional limit* and *file* arguments have the same meaning as for + optional *limit* and *file* arguments have the same meaning as for :func:`print_exception`. diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index ca4f37e..1c8a967 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -2219,7 +2219,7 @@ The demoscripts are: | wikipedia | a pattern from the wikipedia | :func:`clone`, | | | article on turtle graphics | :func:`undo` | +----------------+------------------------------+-----------------------+ -| yingyang | another elementary example | :func:`circle` | +| yinyang | another elementary example | :func:`circle` | +----------------+------------------------------+-----------------------+ Have fun! diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst index a3a7c96..d7c48c4 100644 --- a/Doc/library/unicodedata.rst +++ b/Doc/library/unicodedata.rst @@ -161,7 +161,7 @@ Examples: 9 >>> unicodedata.decimal(u'a') Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in ValueError: not a decimal >>> unicodedata.category(u'A') # 'L'etter, 'u'ppercase 'Lu' diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index b0eaae6..15765f5 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -1138,7 +1138,7 @@ Test cases Test that the multiline string *first* is equal to the string *second*. When not equal a diff of the two strings highlighting the differences will be included in the error message. This method is used by default - when comparing strings with :meth:`assertEqual`. + when comparing Unicode strings with :meth:`assertEqual`. .. versionadded:: 2.7 @@ -1352,7 +1352,7 @@ Grouping tests .. class:: TestSuite(tests=()) - This class represents an aggregation of individual tests cases and test suites. + This class represents an aggregation of individual test cases and test suites. The class presents the interface needed by the test runner to allow it to be run as any other test case. Running a :class:`TestSuite` instance is the same as iterating over the suite, running each test individually. @@ -1437,13 +1437,13 @@ Loading and running tests .. method:: loadTestsFromTestCase(testCaseClass) - Return a suite of all tests cases contained in the :class:`TestCase`\ -derived + Return a suite of all test cases contained in the :class:`TestCase`\ -derived :class:`testCaseClass`. .. method:: loadTestsFromModule(module) - Return a suite of all tests cases contained in the given module. This + Return a suite of all test cases contained in the given module. This method searches *module* for classes derived from :class:`TestCase` and creates an instance of the class for each test method defined for the class. @@ -1466,7 +1466,7 @@ Loading and running tests .. method:: loadTestsFromName(name, module=None) - Return a suite of all tests cases given a string specifier. + Return a suite of all test cases given a string specifier. The specifier *name* is a "dotted name" that may resolve either to a module, a test case class, a test method within a test case class, a diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index 69ef8f7..2a5ea71 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -26,11 +26,16 @@ reading, and no seek operations are available. .. seealso:: - The `Requests package `_ + The `Requests package `_ is recommended for a higher-level HTTP client interface. -.. warning:: When opening HTTPS URLs, it does not attempt to validate the - server certificate. Use at your own risk! +.. versionchanged:: 2.7.9 + + For HTTPS URIs, :mod:`urllib` performs all the neccessary certificate and hostname checks by default. + +.. warning:: + + For Python versions earlier than 2.7.9, urllib does not attempt to validate the server certificates of HTTPS URIs. Use at your own risk! High-level interface @@ -142,7 +147,7 @@ High-level interface :envvar:`no_proxy` environment variable. .. versionchanged:: 2.7.9 - The *context* parameter was added. + The *context* parameter was added. All the neccessary certificate and hostname checks are done by default. .. deprecated:: 2.6 The :func:`urlopen` function has been removed in Python 3 in favor @@ -295,15 +300,15 @@ Utility functions If both lowercase and uppercase environment variables exist (and disagree), lowercase is preferred. - .. note:: + .. note:: - If the environment variable ``REQUEST_METHOD`` is set, which usually - indicates your script is running in a CGI environment, the environment - variable ``HTTP_PROXY`` (uppercase ``_PROXY``) will be ignored. This is - because that variable can be injected by a client using the "Proxy:" - HTTP header. If you need to use an HTTP proxy in a CGI environment, - either use ``ProxyHandler`` explicitly, or make sure the variable name - is in lowercase (or at least the ``_proxy`` suffix). + If the environment variable ``REQUEST_METHOD`` is set, which usually + indicates your script is running in a CGI environment, the environment + variable ``HTTP_PROXY`` (uppercase ``_PROXY``) will be ignored. This is + because that variable can be injected by a client using the "Proxy:" HTTP + header. If you need to use an HTTP proxy in a CGI environment, either use + ``ProxyHandler`` explicitly, or make sure the variable name is in + lowercase (or at least the ``_proxy`` suffix). .. note:: urllib also exposes certain utility functions like splittype, splithost and @@ -344,47 +349,47 @@ URL Opener objects :class:`URLopener` objects will raise an :exc:`IOError` exception if the server returns an error code. - .. method:: open(fullurl[, data]) + .. method:: open(fullurl[, data]) - Open *fullurl* using the appropriate protocol. This method sets up cache and - proxy information, then calls the appropriate open method with its input - arguments. If the scheme is not recognized, :meth:`open_unknown` is called. - The *data* argument has the same meaning as the *data* argument of - :func:`urlopen`. + Open *fullurl* using the appropriate protocol. This method sets up cache and + proxy information, then calls the appropriate open method with its input + arguments. If the scheme is not recognized, :meth:`open_unknown` is called. + The *data* argument has the same meaning as the *data* argument of + :func:`urlopen`. - .. method:: open_unknown(fullurl[, data]) + .. method:: open_unknown(fullurl[, data]) - Overridable interface to open unknown URL types. + Overridable interface to open unknown URL types. - .. method:: retrieve(url[, filename[, reporthook[, data]]]) + .. method:: retrieve(url[, filename[, reporthook[, data]]]) - Retrieves the contents of *url* and places it in *filename*. The return value - is a tuple consisting of a local filename and either a - :class:`mimetools.Message` object containing the response headers (for remote - URLs) or ``None`` (for local URLs). The caller must then open and read the - contents of *filename*. If *filename* is not given and the URL refers to a - local file, the input filename is returned. If the URL is non-local and - *filename* is not given, the filename is the output of :func:`tempfile.mktemp` - with a suffix that matches the suffix of the last path component of the input - URL. If *reporthook* is given, it must be a function accepting three numeric - parameters. It will be called after each chunk of data is read from the - network. *reporthook* is ignored for local URLs. + Retrieves the contents of *url* and places it in *filename*. The return value + is a tuple consisting of a local filename and either a + :class:`mimetools.Message` object containing the response headers (for remote + URLs) or ``None`` (for local URLs). The caller must then open and read the + contents of *filename*. If *filename* is not given and the URL refers to a + local file, the input filename is returned. If the URL is non-local and + *filename* is not given, the filename is the output of :func:`tempfile.mktemp` + with a suffix that matches the suffix of the last path component of the input + URL. If *reporthook* is given, it must be a function accepting three numeric + parameters. It will be called after each chunk of data is read from the + network. *reporthook* is ignored for local URLs. - If the *url* uses the :file:`http:` scheme identifier, the optional *data* - argument may be given to specify a ``POST`` request (normally the request type - is ``GET``). The *data* argument must in standard - :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode` - function below. + If the *url* uses the :file:`http:` scheme identifier, the optional *data* + argument may be given to specify a ``POST`` request (normally the request type + is ``GET``). The *data* argument must in standard + :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode` + function below. - .. attribute:: version + .. attribute:: version - Variable that specifies the user agent of the opener object. To get - :mod:`urllib` to tell servers that it is a particular user agent, set this in a - subclass as a class variable or in the constructor before calling the base - constructor. + Variable that specifies the user agent of the opener object. To get + :mod:`urllib` to tell servers that it is a particular user agent, set this in a + subclass as a class variable or in the constructor before calling the base + constructor. .. class:: FancyURLopener(...) @@ -415,18 +420,18 @@ URL Opener objects users for the required information on the controlling terminal. A subclass may override this method to support more appropriate behavior if needed. - The :class:`FancyURLopener` class offers one additional method that should be - overloaded to provide the appropriate behavior: + The :class:`FancyURLopener` class offers one additional method that should be + overloaded to provide the appropriate behavior: - .. method:: prompt_user_passwd(host, realm) + .. method:: prompt_user_passwd(host, realm) - Return information needed to authenticate the user at the given host in the - specified security realm. The return value should be a tuple, ``(user, - password)``, which can be used for basic authentication. + Return information needed to authenticate the user at the given host in the + specified security realm. The return value should be a tuple, ``(user, + password)``, which can be used for basic authentication. - The implementation prompts for this information on the terminal; an application - should override this method to use an appropriate interaction model in the local - environment. + The implementation prompts for this information on the terminal; an application + should override this method to use an appropriate interaction model in the local + environment. .. exception:: ContentTooShortError(msg[, content]) diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst index 885db3d..bc69b5f 100644 --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -104,7 +104,7 @@ random UUID. .. attribute:: UUID.variant The UUID variant, which determines the internal layout of the UUID. This will be - one of the integer constants :const:`RESERVED_NCS`, :const:`RFC_4122`, + one of the constants :const:`RESERVED_NCS`, :const:`RFC_4122`, :const:`RESERVED_MICROSOFT`, or :const:`RESERVED_FUTURE`. diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index afbd611..0781e67 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -189,8 +189,8 @@ than needed. magic" (as a side effect of garbage collection). :class:`WeakValueDictionary` objects have the following additional methods. -These method have the same issues as the :meth:`iterkeyrefs` and :meth:`keyrefs` -methods of :class:`WeakKeyDictionary` objects. +These methods have the same issues as the :meth:`iterkeyrefs` and +:meth:`keyrefs` methods of :class:`WeakKeyDictionary` objects. .. method:: WeakValueDictionary.itervaluerefs() diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index a1d7951..f91259a 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -273,7 +273,7 @@ utility to most DOM users. .. rubric:: Footnotes -.. [#] The encoding string included in XML output should conform to the +.. [1] The encoding string included in XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml. diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 08b677b..39d811b 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -1031,7 +1031,7 @@ This is an example of counting the maximum depth of an XML file:: .. rubric:: Footnotes -.. [#] The encoding string included in XML output should conform to the +.. [1] The encoding string included in XML output should conform to the appropriate standards. For example, "UTF-8" is valid, but "UTF8" is not. See https://www.w3.org/TR/2006/REC-xml11-20060816/#NT-EncodingDecl and https://www.iana.org/assignments/character-sets/character-sets.xhtml. diff --git a/Doc/license.rst b/Doc/license.rst index ea37b5a..942ad20 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -87,7 +87,7 @@ PSF LICENSE AGREEMENT FOR PYTHON |release| analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use Python |release| alone or in any derivative version, provided, however, that PSF's License Agreement and PSF's notice of - copyright, i.e., "Copyright © 2001-2016 Python Software Foundation; All Rights + copyright, i.e., "Copyright © 2001-2017 Python Software Foundation; All Rights Reserved" are retained in Python |release| alone or in any derivative version prepared by Licensee. diff --git a/Doc/make.bat b/Doc/make.bat index 251f822..ef0e412 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -71,7 +71,7 @@ goto end :build if NOT "%PAPER%" == "" ( - set SPHINXOPTS=-D latex_paper_size=%PAPER% %SPHINXOPTS% + set SPHINXOPTS=-D latex_elements.papersize=%PAPER% %SPHINXOPTS% ) cmd /C %SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%* diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index db2fa17..7bdb141 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1409,8 +1409,12 @@ Basic customization hashed collections including :class:`set`, :class:`frozenset`, and :class:`dict`. :meth:`__hash__` should return an integer. The only required property is that objects which compare equal have the same hash value; it is - advised to somehow mix together (e.g. using exclusive or) the hash values for - the components of the object that also play a part in comparison of objects. + advised to mix together the hash values of the components of the object that + also play a part in comparison of objects by packing them into a tuple and + hashing the tuple. Example:: + + def __hash__(self): + return hash((self.name, self.nick, self.color)) If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it should not define a :meth:`__hash__` operation either; if it defines @@ -1887,6 +1891,14 @@ sequences, it should iterate through the values. :meth:`__nonzero__` method and whose :meth:`__len__` method returns zero is considered to be false in a Boolean context. + .. impl-detail:: + + In CPython, the length is required to be at most :attr:`sys.maxsize`. + If the length is larger than :attr:`!sys.maxsize` some features (such as + :func:`len`) may raise :exc:`OverflowError`. To prevent raising + :exc:`!OverflowError` by truth value testing, an object must define a + :meth:`__nonzero__` method. + .. method:: object.__getitem__(self, key) diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index f18984b..8556fa8 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -767,7 +767,7 @@ A consequence of this is that although the ``*expression`` syntax may appear 2 1 >>> f(a=1, *(2,)) Traceback (most recent call last): - File "", line 1, in ? + File "", line 1, in TypeError: f() got multiple values for keyword argument 'a' >>> f(1, *(2,)) 1 2 @@ -1058,10 +1058,6 @@ must be plain or long integers. The arguments are converted to a common type. .. _comparisons: -.. _is: -.. _is not: -.. _in: -.. _not in: Comparisons =========== @@ -1101,39 +1097,98 @@ The forms ``<>`` and ``!=`` are equivalent; for consistency with C, ``!=`` is preferred; where ``!=`` is mentioned below ``<>`` is also accepted. The ``<>`` spelling is considered obsolescent. +Value comparisons +----------------- + The operators ``<``, ``>``, ``==``, ``>=``, ``<=``, and ``!=`` compare the -values of two objects. The objects need not have the same type. If both are -numbers, they are converted to a common type. Otherwise, objects of different -types *always* compare unequal, and are ordered consistently but arbitrarily. -You can control comparison behavior of objects of non-built-in types by defining -a ``__cmp__`` method or rich comparison methods like ``__gt__``, described in -section :ref:`specialnames`. +values of two objects. The objects do not need to have the same type. + +Chapter :ref:`objects` states that objects have a value (in addition to type +and identity). The value of an object is a rather abstract notion in Python: +For example, there is no canonical access method for an object's value. Also, +there is no requirement that the value of an object should be constructed in a +particular way, e.g. comprised of all its data attributes. Comparison operators +implement a particular notion of what the value of an object is. One can think +of them as defining the value of an object indirectly, by means of their +comparison implementation. + +Types can customize their comparison behavior by implementing +a :meth:`__cmp__` method or +:dfn:`rich comparison methods` like :meth:`__lt__`, described in +:ref:`customization`. + +The default behavior for equality comparison (``==`` and ``!=``) is based on +the identity of the objects. Hence, equality comparison of instances with the +same identity results in equality, and equality comparison of instances with +different identities results in inequality. A motivation for this default +behavior is the desire that all objects should be reflexive (i.e. ``x is y`` +implies ``x == y``). + +The default order comparison (``<``, ``>``, ``<=``, and ``>=``) gives a +consistent but arbitrary order. (This unusual definition of comparison was used to simplify the definition of operations like sorting and the :keyword:`in` and :keyword:`not in` operators. In the future, the comparison rules for objects of different types are likely to change.) -Comparison of objects of the same type depends on the type: - -* Numbers are compared arithmetically. - -* Strings are compared lexicographically using the numeric equivalents (the - result of the built-in function :func:`ord`) of their characters. Unicode and - 8-bit strings are fully interoperable in this behavior. [#]_ - -* Tuples and lists are compared lexicographically using comparison of - corresponding elements. This means that to compare equal, each element must - compare equal and the two sequences must be of the same type and have the same - length. - - If not equal, the sequences are ordered the same as their first differing - elements. For example, ``cmp([1,2,x], [1,2,y])`` returns the same as - ``cmp(x,y)``. If the corresponding element does not exist, the shorter sequence - is ordered first (for example, ``[1,2] < [1,2,3]``). - -* Mappings (dictionaries) compare equal if and only if their sorted (key, value) - lists compare equal. [#]_ Outcomes other than equality are resolved +The behavior of the default equality comparison, that instances with different +identities are always unequal, may be in contrast to what types will need that +have a sensible definition of object value and value-based equality. Such +types will need to customize their comparison behavior, and in fact, a number +of built-in types have done that. + +The following list describes the comparison behavior of the most important +built-in types. + +* Numbers of built-in numeric types (:ref:`typesnumeric`) and of the standard + library types :class:`fractions.Fraction` and :class:`decimal.Decimal` can be + compared within and across their types, with the restriction that complex + numbers do not support order comparison. Within the limits of the types + involved, they compare mathematically (algorithmically) correct without loss + of precision. + +* Strings (instances of :class:`str` or :class:`unicode`) + compare lexicographically using the numeric equivalents (the + result of the built-in function :func:`ord`) of their characters. [#]_ + When comparing an 8-bit string and a Unicode string, the 8-bit string + is converted to Unicode. If the conversion fails, the strings + are considered unequal. + +* Instances of :class:`tuple` or :class:`list` can be compared only + within each of their types. Equality comparison across these types + results in unequality, and ordering comparison across these types + gives an arbitrary order. + + These sequences compare lexicographically using comparison of corresponding + elements, whereby reflexivity of the elements is enforced. + + In enforcing reflexivity of elements, the comparison of collections assumes + that for a collection element ``x``, ``x == x`` is always true. Based on + that assumption, element identity is compared first, and element comparison + is performed only for distinct elements. This approach yields the same + result as a strict element comparison would, if the compared elements are + reflexive. For non-reflexive elements, the result is different than for + strict element comparison. + + Lexicographical comparison between built-in collections works as follows: + + - For two collections to compare equal, they must be of the same type, have + the same length, and each pair of corresponding elements must compare + equal (for example, ``[1,2] == (1,2)`` is false because the type is not the + same). + + - Collections are ordered the same as their + first unequal elements (for example, ``cmp([1,2,x], [1,2,y])`` returns the + same as ``cmp(x,y)``). If a corresponding element does not exist, the + shorter collection is ordered first (for example, ``[1,2] < [1,2,3]`` is + true). + +* Mappings (instances of :class:`dict`) compare equal if and only if they have + equal `(key, value)` pairs. Equality comparison of the keys and values + enforces reflexivity. + + Outcomes other than equality are resolved consistently, but are not otherwise defined. [#]_ * Most other objects of built-in types compare unequal unless they are the same @@ -1141,39 +1196,83 @@ Comparison of objects of the same type depends on the type: another one is made arbitrarily but consistently within one execution of a program. -.. _membership-test-details: +User-defined classes that customize their comparison behavior should follow +some consistency rules, if possible: + +* Equality comparison should be reflexive. + In other words, identical objects should compare equal: + + ``x is y`` implies ``x == y`` + +* Comparison should be symmetric. + In other words, the following expressions should have the same result: + + ``x == y`` and ``y == x`` + + ``x != y`` and ``y != x`` + + ``x < y`` and ``y > x`` + + ``x <= y`` and ``y >= x`` + +* Comparison should be transitive. + The following (non-exhaustive) examples illustrate that: -The operators :keyword:`in` and :keyword:`not in` test for collection -membership. ``x in s`` evaluates to true if *x* is a member of the collection -*s*, and false otherwise. ``x not in s`` returns the negation of ``x in s``. -The collection membership test has traditionally been bound to sequences; an -object is a member of a collection if the collection is a sequence and contains -an element equal to that object. However, it make sense for many other object -types to support membership tests without being a sequence. In particular, -dictionaries (for keys) and sets support membership testing. + ``x > y and y > z`` implies ``x > z`` -For the list and tuple types, ``x in y`` is true if and only if there exists an -index *i* such that either ``x is y[i]`` or ``x == y[i]`` is true. + ``x < y and y <= z`` implies ``x < z`` -For the Unicode and string types, ``x in y`` is true if and only if *x* is a -substring of *y*. An equivalent test is ``y.find(x) != -1``. Note, *x* and *y* -need not be the same type; consequently, ``u'ab' in 'abc'`` will return -``True``. Empty strings are always considered to be a substring of any other -string, so ``"" in "abc"`` will return ``True``. +* Inverse comparison should result in the boolean negation. + In other words, the following expressions should have the same result: -.. versionchanged:: 2.3 - Previously, *x* was required to be a string of length ``1``. + ``x == y`` and ``not x != y`` + + ``x < y`` and ``not x >= y`` (for total ordering) + + ``x > y`` and ``not x <= y`` (for total ordering) + + The last two expressions apply to totally ordered collections (e.g. to + sequences, but not to sets or mappings). See also the + :func:`~functools.total_ordering` decorator. + +* The :func:`hash` result should be consistent with equality. + Objects that are equal should either have the same hash value, + or be marked as unhashable. + +Python does not enforce these consistency rules. + + +.. _in: +.. _not in: +.. _membership-test-details: + +Membership test operations +-------------------------- + +The operators :keyword:`in` and :keyword:`not in` test for membership. ``x in +s`` evaluates to ``True`` if *x* is a member of *s*, and ``False`` otherwise. +``x not in s`` returns the negation of ``x in s``. All built-in sequences and +set types support this as well as dictionary, for which :keyword:`in` tests +whether the dictionary has a given key. For container types such as list, tuple, +set, frozenset, dict, or collections.deque, the expression ``x in y`` is equivalent +to ``any(x is e or x == e for e in y)``. + +For the string and bytes types, ``x in y`` is ``True`` if and only if *x* is a +substring of *y*. An equivalent test is ``y.find(x) != -1``. Empty strings are +always considered to be a substring of any other string, so ``"" in "abc"`` will +return ``True``. For user-defined classes which define the :meth:`__contains__` method, ``x in -y`` is true if and only if ``y.__contains__(x)`` is true. +y`` returns ``True`` if ``y.__contains__(x)`` returns a true value, and +``False`` otherwise. For user-defined classes which do not define :meth:`__contains__` but do define -:meth:`__iter__`, ``x in y`` is true if some value ``z`` with ``x == z`` is +:meth:`__iter__`, ``x in y`` is ``True`` if some value ``z`` with ``x == z`` is produced while iterating over ``y``. If an exception is raised during the iteration, it is as if :keyword:`in` raised that exception. Lastly, the old-style iteration protocol is tried: if a class defines -:meth:`__getitem__`, ``x in y`` is true if and only if there is a non-negative +:meth:`__getitem__`, ``x in y`` is ``True`` if and only if there is a non-negative integer index *i* such that ``x == y[i]``, and all lower integer indices do not raise :exc:`IndexError` exception. (If any other exception is raised, it is as if :keyword:`in` raised that exception). @@ -1192,6 +1291,13 @@ The operator :keyword:`not in` is defined to have the inverse true value of operator: is not pair: identity; test + +.. _is: +.. _is not: + +Identity comparisons +-------------------- + The operators :keyword:`is` and :keyword:`is not` test for object identity: ``x is y`` is true if and only if *x* and *y* are the same object. ``x is not y`` yields the inverse truth value. [#]_ @@ -1418,15 +1524,24 @@ groups from right to left). cases, Python returns the latter result, in order to preserve that ``divmod(x,y)[0] * y + x % y`` be very close to ``x``. -.. [#] While comparisons between unicode strings make sense at the byte - level, they may be counter-intuitive to users. For example, the - strings ``u"\u00C7"`` and ``u"\u0043\u0327"`` compare differently, - even though they both represent the same unicode character (LATIN - CAPITAL LETTER C WITH CEDILLA). To compare strings in a human - recognizable way, compare using :func:`unicodedata.normalize`. - -.. [#] The implementation computes this efficiently, without constructing lists or - sorting. +.. [#] The Unicode standard distinguishes between :dfn:`code points` + (e.g. U+0041) and :dfn:`abstract characters` (e.g. "LATIN CAPITAL LETTER A"). + While most abstract characters in Unicode are only represented using one + code point, there is a number of abstract characters that can in addition be + represented using a sequence of more than one code point. For example, the + abstract character "LATIN CAPITAL LETTER C WITH CEDILLA" can be represented + as a single :dfn:`precomposed character` at code position U+00C7, or as a + sequence of a :dfn:`base character` at code position U+0043 (LATIN CAPITAL + LETTER C), followed by a :dfn:`combining character` at code position U+0327 + (COMBINING CEDILLA). + + The comparison operators on unicode strings compare at the level of Unicode code + points. This may be counter-intuitive to humans. For example, + ``u"\u00C7" == u"\u0043\u0327"`` is ``False``, even though both strings + represent the same abstract character "LATIN CAPITAL LETTER C WITH CEDILLA". + + To compare strings at the level of abstract characters (that is, in a way + intuitive to humans), use :func:`unicodedata.normalize`. .. [#] Earlier versions of Python used lexicographic comparison of the sorted (key, value) lists, but this was very expensive for the common case of comparing for diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 848bb9e..43935da 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -972,7 +972,7 @@ definition, function definition, or :keyword:`import` statement. builtin: execfile builtin: compile -**Programmer's note:** the :keyword:`global` is a directive to the parser. It +**Programmer's note:** :keyword:`global` is a directive to the parser. It applies only to code parsed at the same time as the :keyword:`global` statement. In particular, a :keyword:`global` statement contained in an :keyword:`exec` statement does not affect the code block *containing* the :keyword:`exec` diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 1b6b0e2..7bbd580 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -10,12 +10,12 @@ """ ISSUE_URI = 'https://bugs.python.org/issue%s' -SOURCE_URI = 'https://hg.python.org/cpython/file/2.7/%s' +SOURCE_URI = 'https://github.com/python/cpython/tree/2.7/%s' from docutils import nodes, utils +from docutils.parsers.rst import Directive from sphinx.util.nodes import split_explicit_title -from sphinx.util.compat import Directive from sphinx.writers.html import HTMLTranslator from sphinx.writers.latex import LaTeXTranslator @@ -58,7 +58,7 @@ LaTeXTranslator.depart_literal_block = new_depart_literal_block def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): issue = utils.unescape(text) - text = 'issue ' + issue + text = 'bpo-'+ issue refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue) return [refnode], [] diff --git a/Doc/tools/static/switchers.js b/Doc/tools/static/switchers.js new file mode 100644 index 0000000..bd31fac --- /dev/null +++ b/Doc/tools/static/switchers.js @@ -0,0 +1,147 @@ +(function() { + 'use strict'; + + // Parses versions in URL segments like: + // "3", "dev", "release/2.7" or "3.6rc2" + var version_regexs = [ + '(?:\\d)', + '(?:\\d\\.\\d[\\w\\d\\.]*)', + '(?:dev)', + '(?:release/\\d.\\d[\\x\\d\\.]*)']; + + var all_versions = { + '3.7': 'dev (3.7)', + '3.6': '3.6', + '3.5': '3.5', + '3.4': '3.4', + '3.3': '3.3', + '2.7': '2.7', + }; + + var all_languages = { + 'en': 'English', + 'fr': 'French', + 'ja': 'Japanese', + }; + + function build_version_select(current_version, current_release) { + var buf = [''); + return buf.join(''); + } + + function build_language_select(current_language) { + var buf = [''); + return buf.join(''); + } + + function navigate_to_first_existing(urls) { + // Navigate to the first existing URL in urls. + var url = urls.shift(); + if (urls.length == 0) { + window.location.href = url; + return; + } + $.ajax({ + url: url, + success: function() { + window.location.href = url; + }, + error: function() { + navigate_to_first_existing(urls); + } + }); + } + + function on_version_switch() { + var selected_version = $(this).children('option:selected').attr('value') + '/'; + var url = window.location.href; + var current_language = language_segment_from_url(url); + var current_version = version_segment_in_url(url); + var new_url = url.replace('.org/' + current_language + current_version, + '.org/' + current_language + selected_version); + if (new_url != url) { + navigate_to_first_existing([ + new_url, + url.replace('.org/' + current_language + current_version, + '.org/' + selected_version), + 'https://docs.python.org/' + current_language + selected_version, + 'https://docs.python.org/' + selected_version, + 'https://docs.python.org/' + ]); + } + } + + function on_language_switch() { + var selected_language = $(this).children('option:selected').attr('value') + '/'; + var url = window.location.href; + var current_language = language_segment_from_url(url); + var current_version = version_segment_in_url(url); + if (selected_language == 'en/') // Special 'default' case for english. + selected_language = ''; + var new_url = url.replace('.org/' + current_language + current_version, + '.org/' + selected_language + current_version); + if (new_url != url) { + navigate_to_first_existing([ + new_url, + 'https://docs.python.org/' + ]); + } + } + + // Returns the path segment of the language as a string, like 'fr/' + // or '' if not found. + function language_segment_from_url(url) { + var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)'; + var match = url.match(language_regexp); + if (match !== null) + return match[1]; + return ''; + } + + // Returns the path segment of the version as a string, like '3.6/' + // or '' if not found. + function version_segment_in_url(url) { + var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)'; + var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)'; + var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')'; + var match = url.match(version_regexp); + if (match !== null) + return match[1]; + return '' + } + + $(document).ready(function() { + var release = DOCUMENTATION_OPTIONS.VERSION; + var language_segment = language_segment_from_url(window.location.href); + var current_language = language_segment.replace(/\/+$/g, '') || 'en'; + var version = release.substr(0, 3); + var version_select = build_version_select(version, release); + + $('.version_switcher_placeholder').html(version_select); + $('.version_switcher_placeholder select').bind('change', on_version_switch); + + var language_select = build_language_select(current_language); + + $('.language_switcher_placeholder').html(language_select); + $('.language_switcher_placeholder select').bind('change', on_language_switch); + }); +})(); diff --git a/Doc/tools/static/version_switch.js b/Doc/tools/static/version_switch.js deleted file mode 100644 index 8b36a61..0000000 --- a/Doc/tools/static/version_switch.js +++ /dev/null @@ -1,67 +0,0 @@ -(function() { - 'use strict'; - - var all_versions = { - '3.7': 'dev (3.7)', - '3.6': '3.6', - '3.5': '3.5', - '3.4': '3.4', - '3.3': '3.3', - '2.7': '2.7', - }; - - function build_select(current_version, current_release) { - var buf = [''); - return buf.join(''); - } - - function patch_url(url, new_version) { - var url_re = /\.org\/(\d|py3k|dev|((release\/)?\d\.\d[\w\d\.]*))\//, - new_url = url.replace(url_re, '.org/' + new_version + '/'); - - if (new_url == url && !new_url.match(url_re)) { - // python 2 url without version? - new_url = url.replace(/\.org\//, '.org/' + new_version + '/'); - } - return new_url; - } - - function on_switch() { - var selected = $(this).children('option:selected').attr('value'); - - var url = window.location.href, - new_url = patch_url(url, selected); - - if (new_url != url) { - // check beforehand if url exists, else redirect to version's start page - $.ajax({ - url: new_url, - success: function() { - window.location.href = new_url; - }, - error: function() { - window.location.href = 'https://docs.python.org/' + selected; - } - }); - } - } - - $(document).ready(function() { - var release = DOCUMENTATION_OPTIONS.VERSION; - var version = release.substr(0, 3); - var select = build_select(version, release); - - $('.version_switcher_placeholder').html(select); - $('.version_switcher_placeholder select').bind('change', on_switch); - }); -})(); diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv index 17b2366..f7d23e2 100644 --- a/Doc/tools/susp-ignored.csv +++ b/Doc/tools/susp-ignored.csv @@ -46,7 +46,7 @@ howto/pyporting,,::,Programming Language :: Python :: 2 howto/pyporting,,::,Programming Language :: Python :: 3 howto/regex,,::, howto/regex,,:foo,(?:foo) -howto/urllib2,,:password,"for example ""joe:password@example.com""" +howto/urllib2,,:password,"""joe:password@example.com""" library/audioop,,:ipos,"# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)]," library/bisect,,:hi,all(val >= x for val in a[i:hi]) library/bisect,,:hi,all(val > x for val in a[i:hi]) @@ -99,6 +99,8 @@ library/profile,,:lineno,ncalls tottime percall cumtime percall filename:lin library/profile,,:lineno,filename:lineno(function) library/pyexpat,,:elem1, library/pyexpat,,:py,"xmlns:py = ""http://www.python.org/ns/"">" +library/re,,`,!#$%&'*+-.^_`|~: +library/re,,`,[abcdefghijklmnopqrstuvwxyz0123456789\!\#\$\%\&\'\*\+\-\.\^\_\`\|\~\:]+ library/smtplib,,:port,method must support that as well as a regular host:port library/socket,,::,'5aef:2b::8' library/sqlite3,,:memory, @@ -150,7 +152,7 @@ reference/datamodel,,:step,a[i:j:step] reference/datamodel,,:max, reference/expressions,,:index,x[index:index] reference/expressions,,`,`expressions...` -reference/expressions,,`,"""`""" +reference/expressions,350,`,` reference/grammar,,`,'`' testlist1 '`' reference/lexical_analysis,,:fileencoding,# vim:fileencoding= reference/lexical_analysis,,`,", : . ` = ;" diff --git a/Doc/tools/templates/download.html b/Doc/tools/templates/download.html index 2a885d7..298dc5c 100644 --- a/Doc/tools/templates/download.html +++ b/Doc/tools/templates/download.html @@ -27,34 +27,34 @@ files in megabytes.{% endtrans %}

{% trans %}Download{% endtrans %} - {% trans %}(ca. 8 MB){% endtrans %} + {% trans %}(ca. 11 MB){% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 8 MB){% endtrans %} + {% trans %}(ca. 11 MB){% endtrans %} {% trans %}PDF (A4 paper size){% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 8 MB){% endtrans %} + {% trans %}(ca. 11 MB){% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 8 MB){% endtrans %} + {% trans %}(ca. 11 MB){% endtrans %} {% trans %}HTML{% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 6 MB){% endtrans %} + {% trans %}(ca. 7.5 MB){% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 4 MB){% endtrans %} + {% trans %}(ca. 5 MB){% endtrans %} @@ -62,12 +62,12 @@ files in megabytes.{% endtrans %}

{% trans %}Download{% endtrans %} - {% trans %}(ca. 2 MB){% endtrans %} + {% trans %}(ca. 2.5 MB){% endtrans %} {% trans %}Download{% endtrans %} - {% trans %}(ca. 1.5 MB){% endtrans %} + {% trans %}(ca. 2 MB){% endtrans %} @@ -75,9 +75,9 @@ files in megabytes.{% endtrans %}

{% trans %}These archives contain all the content in the documentation.{% endtrans %}

-

{% trans download_page="https://www.python.org/download/releases/{{ release[:5] }}/" %}HTML Help -(.chm) files are made available in the "Windows" section -on the Python download page.{% endtrans %}

+

{% trans download_page="https://www.python.org/downloads/release/python-" + release.replace('.', '') + "/" %}HTML Help +(.chm) files are made available in the "Files" section +on the Python download page.{% endtrans %}

{% trans %}Unpacking{% endtrans %}

diff --git a/Doc/tools/templates/indexcontent.html b/Doc/tools/templates/indexcontent.html index 6488c16..5cba973 100644 --- a/Doc/tools/templates/indexcontent.html +++ b/Doc/tools/templates/indexcontent.html @@ -1,5 +1,12 @@ -{% extends "defindex.html" %} -{% block tables %} +{% extends "layout.html" %} +{%- block htmltitle -%} +{{ shorttitle }} +{%- endblock -%} +{% block body %} +

{{ docstitle|e }}

+

+ {% trans %}Welcome! This is the documentation for Python {{ release }}.{% endtrans %} +

{% trans %}Parts of the documentation:{% endtrans %}

diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index d93021d..76071e8 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -2,8 +2,9 @@

{% trans %}Download these documents{% endtrans %}

{% trans %}Docs for other versions{% endtrans %}

diff --git a/Doc/tools/templates/layout.html b/Doc/tools/templates/layout.html index 78b3b27..8d6d3e5 100644 --- a/Doc/tools/templates/layout.html +++ b/Doc/tools/templates/layout.html @@ -4,7 +4,8 @@ style="vertical-align: middle; margin-top: -1px"/>
  • Python{{ reldelim1 }}
  • - {%- if versionswitcher is defined %} + {%- if switchers is defined %} + {{ language or 'en' }} {{ release }} {% trans %}Documentation{% endtrans %}{{ reldelim1 }} {%- else %} @@ -16,8 +17,9 @@ {% block relbar2 %} {% if builder != 'qthelp' %} {{ relbar() }} {% endif %} {% endblock %} {% block extrahead %} + {% if not embedded %}{% endif %} - {% if versionswitcher is defined and not embedded %}{% endif %} + {% if switchers is defined and not embedded %}{% endif %} {{ super() }} {% if builder == 'qthelp' %}