From 22d1742a72b0ea5e939dfe68a5dc521ff514f2c0 Mon Sep 17 00:00:00 2001 From: Hyunjee Kim Date: Mon, 25 Nov 2019 17:02:02 +0900 Subject: [PATCH] Imported Upstream version 2.7.17 --- Doc/Makefile | 13 +- Doc/c-api/exceptions.rst | 8 +- Doc/c-api/list.rst | 6 +- Doc/c-api/long.rst | 6 + Doc/conf.py | 9 +- Doc/distutils/packageindex.rst | 242 +- Doc/distutils/setupscript.rst | 5 +- Doc/faq/general.rst | 22 +- Doc/faq/programming.rst | 24 +- Doc/glossary.rst | 7 + Doc/howto/regex.rst | 5 +- Doc/library/_winreg.rst | 6 +- Doc/library/ast.rst | 10 + Doc/library/colorsys.rst | 2 +- Doc/library/ctypes.rst | 2 +- Doc/library/exceptions.rst | 7 + Doc/library/functions.rst | 28 +- Doc/library/io.rst | 4 +- Doc/library/itertools.rst | 4 + Doc/library/select.rst | 7 +- Doc/library/simplehttpserver.rst | 2 +- Doc/library/stdtypes.rst | 2 +- Doc/library/sys.rst | 2 +- Doc/library/telnetlib.rst | 2 +- Doc/library/test.rst | 5 + Doc/library/textwrap.rst | 3 + Doc/library/tkinter.rst | 4 +- Doc/library/unicodedata.rst | 2 +- Doc/library/urlparse.rst | 20 + Doc/library/warnings.rst | 3 + Doc/tools/extensions/pyspecific.py | 6 +- Doc/tools/extensions/suspicious.py | 9 +- Doc/tools/static/sidebar.js | 12 + Doc/tools/static/switchers.js | 3 +- Doc/tools/templates/indexsidebar.html | 3 +- Doc/tutorial/controlflow.rst | 4 +- Doc/tutorial/modules.rst | 2 +- Include/code.h | 2 +- Include/patchlevel.h | 4 +- Include/pyport.h | 2 +- Lib/DocXMLRPCServer.py | 13 +- Lib/cookielib.py | 27 +- Lib/ctypes/test/test_arrays.py | 21 + Lib/ctypes/test/test_unicode.py | 2 +- Lib/distutils/ccompiler.py | 3 +- Lib/distutils/command/build.py | 2 +- Lib/distutils/command/check.py | 3 +- Lib/distutils/sysconfig.py | 20 +- Lib/distutils/tests/includetest.rst | 1 + Lib/distutils/tests/test_check.py | 16 +- Lib/distutils/tests/test_sysconfig.py | 99 +- Lib/email/_parseaddr.py | 11 +- Lib/email/feedparser.py | 20 - Lib/email/test/test_email.py | 14 + Lib/email/test/test_email_renamed.py | 5 - Lib/ensurepip/__init__.py | 4 +- .../_bundled/pip-18.1-py2.py3-none-any.whl | Bin 1323545 -> 0 bytes .../_bundled/pip-19.2.3-py2.py3-none-any.whl | Bin 0 -> 1414986 bytes ...=> setuptools-41.2.0-py2.py3-none-any.whl} | Bin 573107 -> 576332 bytes Lib/httplib.py | 37 +- Lib/idlelib/IOBinding.py | 2 + Lib/idlelib/NEWS.txt | 10 +- Lib/idlelib/SearchDialogBase.py | 2 + .../idle_test/test_searchdialogbase.py | 13 +- Lib/idlelib/keybindingDialog.py | 2 +- Lib/lib-tk/test/test_ttk/test_widgets.py | 11 +- Lib/lib2to3/refactor.py | 8 +- Lib/msilib/__init__.py | 2 +- Lib/sqlite3/test/factory.py | 19 +- Lib/test/bisect_cmd.py | 6 +- Lib/test/capath/efa5f9c3.0 | 34 + Lib/test/pythoninfo.py | 133 +- Lib/test/regrtest.py | 77 +- Lib/test/selfsigned_pythontestdotnet.pem | 46 +- Lib/test/ssl_servers.py | 5 + Lib/test/support/__init__.py | 4 + Lib/test/test_cookielib.py | 59 + Lib/test/test_descr.py | 8 + Lib/test/test_docxmlrpc.py | 20 + Lib/test/test_gdb.py | 47 +- Lib/test/test_httplib.py | 14 + Lib/test/test_itertools.py | 41 + Lib/test/test_msilib.py | 56 +- Lib/test/test_multiprocessing.py | 2 + Lib/test/test_os.py | 8 + Lib/test/test_ssl.py | 33 + Lib/test/test_timeout.py | 1 + Lib/test/test_tools.py | 27 + Lib/test/test_urllib.py | 36 + Lib/test/test_urllib2.py | 51 +- Lib/test/test_urllib2net.py | 14 +- Lib/test/test_urllibnet.py | 28 +- Lib/test/test_urlparse.py | 41 + Lib/test/test_wsgiref.py | 82 +- Lib/test/test_xmlrpc.py | 8 +- Lib/textwrap.py | 2 + Lib/threading.py | 3 +- Lib/urllib.py | 4 +- Lib/urlparse.py | 21 + Mac/BuildScript/{README.txt => README.rst} | 2 +- Mac/BuildScript/build-installer.py | 14 +- Mac/BuildScript/resources/License.rtf | 53 +- Mac/BuildScript/resources/ReadMe.rtf | 162 +- Mac/BuildScript/resources/Welcome.rtf | 22 +- .../resources/install_certificates.command | 2 +- Mac/{README => README.rst} | 139 +- Makefile.pre.in | 6 + Misc/ACKS | 1 + Misc/NEWS | 303 ++ Misc/valgrind-python.supp | 8 + Modules/_csv.c | 2 +- Modules/_ctypes/_ctypes.c | 25 +- Modules/_ctypes/callproc.c | 5 +- Modules/_ctypes/cfield.c | 26 +- Modules/_hashopenssl.c | 16 +- Modules/_hotshot.c | 5 +- Modules/_io/bufferedio.c | 1 + Modules/_json.c | 4 +- Modules/_multiprocessing/multiprocessing.c | 2 +- Modules/_sqlite/row.c | 12 +- Modules/_ssl.c | 4 +- Modules/_testcapimodule.c | 22 + Modules/cPickle.c | 13 +- Modules/expat/asciitab.h | 62 +- Modules/expat/expat.h | 275 +- Modules/expat/expat_external.h | 93 +- Modules/expat/iasciitab.h | 62 +- Modules/expat/internal.h | 47 +- Modules/expat/latin1tab.h | 62 +- Modules/expat/loadlibrary.c | 143 - Modules/expat/nametab.h | 242 +- Modules/expat/siphash.h | 443 +- Modules/expat/utf8tab.h | 62 +- Modules/expat/winconfig.h | 21 +- Modules/expat/xmlparse.c | 3809 ++++++++--------- Modules/expat/xmlrole.c | 747 ++-- Modules/expat/xmlrole.h | 13 +- Modules/expat/xmltok.c | 1375 +++--- Modules/expat/xmltok.h | 212 +- Modules/expat/xmltok_impl.c | 999 ++--- Modules/expat/xmltok_impl.h | 72 +- Modules/expat/xmltok_ns.c | 84 +- Modules/itertoolsmodule.c | 10 + Modules/linuxaudiodev.c | 2 + Modules/mathmodule.c | 8 +- Modules/mmapmodule.c | 3 +- Modules/socketmodule.c | 29 +- Objects/bytearrayobject.c | 10 +- Objects/exceptions.c | 4 +- Objects/longobject.c | 2 +- Objects/obmalloc.c | 6 + Objects/structseq.c | 1 + Objects/typeobject.c | 8 +- PC/VS9.0/_elementtree.vcproj | 4 - PC/VS9.0/pyexpat.vcproj | 4 - PC/_msi.c | 33 +- PC/_winreg.c | 8 +- PC/bdist_wininst/install.c | 3 +- PCbuild/_elementtree.vcxproj | 1 - PCbuild/_elementtree.vcxproj.filters | 3 - PCbuild/get_external.py | 6 +- PCbuild/get_externals.bat | 14 +- PCbuild/pyexpat.vcxproj | 1 - PCbuild/pyexpat.vcxproj.filters | 3 - PCbuild/pyproject.props | 2 +- PCbuild/python.props | 4 +- PCbuild/readme.txt | 4 +- Parser/myreadline.c | 22 +- Parser/tokenizer.c | 9 +- Python/bltinmodule.c | 11 +- Python/dtoa.c | 78 +- Python/pythonrun.c | 2 +- Python/thread_pthread.h | 15 +- README | 38 +- Tools/nuget/make_zip.py | 1 + Tools/nuget/python2.nuspec | 3 +- Tools/nuget/python2x86.nuspec | 3 +- Tools/scripts/lll.py | 7 +- aclocal.m4 | 78 +- configure | 73 +- configure.ac | 14 +- pyconfig.h.in | 5 +- setup.py | 64 +- 183 files changed, 6139 insertions(+), 5916 deletions(-) create mode 100644 Lib/distutils/tests/includetest.rst delete mode 100644 Lib/ensurepip/_bundled/pip-18.1-py2.py3-none-any.whl create mode 100644 Lib/ensurepip/_bundled/pip-19.2.3-py2.py3-none-any.whl rename Lib/ensurepip/_bundled/{setuptools-40.6.2-py2.py3-none-any.whl => setuptools-41.2.0-py2.py3-none-any.whl} (80%) create mode 100644 Lib/test/capath/efa5f9c3.0 rename Mac/BuildScript/{README.txt => README.rst} (99%) rename Mac/{README => README.rst} (75%) delete mode 100644 Modules/expat/loadlibrary.c diff --git a/Doc/Makefile b/Doc/Makefile index ebabc02..3d7e4ac 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -5,7 +5,9 @@ # You can set these variables from the command line. PYTHON = python -SPHINXBUILD = sphinx-build +VENVDIR = ./venv +SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build +BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb PAPER = SOURCES = DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) @@ -102,7 +104,12 @@ htmlview: html $(PYTHON) -c "import webbrowser; webbrowser.open('build/html/index.html')" clean: - -rm -rf build/* + -rm -rf build/* $(VENVDIR)/* + +venv: + $(PYTHON) -m venv $(VENVDIR) + $(VENVDIR)/bin/python3 -m pip install -U Sphinx blurb + @echo "The venv has been created in the $(VENVDIR) directory" dist: rm -rf dist @@ -148,7 +155,7 @@ dist: cp -pPR build/epub/Python.epub dist/python-$(DISTVERSION)-docs.epub check: - $(PYTHON) tools/rstlint.py -i tools + $(PYTHON)2 tools/rstlint.py -i tools -i $(VENVDIR) serve: ../Tools/scripts/serve.py build/html diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index db302d8..281e4c8 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -44,8 +44,12 @@ is a separate error indicator for each thread. .. c:function:: void PyErr_PrintEx(int set_sys_last_vars) Print a standard traceback to ``sys.stderr`` and clear the error indicator. - Call this function only when the error indicator is set. (Otherwise it will - cause a fatal error!) + **Unless** the error is a ``SystemExit``. In that case the no traceback + is printed and Python process will exit with the error code specified by + the ``SystemExit`` instance. + + Call this function **only** when the error indicator is set. Otherwise it + will cause a fatal error! If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the diff --git a/Doc/c-api/list.rst b/Doc/c-api/list.rst index 0aed0f3..a5e4a45 100644 --- a/Doc/c-api/list.rst +++ b/Doc/c-api/list.rst @@ -76,9 +76,9 @@ List Objects .. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index) Return the object at position *index* in the list pointed to by *list*. The - position must be positive, indexing from the end of the list is not - supported. If *index* is out of bounds, return *NULL* and set an - :exc:`IndexError` exception. + position must be non-negative; indexing from the end of the list is not + supported. If *index* is out of bounds (<0 or >=len(list)), + return *NULL* and set an :exc:`IndexError` exception. .. versionchanged:: 2.5 This function used an :c:type:`int` for *index*. This might require diff --git a/Doc/c-api/long.rst b/Doc/c-api/long.rst index 28fb589..4684d1b 100644 --- a/Doc/c-api/long.rst +++ b/Doc/c-api/long.rst @@ -217,6 +217,9 @@ Long Integer Objects Return a C :c:type:`unsigned long` from a Python long integer, without checking for overflow. + Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to + disambiguate. + .. versionadded:: 2.3 @@ -225,6 +228,9 @@ Long Integer Objects Return a C :c:type:`unsigned long long` from a Python long integer, without checking for overflow. + Returns ``(unsigned PY_LONG_LONG)-1`` on error. Use + :c:func:`PyErr_Occurred` to disambiguate. + .. versionadded:: 2.3 diff --git a/Doc/conf.py b/Doc/conf.py index 557fe1e..393018d 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -41,6 +41,8 @@ exclude_patterns = [ # Require Sphinx 1.2 for build. needs_sphinx = '1.2' +# Avoid a warning with Sphinx >= 2.0 +master_doc = 'contents' # Options for HTML output # ----------------------- @@ -57,7 +59,7 @@ templates_path = ['tools/templates'] # Custom sidebar templates, filenames relative to this file. html_sidebars = { - 'index': 'indexsidebar.html', + 'index': ['indexsidebar.html'], } # Additional templates that should be rendered to pages. @@ -82,11 +84,10 @@ html_split_index = True # Options for LaTeX output # ------------------------ +latex_engine = 'xelatex' + # Get LaTeX to handle Unicode correctly latex_elements = { - 'inputenc': r'\usepackage[utf8x]{inputenc}', - 'utf8extra': '', - 'fontenc': r'\usepackage[T1,T2A]{fontenc}', } # Additional stuff for the LaTeX preamble. diff --git a/Doc/distutils/packageindex.rst b/Doc/distutils/packageindex.rst index cd11f20..f74c439 100644 --- a/Doc/distutils/packageindex.rst +++ b/Doc/distutils/packageindex.rst @@ -8,244 +8,10 @@ The Python Package Index (PyPI) ******************************* -The `Python Package Index (PyPI)`_ stores :ref:`meta-data ` -describing distributions packaged with distutils, as well as package data like -distribution files if a package author wishes. - -Distutils provides the :command:`register` and :command:`upload` commands for -pushing meta-data and distribution files to PyPI, respectively. See -:ref:`package-commands` for information on these commands. - - -PyPI overview -============= - -PyPI lets you submit any number of versions of your distribution to the index. -If you alter the meta-data for a particular version, you can submit it again -and the index will be updated. - -PyPI holds a record for each (name, version) combination submitted. The first -user to submit information for a given name is designated the Owner of that -name. Changes can be submitted through the :command:`register` command or -through the web interface. Owners can designate other users as Owners or -Maintainers. Maintainers can edit the package information, but not designate -new Owners or Maintainers. - -By default PyPI displays only the newest version of a given package. The web -interface lets one change this default behavior and manually select which -versions to display and hide. - -For each version, PyPI displays a home page. The home page is created from -the ``long_description`` which can be submitted via the :command:`register` -command. See :ref:`package-display` for more information. - - -.. _package-commands: - -Distutils commands -================== - -Distutils exposes two commands for submitting package data to PyPI: the -:ref:`register ` command for submitting meta-data to PyPI -and the :ref:`upload ` command for submitting distribution -files. Both commands read configuration data from a special file called a -:ref:`.pypirc file `. - - -.. _package-register: - -The ``register`` command ------------------------- - -The distutils command :command:`register` is used to submit your distribution's -meta-data to an index server. It is invoked as follows:: - - python setup.py register - -Distutils will respond with the following prompt:: - - running register - We need to know who you are, so please choose either: - 1. use your existing login, - 2. register as a new user, - 3. have the server generate a new password for you (and email it to you), or - 4. quit - Your selection [default 1]: - -Note: if your username and password are saved locally, you will not see this -menu. Also, refer to :ref:`pypirc` for how to store your credentials in a -:file:`.pypirc` file. - -If you have not registered with PyPI, then you will need to do so now. You -should choose option 2, and enter your details as required. Soon after -submitting your details, you will receive an email which will be used to confirm -your registration. - -Once you are registered, you may choose option 1 from the menu. You will be -prompted for your PyPI username and password, and :command:`register` will then -submit your meta-data to the index. - -See :ref:`package-cmdoptions` for options to the :command:`register` command. - - -.. _package-upload: - -The ``upload`` command ----------------------- - -.. versionadded:: 2.5 - -The distutils command :command:`upload` pushes the distribution files to PyPI. - -The command is invoked immediately after building one or more distribution -files. For example, the command :: - - python setup.py sdist bdist_wininst upload - -will cause the source distribution and the Windows installer to be uploaded to -PyPI. Note that these will be uploaded even if they are built using an earlier -invocation of :file:`setup.py`, but that only distributions named on the command -line for the invocation including the :command:`upload` command are uploaded. - -If a :command:`register` command was previously called in the same command, -and if the password was entered in the prompt, :command:`upload` will reuse the -entered password. This is useful if you do not want to store a password in -clear text in a :file:`.pypirc` file. - -You can use the ``--sign`` option to tell :command:`upload` to sign each -uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must -be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the ``--identity=name`` option. - -See :ref:`package-cmdoptions` for additional options to the :command:`upload` -command. - - -.. _package-cmdoptions: - -Additional command options --------------------------- - -This section describes options common to both the :command:`register` and -:command:`upload` commands. - -The ``--repository`` or ``-r`` option lets you specify a PyPI server -different from the default. For example:: - - python setup.py sdist bdist_wininst upload -r https://example.com/pypi - -For convenience, a name can be used in place of the URL when the -:file:`.pypirc` file is configured to do so. For example:: - - python setup.py register -r other - -See :ref:`pypirc` for more information on defining alternate servers. - -The ``--show-response`` option displays the full response text from the PyPI -server, which is useful when debugging problems with registering and uploading. - - -.. index:: - single: .pypirc file - single: Python Package Index (PyPI); .pypirc file - -.. _pypirc: - -The ``.pypirc`` file --------------------- - -The :command:`register` and :command:`upload` commands both check for the -existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. -If this file exists, the command uses the username, password, and repository -URL configured in the file. The format of a :file:`.pypirc` file is as -follows:: - - [distutils] - index-servers = - pypi - - [pypi] - repository: - username: - password: - -The *distutils* section defines an *index-servers* variable that lists the -name of all sections describing a repository. - -Each section describing a repository defines three variables: - -- *repository*, that defines the url of the PyPI server. Defaults to - ``https://www.python.org/pypi``. -- *username*, which is the registered username on the PyPI server. -- *password*, that will be used to authenticate. If omitted the user - will be prompt to type it when needed. - -If you want to define another server a new section can be created and -listed in the *index-servers* variable:: - - [distutils] - index-servers = - pypi - other - - [pypi] - repository: - username: - password: - - [other] - repository: https://example.com/pypi - username: - password: - -This allows the :command:`register` and :command:`upload` commands to be -called with the ``--repository`` option as described in -:ref:`package-cmdoptions`. - -Specifically, you might want to add the `PyPI Test Repository -`_ to your ``.pypirc`` to facilitate -testing before doing your first upload to ``PyPI`` itself. - - -.. _package-display: - -PyPI package display -==================== - -The ``long_description`` field plays a special role at PyPI. It is used by -the server to display a home page for the registered package. - -If you use the `reStructuredText `_ -syntax for this field, PyPI will parse it and display an HTML output for -the package home page. - -The ``long_description`` field can be attached to a text file located -in the package:: - - from distutils.core import setup - - with open('README.txt') as file: - long_description = file.read() - - setup(name='Distutils', - long_description=long_description) - -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. - -To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package and -check the ``long_description`` from the command line: - -.. code-block:: shell-session - - $ python setup.py --long-description | rst2html.py > output.html - -:mod:`docutils` will display a warning if there's something wrong with your -syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` -to ``rst2html.py`` in the command above), being able to run the command above -without warnings does not guarantee that PyPI will convert the content -successfully. +The `Python Package Index (PyPI)`_ stores metadata describing distributions +packaged with distutils and other publishing tools, as well the distribution +archives themselves. +Detailed instructions on using PyPI at :ref:`distributing-index`. .. _Python Package Index (PyPI): https://pypi.org diff --git a/Doc/distutils/setupscript.rst b/Doc/distutils/setupscript.rst index 8407206..fae570f 100644 --- a/Doc/distutils/setupscript.rst +++ b/Doc/distutils/setupscript.rst @@ -612,9 +612,8 @@ Notes: `_. (5) - The ``long_description`` field is used by PyPI when you are - :ref:`registering ` a package, to - :ref:`build its home page `. + The ``long_description`` field is used by PyPI when you publish a package, + to build its project page. (6) The ``license`` field is a text indicating the license covering the diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 887dea7..27f4681 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -268,14 +268,8 @@ Python references; or perhaps search for "Python" and "language". Where in the world is www.python.org located? --------------------------------------------- -The Python project's infrastructure is located all over the world. -`www.python.org `_ is graciously hosted by `Rackspace -`_, with CDN caching provided by `Fastly -`_. `Upfront Systems -`_ hosts `bugs.python.org -`_. Many other Python services like `the Wiki -`_ are hosted by `Oregon State -University Open Source Lab `_. +The Python project's infrastructure is located all over the world and is managed +by the Python Infrastructure Team. Details `here `__. Why is it called Python? @@ -312,14 +306,10 @@ 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 -`_. 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 `_. -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. - +`_. There are two production-ready versions +of Python: 2.x and 3.x. The recommended version is 3.x, which is supported by +most widely used libraries. Although 2.x is still widely used, `it will not +be maintained after January 1, 2020 `_. How many people are using Python? --------------------------------- diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index 9190e1a..62b34b6 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -997,9 +997,27 @@ To convert, e.g., the number 144 to the string '144', use the built-in type constructor :func:`str`. If you want a hexadecimal or octal representation, use the built-in functions :func:`hex` or :func:`oct`. For fancy formatting, see the :ref:`formatstrings` section, e.g. ``"{:04d}".format(144)`` yields -``'0144'`` and ``"{:.3f}".format(1/3)`` yields ``'0.333'``. You may also use -:ref:`the % operator ` on strings. See the library reference -manual for details. +``'0144'`` and ``"{:.3f}".format(1.0/3.0)`` yields ``'0.333'``. In Python 2, the +division (/) operator returns the floor of the mathematical result of division +if the arguments are ints or longs, but it returns a reasonable approximation of +the division result if the arguments are floats or complex:: + + >>> print('{:.3f}'.format(1/3)) + 0.000 + >>> print('{:.3f}'.format(1.0/3)) + 0.333 + +In Python 3, the default behaviour of the division operator (see :pep:`238`) has +been changed but you can have the same behaviour in Python 2 if you import +``division`` from :mod:`__future__`:: + + >>> from __future__ import division + >>> print('{:.3f}'.format(1/3)) + 0.333 + + +You may also use :ref:`the % operator ` on strings. See the +library reference manual for details. How do I modify a string in place? diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 9e6bf23..43abf50 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -490,6 +490,11 @@ Glossary :meth:`load_module`. A loader is typically returned by a :term:`finder`. See :pep:`302` for details. + magic method + .. index:: pair: magic; method + + An informal synonym for :term:`special method`. + mapping A container object that supports arbitrary key lookups and implements the methods specified in the :class:`~collections.Mapping` or @@ -698,6 +703,8 @@ Glossary versions, :meth:`__getslice__` and :meth:`__setslice__`). special method + .. index:: pair: special; method + A method that is called implicitly by Python to execute a certain operation on a type, such as addition. Such methods have names starting and ending with double underscores. Special methods are documented in diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index 082fc01..81c0495 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -101,8 +101,9 @@ special nature. You can match the characters not listed within the class by :dfn:`complementing` the set. This is indicated by including a ``'^'`` as the first character of the -class; ``'^'`` outside a character class will simply match the ``'^'`` -character. For example, ``[^5]`` will match any character except ``'5'``. +class. For example, ``[^5]`` will match any character except ``'5'``. If the +caret appears elsewhere in a character class, it does not have special meaning. +For example: ``[5^]`` will match either a ``'5'`` or a ``'^'``. Perhaps the most important metacharacter is the backslash, ``\``. As in Python string literals, the backslash can be followed by various characters to signal diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst index a87cb9c..177e199 100644 --- a/Doc/library/_winreg.rst +++ b/Doc/library/_winreg.rst @@ -427,7 +427,7 @@ This module offers the following functions: *key* is an already open key, or one of the predefined :ref:`HKEY_* constants `. - Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Will generally raise :exc:`NotImplementedError` if executed on a 32-bit operating system. If the key is not on the reflection list, the function succeeds but has no @@ -442,7 +442,7 @@ This module offers the following functions: *key* is an already open key, or one of the predefined :ref:`HKEY_* constants `. - Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Will generally raise :exc:`NotImplementedError` if executed on a 32-bit operating system. Restoring reflection for a key does not affect reflection of any subkeys. @@ -457,7 +457,7 @@ This module offers the following functions: Returns ``True`` if reflection is disabled. - Will generally raise :exc:`NotImplemented` if executed on a 32-bit + Will generally raise :exc:`NotImplementedError` if executed on a 32-bit operating system. diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 6d5855b..b04a92d 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -129,6 +129,11 @@ and classes for traversing abstract syntax trees: Parse the source into an AST node. Equivalent to ``compile(source, filename, mode, ast.PyCF_ONLY_AST)``. + .. warning:: + It is possible to crash the Python interpreter with a + sufficiently large/complex string due to stack depth limitations + in Python's AST compiler. + .. function:: literal_eval(node_or_string) @@ -142,6 +147,11 @@ and classes for traversing abstract syntax trees: capable of evaluating arbitrarily complex expressions, for example involving operators or indexing. + .. warning:: + It is possible to crash the Python interpreter with a + sufficiently large/complex string due to stack depth limitations + in Python's AST compiler. + .. function:: get_docstring(node, clean=True) diff --git a/Doc/library/colorsys.rst b/Doc/library/colorsys.rst index f1447e8..32eac8e 100644 --- a/Doc/library/colorsys.rst +++ b/Doc/library/colorsys.rst @@ -20,7 +20,7 @@ spaces, the coordinates are all between 0 and 1. .. seealso:: More information about color spaces can be found at - http://www.poynton.com/ColorFAQ.html and + https://www.poynton.com/ColorFAQ.html and https://www.cambridgeincolour.com/tutorials/color-spaces.htm. The :mod:`colorsys` module defines the following functions: diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index df9ccbf..6a52991 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -565,7 +565,7 @@ Here is a simple example of a POINT structure, which contains two integers named >>> POINT(1, 2, 3) Traceback (most recent call last): File "", line 1, in - ValueError: too many initializers + TypeError: too many initializers >>> You can, however, build much more complicated structures. A structure can diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 8757c6c..3cb9445 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -524,6 +524,13 @@ module for more information. .. versionadded:: 2.5 +.. exception:: BytesWarning + + Base class for warnings related to bytes and bytearray. + + .. versionadded:: 2.6 + + Exception hierarchy ------------------- diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 4386e60..23f34a3 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -175,19 +175,18 @@ section. def f(cls, arg1, arg2, ...): ... - The ``@classmethod`` form is a function :term:`decorator` -- see the description - of function definitions in :ref:`function` for details. + The ``@classmethod`` form is a function :term:`decorator` -- see + :ref:`function` for details. - It can be called either on the class (such as ``C.f()``) or on an instance (such + A class method can be called either on the class (such as ``C.f()``) or on an instance (such as ``C().f()``). The instance is ignored except for its class. If a class method is called for a derived class, the derived class object is passed as the implied first argument. Class methods are different than C++ or Java static methods. If you want those, - see :func:`staticmethod` in this section. + see :func:`staticmethod`. - For more information on class methods, consult the documentation on the standard - type hierarchy in :ref:`types`. + For more information on class methods, see :ref:`types`. .. versionadded:: 2.2 @@ -249,6 +248,12 @@ section. character. This is to facilitate detection of incomplete and complete statements in the :mod:`code` module. + .. warning:: + + It is possible to crash the Python interpreter with a + sufficiently large/complex string when compiling to an AST + object due to stack depth limitations in Python's AST compiler. + .. versionchanged:: 2.3 The *flags* and *dont_inherit* arguments were added. @@ -1346,18 +1351,17 @@ section. def f(arg1, arg2, ...): ... - The ``@staticmethod`` form is a function :term:`decorator` -- see the - description of function definitions in :ref:`function` for details. + The ``@staticmethod`` form is a function :term:`decorator` -- see + :ref:`function` for details. - It can be called either on the class (such as ``C.f()``) or on an instance (such - as ``C().f()``). The instance is ignored except for its class. + A static method can be called either on the class (such as ``C.f()``) or on an instance (such + as ``C().f()``). Static methods in Python are similar to those found in Java or C++. Also see :func:`classmethod` for a variant that is useful for creating alternate class constructors. - For more information on static methods, consult the documentation on the - standard type hierarchy in :ref:`types`. + For more information on static methods, see :ref:`types`. .. versionadded:: 2.2 diff --git a/Doc/library/io.rst b/Doc/library/io.rst index dcdd01c..7c053f9 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -304,7 +304,7 @@ I/O Base Classes Note that it's already possible to iterate on file objects using ``for line in file: ...`` without calling ``file.readlines()``. - .. method:: seek(offset[, whence]) + .. method:: seek(offset, whence=SEEK_SET) Change the stream position to the given byte *offset*. *offset* is interpreted relative to the position indicated by *whence*. The default @@ -736,7 +736,7 @@ Text I/O If *limit* is specified, at most *limit* characters will be read. - .. method:: seek(offset[, whence]) + .. method:: seek(offset, whence=SEEK_SET) Change the stream position to the given *offset*. Behaviour depends on the *whence* parameter. The default value for *whence* is diff --git a/Doc/library/itertools.rst b/Doc/library/itertools.rst index 17303dd..18477f1 100644 --- a/Doc/library/itertools.rst +++ b/Doc/library/itertools.rst @@ -659,6 +659,10 @@ loops that truncate the stream. used anywhere else; otherwise, the *iterable* could get advanced without the tee objects being informed. + ``tee`` iterators are not threadsafe. A :exc:`RuntimeError` may be + raised when using simultaneously iterators returned by the same :func:`tee` + call, even if the original *iterable* is threadsafe. + This itertool may require significant auxiliary storage (depending on how much temporary data needs to be stored). In general, if one iterator uses most or all of the data before another iterator starts, it is faster to use diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 7a08045..b68b324 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -291,13 +291,14 @@ Kqueue Objects Create a kqueue object from a given file descriptor. -.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist +.. method:: kqueue.control(changelist, max_events[, timeout]) -> eventlist Low level interface to kevent - - changelist must be an iterable of kevent object or ``None`` + - changelist must be an iterable of kevent objects or ``None`` - max_events must be 0 or a positive integer - - timeout in seconds (floats possible) + - timeout in seconds (floats possible); the default is ``None``, + to wait forever .. _kevent-objects: diff --git a/Doc/library/simplehttpserver.rst b/Doc/library/simplehttpserver.rst index df8699e..1eca9fe 100644 --- a/Doc/library/simplehttpserver.rst +++ b/Doc/library/simplehttpserver.rst @@ -13,7 +13,7 @@ .. warning:: - mod:`SimpleHTTServer` is not recommended for production. It only implements + :mod:`SimpleHTTPServer` is not recommended for production. It only implements basic security checks. The :mod:`SimpleHTTPServer` module defines a single class, diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index ff68738..b4fe19a 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -1909,7 +1909,7 @@ The constructors for both classes work the same: .. method:: copy() - Return a new set with a shallow copy of *s*. + Return a shallow copy of the set. Note, the non-operator versions of :meth:`union`, :meth:`intersection`, diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 5a7647b..339625a 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -1030,7 +1030,7 @@ always available. .. note:: Python is now `developed `_ using - Mercurial. In recent Python 2.7 bugfix releases, :data:`subversion` + Git. In recent Python 2.7 bugfix releases, :data:`subversion` therefore contains placeholder information. It is removed in Python 3.3. diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst index a3019f5..73721f5 100644 --- a/Doc/library/telnetlib.rst +++ b/Doc/library/telnetlib.rst @@ -29,7 +29,7 @@ Character), EL (Erase Line), GA (Go Ahead), SB (Subnegotiation Begin). .. class:: Telnet([host[, port[, timeout]]]) :class:`Telnet` represents a connection to a Telnet server. The instance is - initially not connected by default; the :meth:`open` method must be used to + initially not connected by default; the :meth:`~Telnet.open` method must be used to establish a connection. Alternatively, the host name and optional port number can be passed to the constructor, to, in which case the connection to the server will be established before the constructor returns. The optional diff --git a/Doc/library/test.rst b/Doc/library/test.rst index eef5d16..9d78c90 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -246,6 +246,11 @@ The :mod:`test.support` module defines the following constants: Set to a name that is safe to use as the name of a temporary file. Any temporary file that is created should be closed and unlinked (removed). + +.. data:: TEST_HTTP_URL + + Define the URL of a dedicated HTTP server for the network tests. + The :mod:`test.support` module defines the following functions: diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index a50600e..6b0decb 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -66,6 +66,9 @@ indentation from strings that have unwanted whitespace to the left of the text. of this module incorrectly expanded tabs before searching for common leading whitespace.) + Lines containing only whitespace are ignored in the input and normalized to a + single newline character in the output. + For example:: def test(): diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 3356e4e..9aa6dcb 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -33,7 +33,7 @@ installed, so you can read the Tcl/Tk documentation specific to that version. `TKDocs `_ Extensive tutorial plus friendlier widget pages for some of the widgets. - `Tkinter reference: a GUI for Python `_ + `Tkinter 8.5 reference: a GUI for Python `_ On-line reference material. `Tkinter docs from effbot `_ @@ -43,7 +43,7 @@ installed, so you can read the Tcl/Tk documentation specific to that version. Book by Mark Lutz, has excellent coverage of Tkinter. `Modern Tkinter for Busy Python Developers `_ - Book by Mark Rozerman about building attractive and modern graphical user interfaces with Python and Tkinter. + Book by Mark Roseman about building attractive and modern graphical user interfaces with Python and Tkinter. `Python and Tkinter Programming `_ Book by John Grayson (ISBN 1-884777-81-3). diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst index d7c48c4..bed35ef 100644 --- a/Doc/library/unicodedata.rst +++ b/Doc/library/unicodedata.rst @@ -20,7 +20,7 @@ based on the :file:`UnicodeData.txt` file version 5.2.0 which is publicly available from ftp://ftp.unicode.org/. The module uses the same names and symbols as defined by the UnicodeData File -Format 5.2.0 (see http://www.unicode.org/reports/tr44/tr44-4.html). +Format 5.2.0 (see https://www.unicode.org/reports/tr44/). It defines the following functions: diff --git a/Doc/library/urlparse.rst b/Doc/library/urlparse.rst index 22249da..0989c88 100644 --- a/Doc/library/urlparse.rst +++ b/Doc/library/urlparse.rst @@ -119,12 +119,22 @@ The :mod:`urlparse` module defines the following functions: See section :ref:`urlparse-result-object` for more information on the result object. + Characters in the :attr:`netloc` attribute that decompose under NFKC + normalization (as used by the IDNA encoding) into any of ``/``, ``?``, + ``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is + decomposed before parsing, or is not a Unicode string, no error will be + raised. + .. versionchanged:: 2.5 Added attributes to return value. .. versionchanged:: 2.7 Added IPv6 URL parsing capabilities. + .. versionchanged:: 2.7.17 + Characters that affect netloc parsing under NFKC normalization will + now raise :exc:`ValueError`. + .. function:: parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]]) @@ -232,11 +242,21 @@ The :mod:`urlparse` module defines the following functions: See section :ref:`urlparse-result-object` for more information on the result object. + Characters in the :attr:`netloc` attribute that decompose under NFKC + normalization (as used by the IDNA encoding) into any of ``/``, ``?``, + ``#``, ``@``, or ``:`` will raise a :exc:`ValueError`. If the URL is + decomposed before parsing, or is not a Unicode string, no error will be + raised. + .. versionadded:: 2.2 .. versionchanged:: 2.5 Added attributes to return value. + .. versionchanged:: 2.7.17 + Characters that affect netloc parsing under NFKC normalization will + now raise :exc:`ValueError`. + .. function:: urlunsplit(parts) diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst index e82bb97..2f699ea 100644 --- a/Doc/library/warnings.rst +++ b/Doc/library/warnings.rst @@ -91,6 +91,9 @@ following warnings category classes are currently defined: | :exc:`UnicodeWarning` | Base category for warnings related to | | | Unicode. | +----------------------------------+-----------------------------------------------+ +| :exc:`BytesWarning` | Base category for warnings related to | +| | bytes and bytearray. | ++----------------------------------+-----------------------------------------------+ While these are technically built-in exceptions, they are documented here, because conceptually they belong to the warnings mechanism. diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 6378f76..1ec88c2 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -15,7 +15,6 @@ 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 @@ -173,6 +172,11 @@ class PydocTopicsBuilder(Builder): return '' # no URIs def write(self, *ignored): + try: # sphinx>=1.6 + from sphinx.util import status_iterator + except ImportError: # sphinx<1.6 + status_iterator = self.status_iterator + writer = TextWriter(self) for label in status_iterator(pydoc_topic_labels, 'building topics... ', diff --git a/Doc/tools/extensions/suspicious.py b/Doc/tools/extensions/suspicious.py index 0a70e57..494efab 100644 --- a/Doc/tools/extensions/suspicious.py +++ b/Doc/tools/extensions/suspicious.py @@ -48,6 +48,7 @@ import sys from docutils import nodes from sphinx.builders import Builder +import sphinx.util detect_all = re.compile(r''' ::(?=[^=])| # two :: (but NOT ::=) @@ -85,6 +86,7 @@ class CheckSuspiciousMarkupBuilder(Builder): Checks for possibly invalid markup that may leak into the output. """ name = 'suspicious' + logger = sphinx.util.logging.getLogger("CheckSuspiciousMarkupBuilder") def init(self): # create output file @@ -116,7 +118,7 @@ class CheckSuspiciousMarkupBuilder(Builder): self.warn('Found %s/%s unused rules:' % (len(unused_rules), len(self.rules))) for rule in unused_rules: - self.info(repr(rule)) + self.logger.info(repr(rule)) return def check_issue(self, line, lineno, issue): @@ -146,7 +148,6 @@ class CheckSuspiciousMarkupBuilder(Builder): return False def report_issue(self, text, lineno, issue): - if not self.any_issue: self.info() self.any_issue = True self.write_log_entry(lineno, issue, text) if py3: @@ -181,7 +182,7 @@ class CheckSuspiciousMarkupBuilder(Builder): A csv file, with exactly the same format as suspicious.csv Fields: document name (normalized), line number, issue, surrounding text """ - self.info("loading ignore rules... ", nonl=1) + self.logger.info("loading ignore rules... ", nonl=1) self.rules = rules = [] try: if py3: @@ -206,7 +207,7 @@ class CheckSuspiciousMarkupBuilder(Builder): rule = Rule(docname, lineno, issue, text) rules.append(rule) f.close() - self.info('done, %d rules loaded' % len(self.rules)) + self.logger.info('done, %d rules loaded' % len(self.rules)) def get_lineno(node): diff --git a/Doc/tools/static/sidebar.js b/Doc/tools/static/sidebar.js index 1bdd829..17f818e 100644 --- a/Doc/tools/static/sidebar.js +++ b/Doc/tools/static/sidebar.js @@ -46,6 +46,15 @@ $(function() { var dark_color = $('.related').css('background-color'); var light_color = $('.document').css('background-color'); + // set position: sticky on sidebar + // (browsers that don't support this will fall-back to + // positioning via scroll_sidebar) + var supportsPositionSticky = (window.CSS && window.CSS.supports && + window.CSS.supports('position', 'sticky')); + if (supportsPositionSticky) { + sidebarwrapper.css('position', 'sticky'); + } + function get_viewport_height() { if (window.innerHeight) return window.innerHeight; @@ -157,6 +166,9 @@ $(function() { /* intelligent scrolling */ function scroll_sidebar() { + if (supportsPositionSticky) { + return; + } var sidebar_height = sidebarwrapper.height(); var viewport_height = get_viewport_height(); var offset = sidebar.position()['top']; diff --git a/Doc/tools/static/switchers.js b/Doc/tools/static/switchers.js index dbf907e..d4fc07d 100644 --- a/Doc/tools/static/switchers.js +++ b/Doc/tools/static/switchers.js @@ -10,7 +10,8 @@ '(?:release/\\d.\\d[\\x\\d\\.]*)']; var all_versions = { - '3.8': 'dev (3.8)', + '3.9': 'dev (3.9)', + '3.8': '3.8', '3.7': '3.7', '3.6': '3.6', '3.5': '3.5', diff --git a/Doc/tools/templates/indexsidebar.html b/Doc/tools/templates/indexsidebar.html index 1181f71..e5748f2 100644 --- a/Doc/tools/templates/indexsidebar.html +++ b/Doc/tools/templates/indexsidebar.html @@ -2,7 +2,8 @@

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

{% trans %}Docs by version{% endtrans %}