diff options
Diffstat (limited to 'Doc')
92 files changed, 584 insertions, 372 deletions
diff --git a/Doc/README.txt b/Doc/README.txt index 4f8e9f8..a362ecc 100644 --- a/Doc/README.txt +++ b/Doc/README.txt @@ -15,7 +15,7 @@ Building the docs You need to have Sphinx <http://sphinx-doc.org/> installed; it is the toolset used to build the docs. It is not included in this tree, but maintained -separately and available from PyPI <https://pypi.python.org/pypi/Sphinx>. +separately and available from PyPI <https://pypi.org/project/Sphinx>. Using make diff --git a/Doc/bugs.rst b/Doc/bugs.rst index 25ce3ca..3749f93 100644 --- a/Doc/bugs.rst +++ b/Doc/bugs.rst @@ -14,7 +14,7 @@ Documentation bugs If you find a bug in this documentation or would like to propose an improvement, please submit a bug report on the :ref:`tracker <using-the-tracker>`. If you -have a suggestion how to fix it, include that as well. +have a suggestion on how to fix it, include that as well. If you're short on time, you can also email documentation bug reports to docs@python.org (behavioral bugs can be sent to python-list@python.org). @@ -84,5 +84,5 @@ the `core-mentorship mailing list`_ is a friendly place to get answers to any and all questions pertaining to the process of fixing issues in Python. .. _Documentation bugs: https://bugs.python.org/issue?@filter=status&@filter=components&components=4&status=1&@columns=id,activity,title,status&@sort=-activity -.. _Python Developer's Guide: https://docs.python.org/devguide/ -.. _core-mentorship mailing list: https://mail.python.org/mailman/listinfo/core-mentorship/ +.. _Python Developer's Guide: https://devguide.python.org/ +.. _core-mentorship mailing list: https://mail.python.org/mailman3/lists/core-mentorship.python.org/ diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 4e5a043..77940ac 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -98,7 +98,7 @@ The new-style Py_buffer struct suboffset value that it negative indicates that no de-referencing should occur (striding in a contiguous memory block). - If all suboffsets are negative (i.e. no de-referencing is needed, then + If all suboffsets are negative (i.e. no de-referencing is needed), then this field must be NULL (the default value). Here is a function that returns a pointer to the element in an N-D array diff --git a/Doc/c-api/capsule.rst b/Doc/c-api/capsule.rst index b8642d0..fd4279c 100644 --- a/Doc/c-api/capsule.rst +++ b/Doc/c-api/capsule.rst @@ -9,6 +9,8 @@ Capsules Refer to :ref:`using-capsules` for more information on using these objects. +.. versionadded:: 2.7 + .. c:type:: PyCapsule @@ -19,6 +21,7 @@ Refer to :ref:`using-capsules` for more information on using these objects. regular import mechanism can be used to access C APIs defined in dynamically loaded modules. + .. c:type:: PyCapsule_Destructor The type of a destructor callback for a capsule. Defined as:: @@ -104,8 +107,8 @@ Refer to :ref:`using-capsules` for more information on using these objects. import the module conventionally (using :c:func:`PyImport_ImportModule`). Return the capsule's internal *pointer* on success. On failure, set an - exception and return *NULL*. However, if :c:func:`PyCapsule_Import` failed to - import the module, and *no_block* was true, no exception is set. + exception and return *NULL*. + .. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name) @@ -122,18 +125,21 @@ Refer to :ref:`using-capsules` for more information on using these objects. Return a nonzero value if the object is valid and matches the name passed in. Return ``0`` otherwise. This function will not fail. + .. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context) Set the context pointer inside *capsule* to *context*. Return ``0`` on success. Return nonzero and set an exception on failure. + .. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor) Set the destructor inside *capsule* to *destructor*. Return ``0`` on success. Return nonzero and set an exception on failure. + .. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name) Set the name inside *capsule* to *name*. If non-*NULL*, the name must @@ -142,6 +148,7 @@ Refer to :ref:`using-capsules` for more information on using these objects. Return ``0`` on success. Return nonzero and set an exception on failure. + .. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer) Set the void pointer inside *capsule* to *pointer*. The pointer may not be diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 9438fea..18ecd07 100644 --- a/Doc/c-api/gcsupport.rst +++ b/Doc/c-api/gcsupport.rst @@ -56,7 +56,7 @@ Constructors for container types must conform to two rules: .. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize) Resize an object allocated by :c:func:`PyObject_NewVar`. Returns the - resized object or *NULL* on failure. + resized object or *NULL* on failure. *op* must not be tracked by the collector yet. .. versionchanged:: 2.5 This function used an :c:type:`int` type for *newsize*. This might diff --git a/Doc/c-api/memory.rst b/Doc/c-api/memory.rst index 258898d..2b9fb73 100644 --- a/Doc/c-api/memory.rst +++ b/Doc/c-api/memory.rst @@ -35,7 +35,7 @@ operate within the bounds of the private heap. It is important to understand that the management of the Python heap is performed by the interpreter itself and that the user has no control over it, -even if she regularly manipulates object pointers to memory blocks inside that +even if they regularly manipulate object pointers to memory blocks inside that heap. The allocation of heap space for Python objects and other internal buffers is performed on demand by the Python memory manager through the Python/C API functions listed in this document. diff --git a/Doc/copyright.rst b/Doc/copyright.rst index 540ff5e..393a1f0 100644 --- a/Doc/copyright.rst +++ b/Doc/copyright.rst @@ -4,7 +4,7 @@ Copyright Python and this documentation is: -Copyright © 2001-2018 Python Software Foundation. All rights reserved. +Copyright © 2001-2019 Python Software Foundation. All rights reserved. Copyright © 2000 BeOpen.com. All rights reserved. diff --git a/Doc/distributing/index.rst b/Doc/distributing/index.rst index 82ecd2c..b0dccb3 100644 --- a/Doc/distributing/index.rst +++ b/Doc/distributing/index.rst @@ -31,7 +31,7 @@ installing other Python projects, refer to the Key terms ========= -* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public +* the `Python Packaging Index <https://pypi.org>`__ is a public repository of open source licensed packages made available for use by other Python users * the `Python Packaging Authority diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 18844dd..eade905 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -78,7 +78,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | - | | package | <https://pypi.python.org/pypi?:action=list_classifiers>`_. | + | | package | <https://pypi.org/classifiers>`_. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | a subclass of | | | class to use | :class:`distutils.core.Distribution` | @@ -934,7 +934,7 @@ timestamp dependency analysis. .. function:: newer_group(sources, target[, missing='error']) Return true if *target* is out-of-date with respect to any file listed in - *sources* In other words, if *target* exists and is newer than every file in + *sources*. In other words, if *target* exists and is newer than every file in *sources*, return false; otherwise return true. *missing* controls what we do when a source file is missing; the default (``'error'``) is to blow up with an :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst index 15ab3b3..acd499a 100644 --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -21,7 +21,7 @@ specialty---writing code and creating source distributions---while an intermediary species called *packagers* springs up to turn source distributions into built distributions for as many platforms as there are packagers. -Of course, the module developer could be his own packager; or the packager could +Of course, the module developer could be their own packager; or the packager could be a volunteer "out there" somewhere who has access to a platform which the original developer does not; or it could be software periodically grabbing new source distributions and turning them into built distributions for as many diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst index fc6184f..488619e 100644 --- a/Doc/distutils/introduction.rst +++ b/Doc/distutils/introduction.rst @@ -94,7 +94,7 @@ containing your setup script :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`. -If an end-user wishes to install your :mod:`foo` module, all she has to do is +If an end-user wishes to install your :mod:`foo` module, all they have to do is download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the :file:`foo-1.0` directory---run :: @@ -193,8 +193,8 @@ modules using the Distutils: module distribution a collection of Python modules distributed together as a single downloadable resource and meant to be installed *en masse*. Examples of some well-known - module distributions are Numeric Python, PyXML, PIL (the Python Imaging - Library), or mxBase. (This would be called a *package*, except that term is + module distributions are Numeric Python, PyXML, Pillow, + or mxBase. (This would be called a *package*, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.) diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst index 8087584..cd11f20 100644 --- a/Doc/distutils/packageindex.rst +++ b/Doc/distutils/packageindex.rst @@ -248,4 +248,4 @@ without warnings does not guarantee that PyPI will convert the content successfully. -.. _Python Package Index (PyPI): https://pypi.python.org/pypi +.. _Python Package Index (PyPI): https://pypi.org diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 6b82c40..8407206 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -520,20 +520,23 @@ following way:: setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), ('config', ['cfg/data.cfg']), - ('/etc/init.d', ['init-script'])] ) -Note that you can specify the directory names where the data files will be -installed, but you cannot rename the data files themselves. - Each (*directory*, *files*) pair in the sequence specifies the installation -directory and the files to install there. If *directory* is a relative path, it -is interpreted relative to the installation prefix (Python's ``sys.prefix`` for -pure-Python packages, ``sys.exec_prefix`` for packages that contain extension -modules). Each file name in *files* is interpreted relative to the -:file:`setup.py` script at the top of the package source distribution. No -directory information from *files* is used to determine the final location of -the installed file; only the name of the file is used. +directory and the files to install there. + +Each file name in *files* is interpreted relative to the :file:`setup.py` +script at the top of the package source distribution. Note that you can +specify the directory where the data files will be installed, but you cannot +rename the data files themselves. + +The *directory* should be a relative path. It is interpreted relative to the +installation prefix (Python's ``sys.prefix`` for system installations; +``site.USER_BASE`` for user installations). Distutils allows *directory* to be +an absolute installation path, but this is discouraged since it is +incompatible with the wheel packaging format. No directory information from +*files* is used to determine the final location of the installed file; only +the name of the file is used. You can specify the ``data_files`` options as a simple sequence of files without specifying a target directory, but this is not recommended, and the @@ -606,7 +609,7 @@ Notes: (4) These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - <https://pypi.python.org/pypi>`_. + <https://pypi.org>`_. (5) The ``long_description`` field is used by PyPI when you are diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 15e4af5..8588daa 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -2,6 +2,11 @@ Design and History FAQ ====================== +.. only:: html + + .. contents:: + + Why does Python use indentation for grouping of statements? ----------------------------------------------------------- @@ -221,24 +226,25 @@ Python file objects support the iterator protocol, so you can now write simply:: Why does Python use methods for some functionality (e.g. list.index()) but functions for other (e.g. len(list))? ---------------------------------------------------------------------------------------------------------------- -The major reason is history. Functions were used for those operations that were -generic for a group of types and which were intended to work even for objects -that didn't have methods at all (e.g. tuples). It is also convenient to have a -function that can readily be applied to an amorphous collection of objects when -you use the functional features of Python (``map()``, ``zip()`` et al). +As Guido said: -In fact, implementing ``len()``, ``max()``, ``min()`` as a built-in function is -actually less code than implementing them as methods for each type. One can -quibble about individual cases but it's a part of Python, and it's too late to -make such fundamental changes now. The functions have to remain to avoid massive -code breakage. + (a) For some operations, prefix notation just reads better than + postfix -- prefix (and infix!) operations have a long tradition in + mathematics which likes notations where the visuals help the + mathematician thinking about a problem. Compare the easy with which we + rewrite a formula like x*(a+b) into x*a + x*b to the clumsiness of + doing the same thing using a raw OO notation. -.. XXX talk about protocols? + (b) When I read code that says len(x) I *know* that it is asking for + the length of something. This tells me two things: the result is an + integer, and the argument is some kind of container. To the contrary, + when I read x.len(), I have to already know that x is some kind of + container implementing an interface or inheriting from a class that + has a standard len(). Witness the confusion we occasionally have when + a class that is not implementing a mapping has a get() or keys() + method, or something that isn't a file has a write() method. -.. note:: - - For string operations, Python has moved from external functions (the - ``string`` module) to methods. However, ``len()`` is still a function. + -- https://mail.python.org/pipermail/python-3000/2006-November/004643.html Why is join() a string method instead of a list or tuple method? @@ -498,10 +504,10 @@ you can always change a list's elements. Only immutable elements can be used as dictionary keys, and hence only tuples and not lists can be used as keys. -How are lists implemented? --------------------------- +How are lists implemented in CPython? +------------------------------------- -Python's lists are really variable-length arrays, not Lisp-style linked lists. +CPython's lists are really variable-length arrays, not Lisp-style linked lists. The implementation uses a contiguous array of references to other objects, and keeps a pointer to this array and the array's length in a list head structure. @@ -514,10 +520,10 @@ when the array must be grown, some extra space is allocated so the next few times don't require an actual resize. -How are dictionaries implemented? ---------------------------------- +How are dictionaries implemented in CPython? +-------------------------------------------- -Python's dictionaries are implemented as resizable hash tables. Compared to +CPython's dictionaries are implemented as resizable hash tables. Compared to B-trees, this gives better performance for lookup (the most common operation by far) under most circumstances, and the implementation is simpler. diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 4be58d6..0a256b5 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -286,7 +286,7 @@ However sometimes you have to run the embedded Python interpreter in the same thread as your rest application and you can't allow the :c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error`` -equal to ``E_EOF``, which means the input is incomplete). Here's a sample code +equal to ``E_EOF``, which means the input is incomplete. Here's a sample code fragment, untested, inspired by code from Alex Farber:: #include <Python.h> diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 35cad55..887dea7 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -117,7 +117,7 @@ programming), software engineering (unit testing, logging, profiling, parsing Python code), and operating system interfaces (system calls, filesystems, TCP/IP sockets). Look at the table of contents for :ref:`library-index` to get an idea of what's available. A wide variety of third-party extensions are also -available. Consult `the Python Package Index <https://pypi.python.org/pypi>`_ to +available. Consult `the Python Package Index <https://pypi.org>`_ to find packages of interest to you. @@ -306,17 +306,19 @@ usually around 18 months between major releases. The developers issue "bugfix" releases of older versions, so the stability of existing releases gradually improves. Bugfix releases, indicated by a third -component of the version number (e.g. 2.5.3, 2.6.2), are managed for stability; +component of the version number (e.g. 3.5.3, 3.6.2), are managed for stability; only fixes for known problems are included in a bugfix release, and it's guaranteed that interfaces will remain the same throughout a series of bugfix releases. The latest stable releases can always be found on the `Python download page -<https://www.python.org/downloads/>`_. There are two recommended production-ready -versions at this point in time, because at the moment there are two branches of -stable releases: 2.x and 3.x. Python 3.x may be less useful than 2.x, since -currently there is more third party software available for Python 2 than for -Python 3. Python 2 code will generally not run unchanged in Python 3. +<https://www.python.org/downloads/>`_. There are two production-ready version +of Python: 2.x and 3.x, but the recommended one at this times is Python 3.x. +Although Python 2.x is still widely used, `it will not be +maintained after January 1, 2020 <https://www.python.org/dev/peps/pep-0373/>`_. +Python 2.x was known for having more third-party libraries available, however, +by the time of this writing, most of the widely used libraries support Python 3.x, +and some are even dropping the Python 2.x support. How many people are using Python? diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index d1b3efb..a259465 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -19,7 +19,7 @@ standard library module. (Eventually you'll learn what's in the standard library and will be able to skip this step.) For third-party packages, search the `Python Package Index -<https://pypi.python.org/pypi>`_ or try `Google <https://www.google.com>`_ or +<https://pypi.org>`_ or try `Google <https://www.google.com>`_ or another Web search engine. Searching for "Python" plus a keyword or two for your topic of interest will usually find something helpful. @@ -585,7 +585,7 @@ substituted for standard input and output. You will have to use pseudo ttys ("ptys") instead of pipes. Or you can use a Python interface to Don Libes' "expect" library. A Python extension that interfaces to expect is called "expy" and available from http://expectpy.sourceforge.net. A pure Python solution that -works like expect is `pexpect <https://pypi.python.org/pypi/pexpect/>`_. +works like expect is `pexpect <https://pypi.org/project/pexpect/>`_. How do I access the serial (RS232) port? diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index f8e23cf..7f0c955 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -17,18 +17,6 @@ This is not necessarily a straightforward question. If you are already familiar with running programs from the Windows command line then everything will seem obvious; otherwise, you might need a little more guidance. -.. sidebar:: |Python Development on XP|_ - :subtitle: `Python Development on XP`_ - - This series of screencasts aims to get you up and running with Python on - Windows XP. The knowledge is distilled into 1.5 hours and will get you up - and running with the right Python distribution, coding in your choice of IDE, - and debugging and writing solid code with unit-tests. - -.. |Python Development on XP| image:: python-video-icon.png -.. _`Python Development on XP`: - http://showmedo.com/videotutorials/series?name=pythonOzsvaldPyNewbieSeries - Unless you use some sort of integrated development environment, you will end up *typing* Windows commands into what is variously referred to as a "DOS window" or "Command prompt window". Usually you can create such a window from your @@ -92,18 +80,6 @@ gives you a message like:: 'python' is not recognized as an internal or external command, operable program or batch file. -.. sidebar:: |Adding Python to DOS Path|_ - :subtitle: `Adding Python to DOS Path`_ - - Python is not added to the DOS path by default. This screencast will walk - you through the steps to add the correct entry to the `System Path`, allowing - Python to be executed from the command-line by all users. - -.. |Adding Python to DOS Path| image:: python-video-icon.png -.. _`Adding Python to DOS Path`: - http://showmedo.com/videotutorials/video?name=960000&fromSeriesID=96 - - or:: Bad command or filename diff --git a/Doc/glossary.rst b/Doc/glossary.rst index cbd1237..9e6bf23 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -14,8 +14,9 @@ Glossary ``...`` The default Python prompt of the interactive shell when entering code for - an indented code block or within a pair of matching left and right - delimiters (parentheses, square brackets or curly braces). + an indented code block, when within a pair of matching left and right + delimiters (parentheses, square brackets, curly braces or triple quotes), + or after specifying a decorator. 2to3 A tool that tries to convert Python 2.x code to Python 3.x code by @@ -296,7 +297,7 @@ Glossary the :func:`next` function. Each :keyword:`yield` temporarily suspends processing, remembering the location execution state (including local variables and pending try-statements). When the generator resumes, it - picks-up where it left-off (in contrast to functions which start fresh on + picks up where it left off (in contrast to functions which start fresh on every invocation). .. index:: single: generator expression @@ -457,7 +458,7 @@ Glossary lambda An anonymous inline function consisting of a single :term:`expression` which is evaluated when the function is called. The syntax to create - a lambda function is ``lambda [arguments]: expression`` + a lambda function is ``lambda [parameters]: expression`` LBYL Look before you leap. This coding style explicitly tests for @@ -474,7 +475,7 @@ Glossary list A built-in Python :term:`sequence`. Despite its name it is more akin to an array in other languages than to a linked list since access to - elements are O(1). + elements is O(1). list comprehension A compact way to process all or part of the elements in a sequence and @@ -625,6 +626,21 @@ Glossary :ref:`the difference between arguments and parameters <faq-argument-vs-parameter>`, and the :ref:`function` section. + PEP + Python Enhancement Proposal. A PEP is a design document + providing information to the Python community, or describing a new + feature for Python or its processes or environment. PEPs should + provide a concise technical specification and a rationale for proposed + features. + + PEPs are intended to be the primary mechanisms for proposing major new + features, for collecting community input on an issue, and for documenting + the design decisions that have gone into Python. The PEP author is + responsible for building consensus within the community and documenting + dissenting opinions. + + See :pep:`1`. + positional argument See :term:`argument`. @@ -694,7 +710,7 @@ Glossary struct sequence A tuple with named elements. Struct sequences expose an interface similiar - to :term:`named tuple` in that elements can either be accessed either by + to :term:`named tuple` in that elements can be accessed either by index or as an attribute. However, they do not have any of the named tuple methods like :meth:`~collections.somenamedtuple._make` or :meth:`~collections.somenamedtuple._asdict`. Examples of struct sequences diff --git a/Doc/howto/doanddont.rst b/Doc/howto/doanddont.rst index 98dbad1..35e1583 100644 --- a/Doc/howto/doanddont.rst +++ b/Doc/howto/doanddont.rst @@ -285,7 +285,7 @@ There are also many useful built-in functions people seem not to be aware of for some reason: :func:`min` and :func:`max` can find the minimum/maximum of any sequence with comparable semantics, for example, yet many people write their own :func:`max`/:func:`min`. Another highly useful function is -:func:`reduce` which can be used to repeatly apply a binary operation to a +:func:`reduce` which can be used to repeatedly apply a binary operation to a sequence, reducing it to a single value. For example, compute a factorial with a series of multiply operations:: diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst index 8562d23..88b0177 100644 --- a/Doc/howto/pyporting.rst +++ b/Doc/howto/pyporting.rst @@ -427,25 +427,25 @@ to make sure everything functions as expected in both versions of Python. .. _2to3: https://docs.python.org/3/library/2to3.html -.. _caniusepython3: https://pypi.python.org/pypi/caniusepython3 +.. _caniusepython3: https://pypi.org/project/caniusepython3 .. _cheat sheet: http://python-future.org/compatible_idioms.html -.. _coverage.py: https://pypi.python.org/pypi/coverage +.. _coverage.py: https://pypi.org/project/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 +.. _importlib2: https://pypi.org/project/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 +.. _Pylint: https://pypi.org/project/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 +.. _six: https://pypi.org/project/six +.. _tox: https://pypi.org/project/tox +.. _trove classifier: https://pypi.org/classifiers .. _"What's New": https://docs.python.org/3/whatsnew/index.html diff --git a/Doc/howto/webservers.rst b/Doc/howto/webservers.rst index a555083..5071a8a 100644 --- a/Doc/howto/webservers.rst +++ b/Doc/howto/webservers.rst @@ -301,7 +301,7 @@ following WSGI-application:: WSGIServer(app).run() This is a simple WSGI application, but you need to install `flup -<https://pypi.python.org/pypi/flup/1.0>`_ first, as flup handles the low level +<https://pypi.org/project/flup/1.0>`_ first, as flup handles the low level FastCGI access. .. seealso:: @@ -583,7 +583,7 @@ alternate storage mechanism. helps with choosing a method for saving data * `SQLAlchemy <http://www.sqlalchemy.org/>`_, the most powerful OR-Mapper - for Python, and `Elixir <https://pypi.python.org/pypi/Elixir>`_, which makes + for Python, and `Elixir <https://pypi.org/project/Elixir>`_, which makes SQLAlchemy easier to use * `SQLObject <http://www.sqlobject.org/>`_, another popular OR-Mapper diff --git a/Doc/includes/run-func.c b/Doc/includes/run-func.c index 5a7df0d..8276b01 100644 --- a/Doc/includes/run-func.c +++ b/Doc/includes/run-func.c @@ -3,7 +3,7 @@ int main(int argc, char *argv[]) { - PyObject *pName, *pModule, *pDict, *pFunc; + PyObject *pName, *pModule, *pFunc; PyObject *pArgs, *pValue; int i; diff --git a/Doc/installing/index.rst b/Doc/installing/index.rst index cbbb882..9b89d08 100644 --- a/Doc/installing/index.rst +++ b/Doc/installing/index.rst @@ -39,9 +39,8 @@ Key terms being installed system wide * ``virtualenv`` is a third party tools for creating virtual environments, it is defaults to installing ``pip`` into all created virtual environments. -* the `Python Packaging Index <https://pypi.python.org/pypi>`__ is a public - repository of open source licensed packages made available for use by - other Python users +* the `Python Packaging Index <https://pypi.org>`__ is a public repository of + open source licensed packages made available for use by other Python users * the `Python Packaging Authority <https://www.pypa.io/en/latest/>`__ are the group of developers and documentation authors responsible for the maintenance and diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 3a00a9c..b5ba139 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -19,10 +19,10 @@ was added to Python. (See also :pep:`3141` and the :mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.) The :mod:`collections` module has some concrete classes that derive from -ABCs; these can, of course, be further derived. In addition the +ABCs; these can, of course, be further derived. In addition, the :mod:`collections` module has some ABCs that can be used to test whether -a class or instance provides a particular interface, for example, is it -hashable or a mapping. +a class or instance provides a particular interface, for example, if it is +hashable or if it is a mapping. This module provides the following class: diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst index 71957ec..478a842 100644 --- a/Doc/library/bz2.rst +++ b/Doc/library/bz2.rst @@ -35,6 +35,10 @@ Here is a summary of the features offered by the bz2 module: * Thread safety uses individual locking mechanism. +.. note:: + Handling of multi-stream bzip2 files is not supported. Modules such as + `bz2file <https://github.com/nvawda/bz2file>`_ let you overcome this. + (De)compression of files ------------------------ @@ -74,7 +78,7 @@ Handling of compressed files is offered by the :class:`BZ2File` class. input file, only the first stream will be accessible. If you require support for multi-stream files, consider using the third-party :mod:`bz2file` module (available from - `PyPI <https://pypi.python.org/pypi/bz2file>`_). This module provides a + `PyPI <https://pypi.org/project/bz2file>`_). This module provides a backport of Python 3.3's :class:`BZ2File` class, which does support multi-stream files. diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst index 1bfdb39..ecd62c8 100644 --- a/Doc/library/cgi.rst +++ b/Doc/library/cgi.rst @@ -292,12 +292,12 @@ algorithms implemented in this module in other circumstances. passed to :func:`urlparse.parse_qs` unchanged. -.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]]) This function is deprecated in this module. Use :func:`urlparse.parse_qs` instead. It is maintained here only for backward compatibility. -.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]]) This function is deprecated in this module. Use :func:`urlparse.parse_qsl` instead. It is maintained here only for backward compatibility. diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index c88dd23..183da70 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -24,22 +24,28 @@ Functions provided: function for :keyword:`with` statement context managers, without needing to create a class or separate :meth:`__enter__` and :meth:`__exit__` methods. - A simple example (this is not recommended as a real way of generating HTML!):: + While many objects natively support use in with statements, sometimes a + resource needs to be managed that isn't a context manager in its own right, + and doesn't implement a ``close()`` method for use with ``contextlib.closing`` + + An abstract example would be the following to ensure correct resource + management:: from contextlib import contextmanager @contextmanager - def tag(name): - print "<%s>" % name - yield - print "</%s>" % name - - >>> with tag("h1"): - ... print "foo" - ... - <h1> - foo - </h1> + def managed_resource(*args, **kwds): + # Code to acquire resource, e.g.: + resource = acquire_resource(*args, **kwds) + try: + yield resource + finally: + # Code to release resource, e.g.: + release_resource(resource) + + >>> with managed_resource(timeout=3600) as resource: + ... # Resource is released at the end of this block, + ... # even if code in the block raises an exception The function being decorated must return a :term:`generator`-iterator when called. This iterator must yield exactly one value, which will be bound to diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index fedd370..ad6b716 100644 --- a/Doc/library/csv.rst +++ b/Doc/library/csv.rst @@ -453,8 +453,9 @@ read CSV files (assuming they support complex numbers at all). .. method:: csvwriter.writerows(rows) - Write all the *rows* parameters (a list of *row* objects as described above) to - the writer's file object, formatted according to the current dialect. + Write all elements in *rows* (an iterable of *row* objects as described + above) to the writer's file object, formatted according to the current + dialect. Writer objects have the following public attribute: diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b8d86e3..2d164b2 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -1566,7 +1566,7 @@ EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)). .. seealso:: - `pytz <https://pypi.python.org/pypi/pytz/>`_ + `pytz <https://pypi.org/project/pytz/>`_ The standard library has no :class:`tzinfo` instances, but there exists a third-party library which brings the *IANA timezone database* (also known as the Olson database) to Python: *pytz*. @@ -1594,7 +1594,9 @@ although not all objects support a :meth:`timetuple` method. Conversely, the :meth:`datetime.strptime` class method creates a :class:`.datetime` object from a string representing a date and time and a corresponding format string. ``datetime.strptime(date_string, format)`` is -equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``. +equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``, except +when the format includes sub-second components or timezone offset information, +which are supported in ``datetime.strptime`` but are discarded by ``time.strptime``. For :class:`.time` objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they're used anyway, ``1900`` @@ -1609,6 +1611,12 @@ calls the platform C library's :func:`strftime` function, and platform variations are common. To see the full set of format codes supported on your platform, consult the :manpage:`strftime(3)` documentation. +For the same reason, handling of format strings containing Unicode code points +that can't be represented in the charset of the current locale is also +platform-dependent. On some platforms such code points are preserved intact in +the output, while on others ``strftime`` may raise :exc:`UnicodeError` or return +an empty string instead. + The following is a list of all the format codes that the C standard (1989 version) requires, and these work on all platforms with a standard C implementation. Note that the 1999 version of the C standard added additional diff --git a/Doc/library/difflib.rst b/Doc/library/difflib.rst index c6bf3ef..7b6cce4 100644 --- a/Doc/library/difflib.rst +++ b/Doc/library/difflib.rst @@ -431,14 +431,15 @@ The :class:`SequenceMatcher` class has this constructor: .. method:: get_matching_blocks() - Return list of triples describing matching subsequences. Each triple is of - the form ``(i, j, n)``, and means that ``a[i:i+n] == b[j:j+n]``. The + Return list of triples describing non-overlapping matching subsequences. + Each triple is of the form ``(i, j, n)``, + and means that ``a[i:i+n] == b[j:j+n]``. The triples are monotonically increasing in *i* and *j*. The last triple is a dummy, and has the value ``(len(a), len(b), 0)``. It is the only triple with ``n == 0``. If ``(i, j, n)`` and ``(i', j', n')`` are adjacent triples in the list, and the second is not the last triple in - the list, then ``i+n != i'`` or ``j+n != j'``; in other words, adjacent + the list, then ``i+n < i'`` or ``j+n < j'``; in other words, adjacent triples always describe non-adjacent equal blocks. .. XXX Explain why a dummy is used! @@ -757,8 +758,10 @@ It is also contained in the Python source distribution, as # we're passing these as arguments to the diff function fromdate = time.ctime(os.stat(fromfile).st_mtime) todate = time.ctime(os.stat(tofile).st_mtime) - fromlines = open(fromfile, 'U').readlines() - tolines = open(tofile, 'U').readlines() + with open(fromfile, 'U') as f: + fromlines = f.readlines() + with open(tofile, 'U') as f: + tolines = f.readlines() if options.u: diff = difflib.unified_diff(fromlines, tolines, fromfile, tofile, diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 04b9b15..e773ab8 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -107,7 +107,7 @@ The :mod:`dis` module defines the following functions and constants: .. data:: hasconst - Sequence of bytecodes that have a constant parameter. + Sequence of bytecodes that access a constant. .. data:: hasfree @@ -796,21 +796,25 @@ the more significant byte last. .. opcode:: RAISE_VARARGS (argc) - Raises an exception. *argc* indicates the number of parameters to the raise + Raises an exception. *argc* indicates the number of arguments to the raise statement, ranging from 0 to 3. The handler will find the traceback as TOS2, the parameter as TOS1, and the exception as TOS. .. opcode:: CALL_FUNCTION (argc) - Calls a function. The low byte of *argc* indicates the number of positional - parameters, the high byte the number of keyword parameters. On the stack, the - opcode finds the keyword parameters first. For each keyword argument, the - value is on top of the key. Below the keyword parameters, the positional - parameters are on the stack, with the right-most parameter on top. Below the - parameters, the function object to call is on the stack. Pops all function - arguments, and the function itself off the stack, and pushes the return - value. + Calls a callable object. The low byte of *argc* indicates the number of + positional arguments, the high byte the number of keyword arguments. + The stack contains keyword arguments on top (if any), then the positional + arguments below that (if any), then the callable object to call below that. + Each keyword argument is represented with two values on the stack: + the argument's name, and its value, with the argument's value above the + name on the stack. + The positional arguments are pushed in the order that they are passed in + to the callable object, with the right-most positional argument on top. + ``CALL_FUNCTION`` pops all arguments and the callable object off the stack, + calls the callable object with those arguments, and pushes the return value + returned by the callable object. .. opcode:: MAKE_FUNCTION (argc) @@ -847,24 +851,53 @@ the more significant byte last. .. opcode:: CALL_FUNCTION_VAR (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the variable argument list, followed by - keyword and positional arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains an iterable object containing + additional positional arguments. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable object is called, the iterable object + is "unpacked" and its contents are appended to the positional + arguments passed in. + The iterable object is ignored when computing + the value of ``argc``. .. opcode:: CALL_FUNCTION_KW (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the keyword arguments dictionary, followed - by explicit keyword and positional arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains a mapping object containing additional keyword + arguments. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable is called, the mapping object at the top of the stack is + "unpacked" and its contents are appended to the keyword arguments passed in. + The mapping object at the top of the stack is ignored when computing + the value of ``argc``. .. opcode:: CALL_FUNCTION_VAR_KW (argc) - Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The - top element on the stack contains the keyword arguments dictionary, followed - by the variable-arguments tuple, followed by explicit keyword and positional - arguments. + Calls a callable object, similarly to :opcode:`CALL_FUNCTION_VAR` and + :opcode:`CALL_FUNCTION_KW`. + *argc* represents the number of keyword and positional + arguments, identically to :opcode:`CALL_FUNCTION`. + The top of the stack contains a mapping object, as per + :opcode:`CALL_FUNCTION_KW`. + Below that is an iterable object, as per + :opcode:`CALL_FUNCTION_VAR`. + Below that are keyword arguments (if any), positional arguments (if any) + and a callable object, identically to :opcode:`CALL_FUNCTION`. + Before the callable is called, the mapping object and iterable object + are each "unpacked" and their contents passed in as keyword and + positional arguments respectively, + identically to :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`. + The mapping object and iterable object are both ignored when computing + the value of ``argc``. .. opcode:: HAVE_ARGUMENT () diff --git a/Doc/library/distribution.rst b/Doc/library/distribution.rst index b560999..21dd18d 100644 --- a/Doc/library/distribution.rst +++ b/Doc/library/distribution.rst @@ -4,7 +4,7 @@ Software Packaging and Distribution These libraries help you with publishing and installing Python software. While these modules are designed to work in conjunction with the -`Python Package Index <https://pypi.python.org>`__, they can also be used +`Python Package Index <https://pypi.org>`__, they can also be used with a local index server, or without any index server at all. .. toctree:: diff --git a/Doc/library/email.rst b/Doc/library/email.rst index 879c38f..d9bd9ed 100644 --- a/Doc/library/email.rst +++ b/Doc/library/email.rst @@ -61,7 +61,7 @@ Contents of the :mod:`email` package documentation: email.charset.rst email.encoders.rst email.errors.rst - email.util.rst + email.utils.rst email.iterators.rst email-examples.rst diff --git a/Doc/library/email.util.rst b/Doc/library/email.utils.rst index 9b583c0..9b583c0 100644 --- a/Doc/library/email.util.rst +++ b/Doc/library/email.utils.rst diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index fe14656..8757c6c 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -439,7 +439,7 @@ The following exceptions are the exceptions that are actually raised. .. exception:: ValueError - Raised when a built-in operation or function receives an argument that has the + Raised when an operation or function receives an argument that has the right type but an inappropriate value, and the situation is not described by a more precise exception such as :exc:`IndexError`. diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst index 42bbf74..8618f5f 100644 --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -36,7 +36,7 @@ For example, ``'[?]'`` matches the character ``'?'``. Note that the filename separator (``'/'`` on Unix) is *not* special to this module. See module :mod:`glob` for pathname expansion (:mod:`glob` uses -:func:`fnmatch` to match pathname segments). Similarly, filenames starting with +:func:`.filter` to match pathname segments). Similarly, filenames starting with a period are not special for this module, and are matched by the ``*`` and ``?`` patterns. diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index f3e396b..aee14d5 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -76,9 +76,9 @@ The :mod:`functools` module defines the following functions: .. function:: partial(func[,*args][, **keywords]) - Return a new :class:`partial` object which when called will behave like *func* - called with the positional arguments *args* and keyword arguments *keywords*. If - more arguments are supplied to the call, they are appended to *args*. If + Return a new :ref:`partial object<partial-objects>` which when called will behave + like *func* called with the positional arguments *args* and keyword arguments *keywords*. + If more arguments are supplied to the call, they are appended to *args*. If additional keyword arguments are supplied, they extend and override *keywords*. Roughly equivalent to:: diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index a461e51..3848231 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -442,7 +442,7 @@ longer or disable the extension. Calltips ^^^^^^^^ -A calltip is shown when one types :kbd:`(` after the name of an *acccessible* +A calltip is shown when one types :kbd:`(` after the name of an *accessible* function. A name expression may include dots and subscripts. A calltip remains until it is clicked, the cursor is moved out of the argument area, or :kbd:`)` is typed. When the cursor is in the argument part of a definition, diff --git a/Doc/library/index.rst b/Doc/library/index.rst index 97cf3ea..31ca6df 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -30,7 +30,7 @@ optional components. In addition to the standard library, there is a growing collection of several thousand components (from individual programs and modules to packages and entire application development frameworks), available from -the `Python Package Index <https://pypi.python.org/pypi>`_. +the `Python Package Index <https://pypi.org>`_. .. toctree:: diff --git a/Doc/library/io.rst b/Doc/library/io.rst index b99324c..dcdd01c 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -724,7 +724,7 @@ Text I/O .. versionadded:: 2.7 - .. method:: read(n) + .. method:: read(n=-1) Read and return at most *n* characters from the stream as a single :class:`unicode`. If *n* is negative or ``None``, reads until EOF. @@ -809,7 +809,7 @@ Text I/O the given string. If *line_buffering* is ``True``, :meth:`flush` is implied when a call to - write contains a newline character. + write contains a newline character or a carriage return. :class:`TextIOWrapper` provides one attribute in addition to those of :class:`TextIOBase` and its parents: diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 0f568aa..09cae18 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -949,26 +949,26 @@ functions. +--------------+---------------------------------------------+ | Format | Description | +==============+=============================================+ - | ``filename`` | Specifies that a FileHandler be created, | + | *filename* | Specifies that a FileHandler be created, | | | using the specified filename, rather than a | | | StreamHandler. | +--------------+---------------------------------------------+ - | ``filemode`` | Specifies the mode to open the file, if | - | | filename is specified (if filemode is | - | | unspecified, it defaults to 'a'). | + | *filemode* | If *filename* is specified, open the file | + | | in this mode. Defaults to ``'a'``. | +--------------+---------------------------------------------+ - | ``format`` | Use the specified format string for the | + | *format* | Use the specified format string for the | | | handler. | +--------------+---------------------------------------------+ - | ``datefmt`` | Use the specified date/time format. | + | *datefmt* | Use the specified date/time format, as | + | | accepted by :func:`time.strftime`. | +--------------+---------------------------------------------+ - | ``level`` | Set the root logger level to the specified | - | | level. | + | *level* | Set the root logger level to the specified | + | | :ref:`level <levels>`. | +--------------+---------------------------------------------+ - | ``stream`` | Use the specified stream to initialize the | + | *stream* | Use the specified stream to initialize the | | | StreamHandler. Note that this argument is | - | | incompatible with 'filename' - if both are | - | | present, 'stream' is ignored. | + | | incompatible with *filename* - if both are | + | | present, *stream* is ignored. | +--------------+---------------------------------------------+ diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index a86eb13..c9fc733 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -68,7 +68,7 @@ memory but does not update the underlying file. *offset* may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. *offset* - defaults to 0. *offset* must be a multiple of the ALLOCATIONGRANULARITY. + defaults to 0. *offset* must be a multiple of the :const:`ALLOCATIONGRANULARITY`. .. class:: mmap(fileno, length[, flags[, prot[, access[, offset]]]]) @@ -97,8 +97,8 @@ memory but does not update the underlying file. *offset* may be specified as a non-negative integer offset. mmap references will be relative to the offset from the beginning of the file. *offset* - defaults to 0. *offset* must be a multiple of the PAGESIZE or - ALLOCATIONGRANULARITY. + defaults to 0. *offset* must be a multiple of :const:`ALLOCATIONGRANULARITY` + which is equal to :const:`PAGESIZE` on Unix systems. To ensure validity of the created memory mapping the file specified by the descriptor *fileno* is internally automatically synchronized @@ -171,7 +171,8 @@ memory but does not update the underlying file. use of this call there is no guarantee that changes are written back before the object is destroyed. If *offset* and *size* are specified, only changes to the given range of bytes will be flushed to disk; otherwise, the - whole extent of the mapping is flushed. + whole extent of the mapping is flushed. *offset* must be a multiple of the + :const:`PAGESIZE` or :const:`ALLOCATIONGRANULARITY`. **(Windows version)** A nonzero value returned indicates success; zero indicates failure. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 97a7b53..2d8660a 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -803,10 +803,13 @@ Miscellaneous Connection Objects ~~~~~~~~~~~~~~~~~~ +.. currentmodule:: None + Connection objects allow the sending and receiving of picklable objects or strings. They can be thought of as message oriented connected sockets. -Connection objects are usually created using :func:`Pipe` -- see also +Connection objects are usually created using +:func:`Pipe <multiprocessing.Pipe>` -- see also :ref:`multiprocessing-listeners-clients`. .. class:: Connection @@ -926,6 +929,8 @@ For example: Synchronization primitives ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. currentmodule:: multiprocessing + Generally synchronization primitives are not as necessary in a multiprocess program as they are in a multithreaded program. See the documentation for :mod:`threading` module. @@ -1943,8 +1948,7 @@ Listeners and Clients :synopsis: API for dealing with sockets. Usually message passing between processes is done using queues or by using -:class:`~multiprocessing.Connection` objects returned by -:func:`~multiprocessing.Pipe`. +:class:`Connection` objects returned by :func:`~multiprocessing.Pipe`. However, the :mod:`multiprocessing.connection` module allows some extra flexibility. It basically gives a high level message oriented API for dealing @@ -1972,7 +1976,7 @@ authentication* using the :mod:`hmac` module. .. function:: Client(address[, family[, authenticate[, authkey]]]) Attempt to set up a connection to the listener which is using address - *address*, returning a :class:`~multiprocessing.Connection`. + *address*, returning a :class:`Connection`. The type of the connection is determined by *family* argument, but this can generally be omitted since it can usually be inferred from the format of @@ -2028,8 +2032,8 @@ authentication* using the :mod:`hmac` module. .. method:: accept() Accept a connection on the bound socket or named pipe of the listener - object and return a :class:`~multiprocessing.Connection` object. If - authentication is attempted and fails, then + object and return a :class:`Connection` object. + If authentication is attempted and fails, then :exc:`~multiprocessing.AuthenticationError` is raised. .. method:: close() @@ -2050,11 +2054,24 @@ authentication* using the :mod:`hmac` module. unavailable then it is ``None``. -The module defines two exceptions: +The module defines the following exceptions: + +.. exception:: ProcessError + + The base class of all :mod:`multiprocessing` exceptions. + +.. exception:: BufferTooShort + + Exception raised by :meth:`Connection.recv_bytes_into()` when the supplied + buffer object is too small for the message read. .. exception:: AuthenticationError - Exception raised when there is an authentication error. + Raised when there is an authentication error. + +.. exception:: TimeoutError + + Raised by methods with a timeout when the timeout expires. **Examples** @@ -2126,7 +2143,7 @@ an ``'AF_PIPE'`` address rather than an ``'AF_UNIX'`` address. Authentication keys ~~~~~~~~~~~~~~~~~~~ -When one uses :meth:`Connection.recv <multiprocessing.Connection.recv>`, the +When one uses :meth:`Connection.recv`, the data received is automatically unpickled. Unfortunately unpickling data from an untrusted source is a security risk. Therefore :class:`Listener` and :func:`Client` use the :mod:`hmac` module diff --git a/Doc/library/optparse.rst b/Doc/library/optparse.rst index 4af75a1..627eb7d 100644 --- a/Doc/library/optparse.rst +++ b/Doc/library/optparse.rst @@ -1679,7 +1679,7 @@ The callback function should raise :exc:`OptionValueError` if there are any problems with the option or its argument(s). :mod:`optparse` catches this and terminates the program, printing the error message you supply to stderr. Your message should be clear, concise, accurate, and mention the option at fault. -Otherwise, the user will have a hard time figuring out what he did wrong. +Otherwise, the user will have a hard time figuring out what they did wrong. .. _optparse-callback-example-1: diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 9f64095..3d0743b 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -270,6 +270,10 @@ Unix Platforms parameters. ``id`` is the item in parentheses after the version number. It is usually the version codename. + .. note:: + This function is deprecated since Python 3.5 and removed in Python 3.8. + See alternative like the `distro <https://pypi.org/project/distro>`_ package. + .. versionadded:: 2.6 .. function:: libc_ver(executable=sys.executable, lib='', version='', chunksize=2048) diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index ffa27d4..3f09b21 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -234,4 +234,3 @@ parameters. ['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'], ['cccccccccccccccccccc', 'dddddddddddddddddddd']] - diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst index 210e99c..0926373 100644 --- a/Doc/library/profile.rst +++ b/Doc/library/profile.rst @@ -333,11 +333,12 @@ Analysis of the profiler data is done using the :class:`~pstats.Stats` class. corresponding version of :mod:`profile` or :mod:`cProfile`. To be specific, there is *no* file compatibility guaranteed with future versions of this profiler, and there is no compatibility with files produced by other - profilers. If several files are provided, all the statistics for identical - functions will be coalesced, so that an overall view of several processes can - be considered in a single report. If additional files need to be combined - with data in an existing :class:`~pstats.Stats` object, the - :meth:`~pstats.Stats.add` method can be used. + profilers, or the same profiler run on a different operating system. If + several files are provided, all the statistics for identical functions will + be coalesced, so that an overall view of several processes can be considered + in a single report. If additional files need to be combined with data in an + existing :class:`~pstats.Stats` object, the :meth:`~pstats.Stats.add` method + can be used. Instead of reading the profile data from a file, a :class:`cProfile.Profile` or :class:`profile.Profile` object can be used as the profile data source. diff --git a/Doc/library/re.rst b/Doc/library/re.rst index c424230..c708a29 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -35,7 +35,7 @@ fine-tuning parameters. .. seealso:: - The third-party `regex <https://pypi.python.org/pypi/regex/>`_ module, + The third-party `regex <https://pypi.org/project/regex/>`_ module, which has an API compatible with the standard library :mod:`re` module, but offers additional functionality and a more thorough Unicode support. @@ -1256,8 +1256,8 @@ Finding all Adverbs ^^^^^^^^^^^^^^^^^^^ :func:`findall` matches *all* occurrences of a pattern, not just the first -one as :func:`search` does. For example, if one was a writer and wanted to -find all of the adverbs in some text, he or she might use :func:`findall` in +one as :func:`search` does. For example, if a writer wanted to +find all of the adverbs in some text, they might use :func:`findall` in the following manner: >>> text = "He was carefully disguised but captured quickly by police." @@ -1271,8 +1271,8 @@ Finding all Adverbs and their Positions If one wants more information about all matches of a pattern than the matched text, :func:`finditer` is useful as it provides instances of :class:`MatchObject` instead of strings. Continuing with the previous example, -if one was a writer who wanted to find all of the adverbs *and their positions* -in some text, he or she would use :func:`finditer` in the following manner: +if a writer wanted to find all of the adverbs *and their positions* +in some text, they would use :func:`finditer` in the following manner: >>> text = "He was carefully disguised but captured quickly by police." >>> for m in re.finditer(r"\w+ly", text): diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index 6bd8f05..7e9af1a 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -82,9 +82,11 @@ Directory and files operations .. function:: copy2(src, dst) - Similar to :func:`shutil.copy`, but metadata is copied as well -- in fact, - this is just :func:`shutil.copy` followed by :func:`copystat`. This is - similar to the Unix command :program:`cp -p`. + Identical to :func:`~shutil.copy` except that :func:`copy2` + also attempts to preserve file metadata. + + :func:`copy2` uses :func:`copystat` to copy the file metadata. + Please see :func:`copystat` for more information. .. function:: ignore_patterns(\*patterns) diff --git a/Doc/library/simplehttpserver.rst b/Doc/library/simplehttpserver.rst index 2e7e97a..df8699e 100644 --- a/Doc/library/simplehttpserver.rst +++ b/Doc/library/simplehttpserver.rst @@ -11,6 +11,10 @@ Python 3. The :term:`2to3` tool will automatically adapt imports when converting your sources to Python 3. +.. warning:: + + mod:`SimpleHTTServer` is not recommended for production. It only implements + basic security checks. The :mod:`SimpleHTTPServer` module defines a single class, :class:`SimpleHTTPRequestHandler`, which is interface-compatible with diff --git a/Doc/library/site.rst b/Doc/library/site.rst index ff7195d..1c2d63e 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -206,7 +206,7 @@ If it is called without arguments, it will print the contents of If both options are given, user base and user site will be printed (always in this order), separated by :data:`os.pathsep`. -If any option is given, the script will exit with one of these values: ``O`` if +If any option is given, the script will exit with one of these values: ``0`` if the user site-packages directory is enabled, ``1`` if it was disabled by the user, ``2`` if it is disabled for security reasons or by an administrator, and a value greater than 2 if there is an error. diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index b6e7689..2cc519e 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -36,7 +36,7 @@ Protocol) and :rfc:`1869` (SMTP Service Extensions). is raised. For normal use, you should only require the initialization/connect, - :meth:`sendmail`, and :meth:`~smtplib.quit` methods. + :meth:`sendmail`, and :meth:`SMTP.quit` methods. An example is included below. .. versionchanged:: 2.6 diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index bd5dd14..ce53e84 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -206,8 +206,8 @@ Module functions and constants Registers a callable to convert a bytestring from the database into a custom Python type. The callable will be invoked for all database values that are of the type *typename*. Confer the parameter *detect_types* of the :func:`connect` - function for how the type detection works. Note that the case of *typename* and - the name of the type in your query must match! + function for how the type detection works. Note that *typename* and the name of + the type in your query are matched in case-insensitive manner. .. function:: register_adapter(type, callable) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 89b9ff3..8e90492 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -24,6 +24,9 @@ sockets, both client-side and server-side. This module uses the OpenSSL library. It is available on all modern Unix systems, Windows, Mac OS X, and probably additional platforms, as long as OpenSSL is installed on that platform. +.. versionchanged:: 2.7.13 + Updated to support linking with OpenSSL 1.1.0 + .. note:: Some behavior may be platform dependent, since calls are made to the @@ -211,7 +214,7 @@ instead. The *ciphers* parameter sets the available ciphers for this SSL object. It should be a string in the `OpenSSL cipher list format - <https://wiki.openssl.org/index.php/Manual:Ciphers(1)#CIPHER_LIST_FORMAT>`_. + <https://www.openssl.org/docs/manmaster/man1/ciphers.html>`_. The parameter ``do_handshake_on_connect`` specifies whether to do the SSL handshake automatically after doing a :meth:`socket.connect`, or whether the @@ -291,11 +294,6 @@ purposes. 3DES was dropped from the default cipher string. - .. versionchanged:: 2.7.15 - - TLS 1.3 cipher suites TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, - and TLS_CHACHA20_POLY1305_SHA256 were added to the default cipher string. - .. function:: _https_verify_certificates(enable=True) Specifies whether or not server certificates are verified when creating @@ -744,6 +742,15 @@ Constants .. versionadded:: 2.7.9 +.. data:: OP_ENABLE_MIDDLEBOX_COMPAT + + Send dummy Change Cipher Spec (CCS) messages in TLS 1.3 handshake to make + a TLS 1.3 connection look more like a TLS 1.2 connection. + + This option is only available with OpenSSL 1.1.1 and later. + + .. versionadded:: 2.7.16 + .. data:: OP_NO_COMPRESSION Disable compression on the SSL channel. This is useful if the application @@ -1060,6 +1067,17 @@ to speed up repeated connections from the same clients. :func:`create_default_context` lets the :mod:`ssl` module choose security settings for a given purpose. + .. versionchanged:: 2.7.16 + + The context is created with secure default values. The options + :data:`OP_NO_COMPRESSION`, :data:`OP_CIPHER_SERVER_PREFERENCE`, + :data:`OP_SINGLE_DH_USE`, :data:`OP_SINGLE_ECDH_USE`, + :data:`OP_NO_SSLv2` (except for :data:`PROTOCOL_SSLv2`), + and :data:`OP_NO_SSLv3` (except for :data:`PROTOCOL_SSLv3`) are + set by default. The initial cipher suite list contains only ``HIGH`` + ciphers, no ``NULL`` ciphers and no ``MD5`` ciphers (except for + :data:`PROTOCOL_SSLv2`). + :class:`SSLContext` objects have the following methods and attributes: @@ -1167,7 +1185,7 @@ to speed up repeated connections from the same clients. Set the available ciphers for sockets created with this context. It should be a string in the `OpenSSL cipher list format - <https://wiki.openssl.org/index.php/Manual:Ciphers(1)#CIPHER_LIST_FORMAT>`_. + <https://www.openssl.org/docs/manmaster/man1/ciphers.html>`_. If no cipher can be selected (because compile-time options or other configuration forbids use of all the specified ciphers), an :class:`SSLError` will be raised. @@ -1176,6 +1194,9 @@ to speed up repeated connections from the same clients. when connected, the :meth:`SSLSocket.cipher` method of SSL sockets will give the currently selected cipher. + OpenSSL 1.1.1 has TLS 1.3 cipher suites enabled by default. The suites + cannot be disabled with :meth:`~SSLContext.set_ciphers`. + .. method:: SSLContext.set_alpn_protocols(protocols) Specify which protocols the socket should advertise during the SSL/TLS @@ -1392,7 +1413,7 @@ message with one of the parts, you can decrypt it with the other part, and A certificate contains information about two principals. It contains the name of a *subject*, and the subject's public key. It also contains a statement by a -second principal, the *issuer*, that the subject is who he claims to be, and +second principal, the *issuer*, that the subject is who they claim to be, and that this is indeed the subject's public key. The issuer's statement is signed with the issuer's private key, which only the issuer knows. However, anyone can verify the issuer's statement by finding the issuer's public key, decrypting the @@ -1586,7 +1607,7 @@ Visual inspection shows that the certificate does identify the desired service (('commonName', 'www.python.org'),)), 'subjectAltName': (('DNS', 'www.python.org'), ('DNS', 'python.org'), - ('DNS', 'pypi.python.org'), + ('DNS', 'pypi.org'), ('DNS', 'docs.python.org'), ('DNS', 'testpypi.python.org'), ('DNS', 'bugs.python.org'), diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e16bd77..ff68738 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1381,7 +1381,7 @@ string functions based on regular expressions. .. method:: str.upper() Return a copy of the string with all the cased characters [4]_ converted to - uppercase. Note that ``str.upper().isupper()`` might be ``False`` if ``s`` + uppercase. Note that ``s.upper().isupper()`` might be ``False`` if ``s`` contains uncased characters or if the Unicode category of the resulting character(s) is not "Lu" (Letter, uppercase), but e.g. "Lt" (Letter, titlecase). diff --git a/Doc/library/string.rst b/Doc/library/string.rst index c2af446..7eedc86 100644 --- a/Doc/library/string.rst +++ b/Doc/library/string.rst @@ -257,8 +257,9 @@ attribute using :func:`getattr`, while an expression of the form ``'[index]'`` does an index lookup using :func:`__getitem__`. .. versionchanged:: 2.7 - The positional argument specifiers can be omitted, so ``'{} {}'`` is - equivalent to ``'{0} {1}'``. + The positional argument specifiers can be omitted for :meth:`str.format` and + :meth:`unicode.format`, so ``'{} {}'`` is equivalent to ``'{0} {1}'``, + ``u'{} {}'`` is equivalent to ``u'{0} {1}'``. Some simple format string examples:: @@ -463,10 +464,10 @@ The available presentation types for floating point and decimal values are: | ``'E'`` | Exponent notation. Same as ``'e'`` except it uses an | | | upper case 'E' as the separator character. | +---------+----------------------------------------------------------+ - | ``'f'`` | Fixed point. Displays the number as a fixed-point | - | | number. The default precision is ``6``. | + | ``'f'`` | Fixed-point notation. Displays the number as a | + | | fixed-point number. The default precision is ``6``. | +---------+----------------------------------------------------------+ - | ``'F'`` | Fixed point. Same as ``'f'``. | + | ``'F'`` | Fixed point notation. Same as ``'f'``. | +---------+----------------------------------------------------------+ | ``'g'`` | General format. For a given precision ``p >= 1``, | | | this rounds the number to ``p`` significant digits and | @@ -521,7 +522,7 @@ addition of the ``{}`` and with ``:`` used instead of ``%``. For example, ``'%03.2f'`` can be translated to ``'{:03.2f}'``. The new format syntax also supports new and different options, shown in the -follow examples. +following examples. Accessing arguments by position:: @@ -700,7 +701,7 @@ these rules. The methods of :class:`Template` are: simply return ``$`` instead of raising :exc:`ValueError`. While other exceptions may still occur, this method is called "safe" - because substitutions always tries to return a usable string instead of + because it always tries to return a usable string instead of raising an exception. In another sense, :meth:`safe_substitute` may be anything other than safe, since it will silently ignore malformed templates containing dangling delimiters, unmatched braces, or diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 284cf44..53a0161 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -32,7 +32,7 @@ functions can be found in the subprocess-replacements_ section. :pep:`324` -- PEP proposing the subprocess module -.. _subprocess32: https://pypi.python.org/pypi/subprocess32/ +.. _subprocess32: https://pypi.org/project/subprocess32/ Using the :mod:`subprocess` Module ---------------------------------- diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst index e8fc09e..7655c60 100644 --- a/Doc/library/sysconfig.rst +++ b/Doc/library/sysconfig.rst @@ -83,7 +83,7 @@ Python currently supports seven schemes: - *nt*: scheme for NT platforms like Windows. - *nt_user*: scheme for NT platforms, when the *user* option is used. - *os2*: scheme for OS/2 platforms. -- *os2_home*: scheme for OS/2 patforms, when the *user* option is used. +- *os2_home*: scheme for OS/2 platforms, when the *user* option is used. Each scheme is itself composed of a series of paths and each path has a unique identifier. Python currently uses eight paths: @@ -188,7 +188,7 @@ Other functions Windows will return one of: - - win-amd64 (64bit Windows on AMD64 (aka x86_64, Intel64, EM64T, etc) + - win-amd64 (64bit Windows on AMD64, aka x86_64, Intel64, and EM64T) - win-ia64 (64bit Windows on Itanium) - win32 (all others - specifically, sys.platform is returned) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index c819bf5..5789e5e 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -37,6 +37,10 @@ Some facts and figures: character devices and block devices and is able to acquire and restore file information like timestamp, access permissions and owner. +.. note:: + Handling of multi-stream bzip2 files is not supported. Modules such as + `bz2file <https://github.com/nvawda/bz2file>`_ let you overcome this. + .. function:: open(name=None, mode='r', fileobj=None, bufsize=10240, \*\*kwargs) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index b2a9253..48a01db 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -236,7 +236,7 @@ The module defines the following functions and data items: argument. If *t* is not provided, the current time as returned by :func:`localtime` is used. *format* must be a string. :exc:`ValueError` is raised if any field in *t* is outside of the allowed range. :func:`strftime` - returns a locale depedent byte string; the result may be converted to unicode + returns a locale dependent byte string; the result may be converted to unicode by doing ``strftime(<myformat>).decode(locale.getlocale()[1])``. .. versionchanged:: 2.1 diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index ce5e63a..3356e4e 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -11,6 +11,11 @@ the Tk GUI toolkit. Both Tk and :mod:`Tkinter` are available on most Unix platforms, as well as on Windows systems. (Tk itself is not part of Python; it is maintained at ActiveState.) +Running ``python -m Tkinter`` from the command line should open a window +demonstrating a simple Tk interface, letting you know that :mod:`Tkinter` is +properly installed on your system, and also showing what version of Tcl/Tk is +installed, so you can read the Tcl/Tk documentation specific to that version. + .. note:: :mod:`Tkinter` has been renamed to :mod:`tkinter` in Python 3. The @@ -19,6 +24,8 @@ is maintained at ActiveState.) .. seealso:: + Tkinter documentation: + `Python Tkinter Resources <https://wiki.python.org/moin/TkInter>`_ The Python Tkinter Topic Guide provides a great deal of information on using Tk from Python and links to other sources of information on Tk. @@ -32,17 +39,32 @@ is maintained at ActiveState.) `Tkinter docs from effbot <http://effbot.org/tkinterbook/>`_ Online reference for tkinter supported by effbot.org. - `Tcl/Tk manual <https://www.tcl.tk/man/tcl8.5/>`_ - Official manual for the latest tcl/tk version. - - `Programming Python <http://learning-python.com/books/about-pp4e.html>`_ + `Programming Python <http://learning-python.com/about-pp4e.html>`_ Book by Mark Lutz, has excellent coverage of Tkinter. - `Modern Tkinter for Busy Python Developers <http://www.amazon.com/Modern-Tkinter-Python-Developers-ebook/dp/B0071QDNLO/>`_ + `Modern Tkinter for Busy Python Developers <https://www.amazon.com/Modern-Tkinter-Python-Developers-ebook/dp/B0071QDNLO/>`_ Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter. `Python and Tkinter Programming <https://www.manning.com/books/python-and-tkinter-programming>`_ - The book by John Grayson (ISBN 1-884777-81-3). + Book by John Grayson (ISBN 1-884777-81-3). + + Tcl/Tk documentation: + + `Tk commands <https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm>`_ + Most commands are available as :mod:`Tkinter` or :mod:`Tkinter.ttk` classes. + Change '8.6' to match the version of your Tcl/Tk installation. + + `Tcl/Tk recent man pages <https://www.tcl.tk/doc/>`_ + Recent Tcl/Tk manuals on www.tcl.tk. + + `ActiveState Tcl Home Page <http://tcl.activestate.com/>`_ + The Tk/Tcl development is largely taking place at ActiveState. + + `Tcl and the Tk Toolkit <https://www.amazon.com/exec/obidos/ASIN/020163337X>`_ + Book by John Ousterhout, the inventor of Tcl. + + `Practical Programming in Tcl and Tk <http://www.beedub.com/book/>`_ + Brent Welch's encyclopedic book. Tkinter Modules @@ -182,18 +204,6 @@ documentation that exists. Here are some hints: when nothing else makes sense. -.. seealso:: - - `ActiveState Tcl Home Page <http://tcl.activestate.com/>`_ - The Tk/Tcl development is largely taking place at ActiveState. - - `Tcl and the Tk Toolkit <http://www.amazon.com/exec/obidos/ASIN/020163337X>`_ - The book by John Ousterhout, the inventor of Tcl. - - `Practical Programming in Tcl and Tk <http://www.beedub.com/book/>`_ - Brent Welch's encyclopedic book. - - A Simple Hello World Program ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -801,12 +811,13 @@ Menu indexes (menu.invoke(), menu.entryconfig(), etc.) Images ^^^^^^ -Bitmap/Pixelmap images can be created through the subclasses of -:class:`Tkinter.Image`: +Images of different formats can be created through the corresponding subclass +of :class:`Tkinter.Image`: -* :class:`BitmapImage` can be used for X11 bitmap data. +* :class:`BitmapImage` for images in XBM format. -* :class:`PhotoImage` can be used for GIF and PPM/PGM color bitmaps. +* :class:`PhotoImage` for images in PGM, PPM, GIF and PNG formats. The latter + is supported starting with Tk 8.6. Either type of image is created through either the ``file`` or the ``data`` option (other options are available as well). @@ -817,6 +828,10 @@ reference to the image. When the last Python reference to the image object is deleted, the image data is deleted as well, and Tk will display an empty box wherever the image was used. +.. seealso:: + + The `Pillow <http://python-pillow.org/>`_ package adds support for + formats such as BMP, JPEG, TIFF, and WebP, among others. .. _tkinter-file-handlers: diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 1c8a967..63c0bee 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -1229,7 +1229,7 @@ Using events :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas - :param num: number of the mouse-button, defaults to 1 (left mouse button) + :param btn: number of the mouse-button, defaults to 1 (left mouse button) :param add: ``True`` or ``False`` -- if ``True``, a new binding will be added, otherwise it will replace a former binding @@ -1250,7 +1250,7 @@ Using events :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas - :param num: number of the mouse-button, defaults to 1 (left mouse button) + :param btn: number of the mouse-button, defaults to 1 (left mouse button) :param add: ``True`` or ``False`` -- if ``True``, a new binding will be added, otherwise it will replace a former binding @@ -1274,7 +1274,7 @@ Using events :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas - :param num: number of the mouse-button, defaults to 1 (left mouse button) + :param btn: number of the mouse-button, defaults to 1 (left mouse button) :param add: ``True`` or ``False`` -- if ``True``, a new binding will be added, otherwise it will replace a former binding @@ -1656,7 +1656,7 @@ Using screen events :param fun: a function with two arguments which will be called with the coordinates of the clicked point on the canvas - :param num: number of the mouse-button, defaults to 1 (left mouse button) + :param btn: number of the mouse-button, defaults to 1 (left mouse button) :param add: ``True`` or ``False`` -- if ``True``, a new binding will be added, otherwise it will replace a former binding diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index b36126e..2638d6c 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -78,7 +78,7 @@ need to derive from a specific class. Module :mod:`doctest` Another test-support module with a very different flavor. - `unittest2: A backport of new unittest features for Python 2.4-2.6 <https://pypi.python.org/pypi/unittest2>`_ + `unittest2: A backport of new unittest features for Python 2.4-2.6 <https://pypi.org/project/unittest2>`_ Many new features were added to unittest in Python 2.7, including test discovery. unittest2 allows you to use these features with earlier versions of Python. @@ -87,7 +87,7 @@ need to derive from a specific class. Kent Beck's original paper on testing frameworks using the pattern shared by :mod:`unittest`. - `Nose <https://nose.readthedocs.org/en/latest/>`_ and `py.test <http://pytest.org>`_ + `Nose <https://nose.readthedocs.io/>`_ and `pytest <https://docs.pytest.org/>`_ Third-party unittest frameworks with a lighter-weight syntax for writing tests. For example, ``assert func(10) == 42``. @@ -730,7 +730,7 @@ Test cases .. method:: setUpClass() - A class method called before tests in an individual class run. + A class method called before tests in an individual class are run. ``setUpClass`` is called with the class as the only argument and must be decorated as a :func:`classmethod`:: diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index 2a5ea71..084d567 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -147,14 +147,15 @@ High-level interface :envvar:`no_proxy` environment variable. .. versionchanged:: 2.7.9 - The *context* parameter was added. All the neccessary certificate and hostname checks are done by default. + 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 of :func:`urllib2.urlopen`. -.. function:: urlretrieve(url[, filename[, reporthook[, data]]]) +.. function:: urlretrieve(url[, filename[, reporthook[, data[, context]]]]) Copy a network object denoted by a URL to a local file, if necessary. If the URL points to a local file, or a valid cached copy of the object exists, the object @@ -166,9 +167,9 @@ High-level interface The second argument, if present, specifies the file location to copy to (if absent, the location will be a tempfile with a generated name). The third - argument, if present, is a hook function that will be called once on + argument, if present, is a callable that will be called once on establishment of the network connection and once after each block read - thereafter. The hook will be passed three arguments; a count of blocks + thereafter. The callable will be passed three arguments; a count of blocks transferred so far, a block size in bytes, and the total size of the file. The third argument may be ``-1`` on older FTP servers which do not return a file size in response to a retrieval request. @@ -179,6 +180,10 @@ High-level interface :mimetype:`application/x-www-form-urlencoded` format; see the :func:`urlencode` function below. + The *context* parameter may be set to a :class:`ssl.SSLContext` instance to + configure the SSL settings that are used if :func:`urlretrieve` makes a HTTPS + connection. + .. versionchanged:: 2.5 :func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that the amount of data available was less than the expected amount (which is the @@ -196,6 +201,10 @@ High-level interface the size of the data it has downloaded, and just returns it. In this case you just have to assume that the download was successful. + .. versionchanged:: 2.7.9 + The *context* parameter was added. All the neccessary certificate and hostname + checks are done by default. + .. data:: _urlopener @@ -349,6 +358,10 @@ URL Opener objects :class:`URLopener` objects will raise an :exc:`IOError` exception if the server returns an error code. + .. versionchanged:: 2.7.9 + The *context* parameter was added. All the neccessary certificate and hostname + checks are done by default. + .. method:: open(fullurl[, data]) Open *fullurl* using the appropriate protocol. This method sets up cache and diff --git a/Doc/library/urlparse.rst b/Doc/library/urlparse.rst index b933dda..22249da 100644 --- a/Doc/library/urlparse.rst +++ b/Doc/library/urlparse.rst @@ -126,7 +126,7 @@ The :mod:`urlparse` module defines the following functions: Added IPv6 URL parsing capabilities. -.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]]) Parse a query string given as a string argument (data of type :mimetype:`application/x-www-form-urlencoded`). Data are returned as a @@ -143,14 +143,20 @@ The :mod:`urlparse` module defines the following functions: parsing errors. If false (the default), errors are silently ignored. If true, errors raise a :exc:`ValueError` exception. + The optional argument *max_num_fields* is the maximum number of fields to + read. If set, then throws a :exc:`ValueError` if there are more than + *max_num_fields* fields read. + Use the :func:`urllib.urlencode` function to convert such dictionaries into query strings. .. versionadded:: 2.6 Copied from the :mod:`cgi` module. + .. versionchanged:: 2.7.16 + Added *max_num_fields* parameter. -.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing]]) +.. function:: parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]]) Parse a query string given as a string argument (data of type :mimetype:`application/x-www-form-urlencoded`). Data are returned as a list of @@ -166,12 +172,18 @@ The :mod:`urlparse` module defines the following functions: parsing errors. If false (the default), errors are silently ignored. If true, errors raise a :exc:`ValueError` exception. + The optional argument *max_num_fields* is the maximum number of fields to + read. If set, then throws a :exc:`ValueError` if there are more than + *max_num_fields* fields read. + Use the :func:`urllib.urlencode` function to convert such lists of pairs into query strings. .. versionadded:: 2.6 Copied from the :mod:`cgi` module. + .. versionchanged:: 2.7.16 + Added *max_num_fields* parameter. .. function:: urlunparse(parts) diff --git a/Doc/library/uuid.rst b/Doc/library/uuid.rst index bc69b5f..d2808cd 100644 --- a/Doc/library/uuid.rst +++ b/Doc/library/uuid.rst @@ -23,12 +23,13 @@ random UUID. .. class:: UUID([hex[, bytes[, bytes_le[, fields[, int[, version]]]]]]) Create a UUID from either a string of 32 hexadecimal digits, a string of 16 - bytes as the *bytes* argument, a string of 16 bytes in little-endian order as - the *bytes_le* argument, a tuple of six integers (32-bit *time_low*, 16-bit - *time_mid*, 16-bit *time_hi_version*, 8-bit *clock_seq_hi_variant*, 8-bit - *clock_seq_low*, 48-bit *node*) as the *fields* argument, or a single 128-bit - integer as the *int* argument. When a string of hex digits is given, curly - braces, hyphens, and a URN prefix are all optional. For example, these + bytes in big-endian order as the *bytes* argument, a string of 16 bytes in + little-endian order as the *bytes_le* argument, a tuple of six integers + (32-bit *time_low*, 16-bit *time_mid*, 16-bit *time_hi_version*, + 8-bit *clock_seq_hi_variant*, 8-bit *clock_seq_low*, 48-bit *node*) as the + *fields* argument, or a single 128-bit integer as the *int* argument. + When a string of hex digits is given, curly braces, hyphens, + and a URN prefix are all optional. For example, these expressions all yield the same UUID:: UUID('{12345678-1234-5678-1234-567812345678}') diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index f91259a..2df5bdd 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -169,7 +169,7 @@ module documentation. This section lists the differences between the API and the *encoding* argument was introduced; see :meth:`writexml`. -.. method:: Node.toprettyxml([indent=""[, newl=""[, encoding=""]]]) +.. method:: Node.toprettyxml(indent="\\t", newl="\\n", encoding=None) Return a pretty-printed version of the document. *indent* specifies the indentation string and defaults to a tabulator; *newl* specifies the string diff --git a/Doc/library/xml.rst b/Doc/library/xml.rst index a8f20cd..b107c29 100644 --- a/Doc/library/xml.rst +++ b/Doc/library/xml.rst @@ -129,8 +129,8 @@ break backward compatibility. After all inline DTD and entity expansion are well-defined XML features. -.. _defusedxml: https://pypi.python.org/pypi/defusedxml/ -.. _defusedexpat: https://pypi.python.org/pypi/defusedexpat/ +.. _defusedxml: https://pypi.org/project/defusedxml/ +.. _defusedexpat: https://pypi.org/project/defusedexpat/ .. _Billion Laughs: https://en.wikipedia.org/wiki/Billion_laughs .. _ZIP bomb: https://en.wikipedia.org/wiki/Zip_bomb .. _DTD: https://en.wikipedia.org/wiki/Document_type_definition diff --git a/Doc/library/xml.sax.rst b/Doc/library/xml.sax.rst index 25e4fa9..9ec9696 100644 --- a/Doc/library/xml.sax.rst +++ b/Doc/library/xml.sax.rst @@ -31,7 +31,7 @@ The convenience functions are: Create and return a SAX :class:`~xml.sax.xmlreader.XMLReader` object. The first parser found will - be used. If *parser_list* is provided, it must be a sequence of strings which + be used. If *parser_list* is provided, it must be a list of strings which name modules that have a function named :func:`create_parser`. Modules listed in *parser_list* will be used before modules in the default list of parsers. diff --git a/Doc/license.rst b/Doc/license.rst index f33495a..eded4a9 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-2018 Python Software Foundation; All Rights + copyright, i.e., "Copyright © 2001-2019 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 d8e8df0..2e199f1 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -5,23 +5,37 @@ pushd %~dp0 set this=%~n0
-call ..\PCBuild\find_python.bat %PYTHON%
-if not defined SPHINXBUILD if defined PYTHON (
+call ..\PCbuild\find_python.bat %PYTHON%
+
+if not defined PYTHON set PYTHON=py
+
+if not defined SPHINXBUILD (
%PYTHON% -c "import sphinx" > nul 2> nul
if errorlevel 1 (
echo Installing sphinx with %PYTHON%
%PYTHON% -m pip install sphinx
if errorlevel 1 exit /B
)
- set SPHINXBUILD=%PYTHON% -c "import sphinx, sys; sys.argv[0] = 'sphinx-build'; sphinx.main()"
+ set SPHINXBUILD=%PYTHON% -c "import sphinx, sys; sys.argv[0] = 'sphinx-build'; sys.exit(sphinx.main())"
)
-if not defined PYTHON set PYTHON=py
-if not defined SPHINXBUILD set SPHINXBUILD=sphinx-build
+if "%1" NEQ "htmlhelp" goto :skiphhcsearch
+if exist "%HTMLHELP%" goto :skiphhcsearch
-if DEFINED ProgramFiles(x86) set _PRGMFLS=%ProgramFiles(x86)%
-if NOT DEFINED ProgramFiles(x86) set _PRGMFLS=%ProgramFiles%
-if "%HTMLHELP%" EQU "" set HTMLHELP=%_PRGMFLS%\HTML Help Workshop\hhc.exe
+rem Search for HHC in likely places
+set HTMLHELP=
+where hhc /q && set HTMLHELP=hhc && goto :skiphhcsearch
+where /R ..\externals hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" where /R "%ProgramFiles(x86)%" hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" where /R "%ProgramFiles%" hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" (
+ echo.
+ echo.The HTML Help Workshop was not found. Set the HTMLHELP variable
+ echo.to the path to hhc.exe or download and install it from
+ echo.http://msdn.microsoft.com/en-us/library/ms669985
+ exit /B 1
+)
+:skiphhcsearch
if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/extensions/patchlevel.py`) do set DISTVERSION=%%v
@@ -33,11 +47,11 @@ if "%1" EQU "help" goto help if "%1" EQU "check" goto check
if "%1" EQU "serve" goto serve
if "%1" == "clean" (
- rmdir /q /s %BUILDDIR%
+ rmdir /q /s "%BUILDDIR%"
goto end
)
-%SPHINXBUILD% 2> nul
+%SPHINXBUILD% >nul 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
@@ -47,7 +61,8 @@ if errorlevel 9009 ( echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
- goto end
+ popd
+ exit /B 1
)
rem Targets that do require sphinx-build and have their own label
@@ -81,22 +96,14 @@ echo.be passed by setting the SPHINXOPTS environment variable. goto end
:build
+if not exist "%BUILDDIR%" mkdir "%BUILDDIR%"
if NOT "%PAPER%" == "" (
set SPHINXOPTS=-D latex_elements.papersize=%PAPER% %SPHINXOPTS%
)
-cmd /C "%SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%*"
+cmd /S /C "%SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . "%BUILDDIR%\%1" %2 %3 %4 %5 %6 %7 %8 %9"
if "%1" EQU "htmlhelp" (
- if not exist "%HTMLHELP%" (
- echo.
- echo.The HTML Help Workshop was not found. Set the HTMLHELP variable
- echo.to the path to hhc.exe or download and install it from
- echo.http://msdn.microsoft.com/en-us/library/ms669985
- rem Set errorlevel to 1 and exit
- cmd /C exit /b 1
- goto end
- )
- cmd /C "%HTMLHELP%" build\htmlhelp\python%DISTVERSION:.=%.hhp
+ "%HTMLHELP%" "%BUILDDIR%\htmlhelp\python%DISTVERSION:.=%.hhp"
rem hhc.exe seems to always exit with code 1, reset to 0 for less than 2
if not errorlevel 2 cmd /C exit /b 0
)
@@ -116,19 +123,19 @@ if NOT "%2" EQU "" ( )
cmd /C %this% html
-if EXIST %BUILDDIR%\html\index.html (
- echo.Opening %BUILDDIR%\html\index.html in the default web browser...
- start %BUILDDIR%\html\index.html
+if EXIST "%BUILDDIR%\html\index.html" (
+ echo.Opening "%BUILDDIR%\html\index.html" in the default web browser...
+ start "" "%BUILDDIR%\html\index.html"
)
goto end
:check
-cmd /C %PYTHON% tools\rstlint.py -i tools
+cmd /S /C "%PYTHON% tools\rstlint.py -i tools"
goto end
:serve
-cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html
+cmd /S /C "%PYTHON% ..\Tools\scripts\serve.py "%BUILDDIR%\html""
goto end
:end
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 66ae530..523d9b5 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -185,7 +185,7 @@ effect of Pascal's ``for i := a to b do``; e.g., ``range(3)`` returns the list single: mutable sequence; loop over There is a subtlety when the sequence is being modified by the loop (this can - only occur for mutable sequences, i.e. lists). An internal counter is used to + only occur for mutable sequences, e.g. lists). An internal counter is used to keep track of which item is used next, and this is incremented on each iteration. When this counter has reached the length of the sequence the loop terminates. This means that if the suite deletes the current (or a previous) @@ -281,9 +281,11 @@ function that handled an exception. statement: break statement: continue -The optional :keyword:`else` clause is executed if and when control flows off -the end of the :keyword:`try` clause. [#]_ Exceptions in the :keyword:`else` -clause are not handled by the preceding :keyword:`except` clauses. +The optional :keyword:`else` clause is executed if the control flow leaves the +:keyword:`try` suite, no exception was raised, and no :keyword:`return`, +:keyword:`continue`, or :keyword:`break` statement was executed. Exceptions in +the :keyword:`else` clause are not handled by the preceding :keyword:`except` +clauses. .. index:: keyword: finally @@ -596,10 +598,6 @@ which is then bound to the class name. there is a :keyword:`finally` clause which happens to raise another exception. That new exception causes the old one to be lost. -.. [#] Currently, control "flows off the end" except in the case of an exception or the - execution of a :keyword:`return`, :keyword:`continue`, or :keyword:`break` - statement. - .. [#] A string literal appearing as the first statement in the function body is transformed into the function's ``__doc__`` attribute and therefore the function's :term:`docstring`. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 7bdb141..92f95c2 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1919,12 +1919,6 @@ sequences, it should iterate through the values. indexes to allow proper detection of the end of the sequence. -.. method:: object.__missing__(self, key) - - Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses - when key is not in the dictionary. - - .. method:: object.__setitem__(self, key, value) Called to implement assignment to ``self[key]``. Same note as for @@ -1943,6 +1937,12 @@ sequences, it should iterate through the values. values as for the :meth:`__getitem__` method. +.. method:: object.__missing__(self, key) + + Called by :class:`dict`\ .\ :meth:`__getitem__` to implement ``self[key]`` for dict subclasses + when key is not in the dictionary. + + .. method:: object.__iter__(self) This method is called when an iterator is required for a container. This method diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst index 8556fa8..6afc867 100644 --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -581,7 +581,7 @@ whose value is one of the keys of the mapping, and the subscription selects the value in the mapping that corresponds to that key. (The expression list is a tuple except if it has exactly one item.) -If the primary is a sequence, the expression (list) must evaluate to a plain +If the primary is a sequence, the expression list must evaluate to a plain integer. If this value is negative, the length of the sequence is added to it (so that, e.g., ``x[-1]`` selects the last item of ``x``.) The resulting value must be a nonnegative integer less than the number of items in the sequence, and @@ -1390,10 +1390,10 @@ Lambdas Lambda expressions (sometimes called lambda forms) have the same syntactic position as expressions. They are a shorthand to create anonymous functions; the expression -``lambda arguments: expression`` yields a function object. The unnamed object +``lambda parameters: expression`` yields a function object. The unnamed object behaves like a function object defined with :: - def name(arguments): + def <lambda>(parameters): return expression See section :ref:`function` for the syntax of parameter lists. Note that diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst index 9f69ef7..435dfc5 100644 --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -73,11 +73,12 @@ Physical lines -------------- A physical line is a sequence of characters terminated by an end-of-line -sequence. In source files, any of the standard platform line termination -sequences can be used - the Unix form using ASCII LF (linefeed), the Windows -form using the ASCII sequence CR LF (return followed by linefeed), or the old -Macintosh form using the ASCII CR (return) character. All of these forms can be -used equally, regardless of platform. +sequence. In source files and strings, any of the standard platform line +termination sequences can be used - the Unix form using ASCII LF (linefeed), +the Windows form using the ASCII sequence CR LF (return followed by linefeed), +or the old Macintosh form using the ASCII CR (return) character. All of these +forms can be used equally, regardless of platform. The end of input also serves +as an implicit terminator for the final physical line. When embedding Python, source code strings should be passed to Python APIs using the standard C conventions for newline characters (the ``\n`` character, diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index 43935da..e2d643f 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -25,6 +25,7 @@ simple statements is: : | `break_stmt` : | `continue_stmt` : | `import_stmt` + : | `future_stmt` : | `global_stmt` : | `exec_stmt` diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst index 304abac..44196f7 100644 --- a/Doc/reference/toplevel_components.rst +++ b/Doc/reference/toplevel_components.rst @@ -51,11 +51,11 @@ a complete program; each statement is executed in the namespace of single: command line single: standard input -Under Unix, a complete program can be passed to the interpreter in three forms: -with the :option:`-c` *string* command line option, as a file passed as the -first command line argument, or as standard input. If the file or standard input -is a tty device, the interpreter enters interactive mode; otherwise, it executes -the file as a complete program. +A complete program can be passed to the interpreter +in three forms: with the :option:`-c` *string* command line option, as a file +passed as the first command line argument, or as standard input. If the file +or standard input is a tty device, the interpreter enters interactive mode; +otherwise, it executes the file as a complete program. .. _file-input: diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 7bbd580..6378f76 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -15,9 +15,11 @@ 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 import status_iterator from sphinx.util.nodes import split_explicit_title from sphinx.writers.html import HTMLTranslator from sphinx.writers.latex import LaTeXTranslator +from sphinx.writers.text import TextTranslator # monkey-patch reST parser to disable alphabetic and roman enumerated lists from docutils.parsers.rst.states import Body @@ -158,8 +160,11 @@ from sphinx.writers.text import TextWriter class PydocTopicsBuilder(Builder): name = 'pydoc-topics' + default_translator_class = TextTranslator + def init(self): self.topics = {} + self.secnumbers = {} def get_outdated_docs(self): return 'all pydoc topics' @@ -169,9 +174,9 @@ class PydocTopicsBuilder(Builder): def write(self, *ignored): writer = TextWriter(self) - for label in self.status_iterator(pydoc_topic_labels, - 'building topics... ', - length=len(pydoc_topic_labels)): + for label in status_iterator(pydoc_topic_labels, + 'building topics... ', + length=len(pydoc_topic_labels)): if label not in self.env.domaindata['std']['labels']: self.warn('label %r not in documentation' % label) continue @@ -248,11 +253,9 @@ def setup(app): app.add_directive('impl-detail', ImplementationDetail) app.add_builder(PydocTopicsBuilder) app.add_builder(suspicious.CheckSuspiciousMarkupBuilder) - app.add_description_unit('opcode', 'opcode', '%s (opcode)', - parse_opcode_signature) - app.add_description_unit('pdbcommand', 'pdbcmd', '%s (pdb command)', - parse_pdb_command) - app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)') + app.add_object_type('opcode', 'opcode', '%s (opcode)', parse_opcode_signature) + app.add_object_type('pdbcommand', 'pdbcmd', '%s (pdb command)', parse_pdb_command) + app.add_object_type('2to3fixer', '2to3fixer', '%s (2to3 fixer)') app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction) app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod) return {'version': '1.0', 'parallel_read_safe': True} diff --git a/Doc/tools/static/switchers.js b/Doc/tools/static/switchers.js index 8e0c5ea..dbf907e 100644 --- a/Doc/tools/static/switchers.js +++ b/Doc/tools/static/switchers.js @@ -11,7 +11,7 @@ var all_versions = { '3.8': 'dev (3.8)', - '3.7': 'pre (3.7)', + '3.7': '3.7', '3.6': '3.6', '3.5': '3.5', '2.7': '2.7', @@ -48,6 +48,12 @@ else buf.push('<option value="' + language + '">' + title + '</option>'); }); + if (!(current_language in all_languages)) { + // In case we're browsing a language that is not yet in all_languages. + buf.push('<option value="' + current_language + '" selected="selected">' + + current_language + '</option>'); + all_languages[current_language] = current_language; + } buf.push('</select>'); return buf.join(''); } diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index ddd8d75..1181f71 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -1,12 +1,13 @@ <h3>{% trans %}Download{% endtrans %}</h3> <p><a href="{{ pathto('download') }}">{% trans %}Download these documents{% endtrans %}</a></p> -<h3>{% trans %}Docs for other versions{% endtrans %}</h3> +<h3>{% trans %}Docs by version{% endtrans %}</h3> <ul> <li><a href="https://docs.python.org/3.8/">{% trans %}Python 3.8 (in development){% endtrans %}</a></li> - <li><a href="https://docs.python.org/3.7/">{% trans %}Python 3.7 (pre-release){% endtrans %}</a></li> - <li><a href="https://docs.python.org/3.6/">{% trans %}Python 3.6 (stable){% endtrans %}</a></li> - <li><a href="https://docs.python.org/3.5/">{% trans %}Python 3.5 (stable){% endtrans %}</a></li> - <li><a href="https://www.python.org/doc/versions/">{% trans %}Old versions{% endtrans %}</a></li> + <li><a href="https://docs.python.org/3.7/">{% trans %}Python 3.7 (stable){% endtrans %}</a></li> + <li><a href="https://docs.python.org/3.6/">{% trans %}Python 3.6 (security-fixes){% endtrans %}</a></li> + <li><a href="https://docs.python.org/3.5/">{% trans %}Python 3.5 (security-fixes){% endtrans %}</a></li> + <li><a href="https://docs.python.org/2.7/">{% trans %}Python 2.7 (stable){% endtrans %}</a></li> + <li><a href="https://www.python.org/doc/versions/">{% trans %}All versions{% endtrans %}</a></li> </ul> <h3>{% trans %}Other resources{% endtrans %}</h3> diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index 7f45c76..b17e150 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -328,8 +328,8 @@ the corresponding function with an argument list that is created by inserting the method's object before the first argument. If you still don't understand how methods work, a look at the implementation can -perhaps clarify matters. When an instance attribute is referenced that isn't a -data attribute, its class is searched. If the name denotes a valid class +perhaps clarify matters. When a non-data attribute of an instance is +referenced, the instance's class is searched. If the name denotes a valid class attribute that is a function object, a method object is created by packing (pointers to) the instance object and the function object just found together in an abstract object: this is the method object. When the method object is called @@ -620,6 +620,9 @@ be treated as a non-public part of the API (whether it is a function, a method or a data member). It should be considered an implementation detail and subject to change without notice. +.. index:: + pair: name; mangling + Since there is a valid use-case for class-private members (namely to avoid name clashes of names with names defined by subclasses), there is limited support for such a mechanism, called :dfn:`name mangling`. Any identifier of the form @@ -651,6 +654,11 @@ breaking intraclass method calls. For example:: for item in zip(keys, values): self.items_list.append(item) +The above example would work even if ``MappingSubclass`` were to introduce a +``__update`` identifier since it is replaced with ``_Mapping__update`` in the +``Mapping`` class and ``_MappingSubclass__update`` in the ``MappingSubclass`` +class respectively. + Note that the mangling rules are designed mostly to avoid accidents; it still is possible to access or modify a variable that is considered private. This can even be useful in special circumstances, such as in the debugger. diff --git a/Doc/tutorial/errors.rst b/Doc/tutorial/errors.rst index 466009e..247dda7 100644 --- a/Doc/tutorial/errors.rst +++ b/Doc/tutorial/errors.rst @@ -315,7 +315,7 @@ to create specific exception classes for different error conditions:: self.next = next self.msg = msg -Most exceptions are defined with names that end in "Error," similar to the +Most exceptions are defined with names that end in "Error", similar to the naming of the standard exceptions. Many standard modules define their own exceptions to report errors that may diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index 6c8609f..b727be0 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -137,12 +137,12 @@ where *encoding* is one of the valid :mod:`codecs` supported by Python. For example, to declare that Windows-1252 encoding is to be used, the first line of your source code file should be:: - # -*- coding: cp-1252 -*- + # -*- coding: cp1252 -*- One exception to the *first line* rule is when the source code starts with a :ref:`UNIX "shebang" line <tut-scripts>`. In this case, the encoding declaration should be added as the second line of the file. For example:: #!/usr/bin/env python - # -*- coding: cp-1252 -*- + # -*- coding: cp1252 -*- diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index be9aa83..2ff776e 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -149,12 +149,12 @@ to escape quotes:: "doesn't" >>> "doesn't" # ...or use double quotes instead "doesn't" - >>> '"Yes," he said.' - '"Yes," he said.' - >>> "\"Yes,\" he said." - '"Yes," he said.' - >>> '"Isn\'t," she said.' - '"Isn\'t," she said.' + >>> '"Yes," they said.' + '"Yes," they said.' + >>> "\"Yes,\" they said." + '"Yes," they said.' + >>> '"Isn\'t," they said.' + '"Isn\'t," they said.' In the interactive interpreter, the output string is enclosed in quotes and special characters are escaped with backslashes. While this might sometimes @@ -165,10 +165,10 @@ enclosed in single quotes. The :keyword:`print` statement produces a more readable output, by omitting the enclosing quotes and by printing escaped and special characters:: - >>> '"Isn\'t," she said.' - '"Isn\'t," she said.' - >>> print '"Isn\'t," she said.' - "Isn't," she said. + >>> '"Isn\'t," they said.' + '"Isn\'t," they said.' + >>> print '"Isn\'t," they said.' + "Isn't," they said. >>> s = 'First line.\nSecond line.' # \n means newline >>> s # without print, \n is included in the output 'First line.\nSecond line.' diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index ec3bd9c..042d233 100644 --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -377,7 +377,7 @@ module names". For example, the module name :mod:`A.B` designates a submodule named ``B`` in a package named ``A``. Just like the use of modules saves the authors of different modules from having to worry about each other's global variable names, the use of dotted module names saves the authors of multi-module -packages like NumPy or the Python Imaging Library from having to worry about +packages like NumPy or Pillow from having to worry about each other's module names. Suppose you want to design a collection of modules (a "package") for the uniform diff --git a/Doc/tutorial/whatnow.rst b/Doc/tutorial/whatnow.rst index 89dfa6a..f6ce4f4 100644 --- a/Doc/tutorial/whatnow.rst +++ b/Doc/tutorial/whatnow.rst @@ -38,7 +38,7 @@ More Python resources: * https://docs.python.org: Fast access to Python's documentation. -* https://pypi.python.org/pypi: The Python Package Index, previously also nicknamed +* https://pypi.org: The Python Package Index, previously also nicknamed the Cheese Shop, is an index of user-created Python modules that are available for download. Once you begin releasing code, you can register it here so that others can find it. diff --git a/Doc/using/unix.rst b/Doc/using/unix.rst index 7719baa..4789e4f 100644 --- a/Doc/using/unix.rst +++ b/Doc/using/unix.rst @@ -142,7 +142,7 @@ Editors and IDEs ================ There are a number of IDEs that support Python programming language. -Many editors and IDEs provide syntax highlighting, debugging tools, and PEP-8 checks. +Many editors and IDEs provide syntax highlighting, debugging tools, and :pep:`8` checks. Please go to `Python Editors <https://wiki.python.org/moin/PythonEditors>`_ and `Integrated Development Environments <https://wiki.python.org/moin/IntegratedDevelopmentEnvironments>`_ diff --git a/Doc/using/windows.rst b/Doc/using/windows.rst index f597476..778b884 100644 --- a/Doc/using/windows.rst +++ b/Doc/using/windows.rst @@ -242,7 +242,7 @@ The Windows-specific standard modules are documented in PyWin32 ------- -The `PyWin32 <https://pypi.python.org/pypi/pywin32>`_ module by Mark Hammond +The `PyWin32 <https://pypi.org/project/pywin32>`_ module by Mark Hammond is a collection of modules for advanced Windows-specific support. This includes utilities for: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index 838ca38..1ef2cb5 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -659,7 +659,7 @@ The heart of the catalog is the new Distutils :command:`register` command. Running ``python setup.py register`` will collect the metadata describing a package, such as its name, version, maintainer, description, &c., and send it to a central catalog server. The resulting catalog is available from -https://pypi.python.org/pypi. +https://pypi.org. To make the catalog a bit more useful, a new optional *classifiers* keyword argument has been added to the Distutils :func:`setup` function. A list of diff --git a/Doc/whatsnew/2.5.rst b/Doc/whatsnew/2.5.rst index d2395e7..6400bb1 100644 --- a/Doc/whatsnew/2.5.rst +++ b/Doc/whatsnew/2.5.rst @@ -229,7 +229,7 @@ required packages. :: ) Another new enhancement to the Python package index at -https://pypi.python.org is storing source and binary archives for a +https://pypi.org is storing source and binary archives for a package. The new :command:`upload` Distutils command will upload a package to the repository. diff --git a/Doc/whatsnew/2.7.rst b/Doc/whatsnew/2.7.rst index 53333eb..992658e 100644 --- a/Doc/whatsnew/2.7.rst +++ b/Doc/whatsnew/2.7.rst @@ -1218,11 +1218,6 @@ changes, or look through the Subversion logs for all the details. created some new files that should be included. (Fixed by Tarek Ziadé; :issue:`8688`.) - The ``upload`` command now longer tries to change CR end-of-line characters - to CRLF. This fixes a corruption issue with sdists that ended with a byte - equivalent to CR. - (Contributed by Bo Bayles in :issue:`32304`.) - * The :mod:`doctest` module's :const:`IGNORE_EXCEPTION_DETAIL` flag will now ignore the name of the module containing the exception being tested. (Patch by Lennart Regebro; :issue:`7490`.) @@ -1535,7 +1530,7 @@ changes, or look through the Subversion logs for all the details. *ciphers* argument that's a string listing the encryption algorithms to be allowed; the format of the string is described `in the OpenSSL documentation - <https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT>`__. + <https://www.openssl.org/docs/manmaster/man1/ciphers.html#CIPHER-LIST-FORMAT>`__. (Added by Antoine Pitrou; :issue:`8322`.) Another change makes the extension load all of OpenSSL's ciphers and @@ -1790,7 +1785,7 @@ wish to read the Tcl/Tk manual page describing the Ttk theme engine, available at https://www.tcl.tk/man/tcl8.5/TkCmd/ttk_intro.htm. Some screenshots of the Python/Ttk code in use are at -http://code.google.com/p/python-ttk/wiki/Screenshots. +https://code.google.com/archive/p/python-ttk/wikis/Screenshots.wiki. The :mod:`ttk` module was written by Guilherme Polo and added in :issue:`2983`. An alternate version called ``Tile.py``, written by @@ -1809,12 +1804,12 @@ new features were added. Most of these features were implemented by Michael Foord, unless otherwise noted. The enhanced version of the module is downloadable separately for use with Python versions 2.4 to 2.6, packaged as the :mod:`unittest2` package, from -https://pypi.python.org/pypi/unittest2. +https://pypi.org/project/unittest2. When used from the command line, the module can automatically discover tests. It's not as fancy as `py.test <http://pytest.org>`__ or -`nose <http://code.google.com/p/python-nose/>`__, but provides a simple way -to run tests kept within a set of package directories. For example, +`nose <https://nose.readthedocs.io/>`__, but provides a +simple way to run tests kept within a set of package directories. For example, the following command will search the :file:`test/` subdirectory for any importable test files named ``test*.py``:: @@ -2728,6 +2723,39 @@ For cases where the connection establishment code can't be modified, but the overall application can be, the new :func:`ssl._https_verify_certificates` function can be used to adjust the default behaviour at runtime. + +New ``make regen-all`` build target +----------------------------------- + +To simplify cross-compilation, and to ensure that CPython can reliably be +compiled without requiring an existing version of Python to already be +available, the autotools-based build system no longer attempts to implicitly +recompile generated files based on file modification times. + +Instead, a new ``make regen-all`` command has been added to force regeneration +of these files when desired (e.g. after an initial version of Python has +already been built based on the pregenerated versions). + +More selective regeneration targets are also defined - see +:source:`Makefile.pre.in` for details. + +(Contributed by Victor Stinner in :issue:`23404`.) + +.. versionadded:: 2.7.14 + + +Removal of ``make touch`` build target +-------------------------------------- + +The ``make touch`` build target previously used to request implicit regeneration +of generated files by updating their modification times has been removed. + +It has been replaced by the new ``make regen-all`` target. + +(Contributed by Victor Stinner in :issue:`23404`.) + +.. versionchanged:: 2.7.14 + .. ====================================================================== .. _acks27: |