From: DongHun Kwak Date: Wed, 12 Jul 2017 02:05:23 +0000 (+0900) Subject: Imported Upstream version 2.7.10 X-Git-Tag: upstream/2.7.10 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Ftags%2Fupstream%2F2.7.10;p=platform%2Fupstream%2Fpython.git Imported Upstream version 2.7.10 Change-Id: I71e04a6e83b31198e3aff21913814359e60b7843 Signed-off-by: DongHun Kwak --- diff --git a/Demo/turtle/turtleDemo.py b/Demo/turtle/turtleDemo.py index d284042..12b4355 100755 --- a/Demo/turtle/turtleDemo.py +++ b/Demo/turtle/turtleDemo.py @@ -231,6 +231,8 @@ class DemoWindow(object): else: self.state = DONE except turtle.Terminator: + if self.root is None: + return self.state = DONE result = "stopped!" if self.state == DONE: @@ -257,7 +259,9 @@ class DemoWindow(object): turtle.TurtleScreen._RUNNING = False def _destroy(self): + turtle.TurtleScreen._RUNNING = False self.root.destroy() + self.root = None #sys.exit() def main(): diff --git a/Doc/Makefile b/Doc/Makefile index 5b5f68a..ea30231 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -8,7 +8,7 @@ PYTHON = python SPHINXBUILD = sphinx-build PAPER = SOURCES = -DISTVERSION = $(shell $(PYTHON) tools/patchlevel.py) +DISTVERSION = $(shell $(PYTHON) tools/extensions/patchlevel.py) ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees -D latex_paper_size=$(PAPER) \ $(SPHINXOPTS) . build/$(BUILDER) $(SOURCES) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 74693ac..e36d01f 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -98,8 +98,11 @@ 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 + this field must be NULL (the default value). + Here is a function that returns a pointer to the element in an N-D array - pointed to by an N-dimesional index when there are both non-NULL strides + pointed to by an N-dimensional index when there are both non-NULL strides and suboffsets:: void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides, diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index 91964d0..6f8f243 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -70,7 +70,7 @@ is a separate error indicator for each thread. Do not compare the return value to a specific exception; use :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could easily fail since the exception may be an instance instead of a class, in the - case of a class exception, or it may the a subclass of the expected exception.) + case of a class exception, or it may be a subclass of the expected exception.) .. c:function:: int PyErr_ExceptionMatches(PyObject *exc) diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst index 46fc93f..d78b43d 100644 --- a/Doc/c-api/init.rst +++ b/Doc/c-api/init.rst @@ -642,7 +642,7 @@ with sub-interpreters: .. versionadded:: 2.3 -.. c:function:: PyThreadState PyGILState_GetThisThreadState() +.. c:function:: PyThreadState* PyGILState_GetThisThreadState() Get the current thread state for this thread. May return ``NULL`` if no GILState API has been used on the current thread. Note that the main thread @@ -1136,7 +1136,7 @@ These functions are only intended to be used by advanced debugging tools. .. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp) - Return the a pointer to the first :c:type:`PyThreadState` object in the list of + Return the pointer to the first :c:type:`PyThreadState` object in the list of threads associated with the interpreter *interp*. .. versionadded:: 2.2 diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index e31687f..c193510 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -122,7 +122,7 @@ The :attr:`ml_meth` is a C function pointer. The functions may be of different types, but they always return :c:type:`PyObject\*`. If the function is not of the :c:type:`PyCFunction`, the compiler will require a cast in the method table. Even though :c:type:`PyCFunction` defines the first parameter as -:c:type:`PyObject\*`, it is common that the method implementation uses a the +:c:type:`PyObject\*`, it is common that the method implementation uses the specific C type of the *self* object. The :attr:`ml_flags` field is a bitfield which can include the following flags. diff --git a/Doc/c-api/unicode.rst b/Doc/c-api/unicode.rst index 8932915..13a2807 100644 --- a/Doc/c-api/unicode.rst +++ b/Doc/c-api/unicode.rst @@ -547,7 +547,7 @@ These are the UTF-32 codec APIs: After completion, *\*byteorder* is set to the current byte order at the end of input data. - In a narrow build codepoints outside the BMP will be decoded as surrogate pairs. + In a narrow build code points outside the BMP will be decoded as surrogate pairs. If *byteorder* is *NULL*, the codec starts in native order mode. @@ -580,7 +580,7 @@ These are the UTF-32 codec APIs: mark (U+FEFF). In the other two modes, no BOM mark is prepended. If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output - as a single codepoint. + as a single code point. Return *NULL* if an exception was raised by the codec. diff --git a/Doc/copyright.rst b/Doc/copyright.rst index be47e8a..2b2f887 100644 --- a/Doc/copyright.rst +++ b/Doc/copyright.rst @@ -4,7 +4,7 @@ Copyright Python and this documentation is: -Copyright © 2001-2014 Python Software Foundation. All rights reserved. +Copyright © 2001-2015 Python Software Foundation. All rights reserved. Copyright © 2000 BeOpen.com. All rights reserved. diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 2a75a46..8366d8a 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -970,7 +970,7 @@ directories. .. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) Create all the empty directories under *base_dir* needed to put *files* there. - *base_dir* is just the a name of a directory which doesn't necessarily exist + *base_dir* is just the name of a directory which doesn't necessarily exist yet; *files* is a list of filenames to be interpreted relative to *base_dir*. *base_dir* + the directory portion of every file in *files* will be created if it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst index 5488ce9..4b23463 100644 --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -20,12 +20,17 @@ source file by including the header ``"Python.h"``. The compilation of an extension module depends on its intended use as well as on your system setup; details are given in later chapters. -Do note that if your use case is calling C library functions or system calls, -you should consider using the :mod:`ctypes` module rather than writing custom -C code. Not only does :mod:`ctypes` let you write Python code to interface -with C code, but it is more portable between implementations of Python than -writing and compiling an extension module which typically ties you to CPython. +.. note:: + The C extension interface is specific to CPython, and extension modules do + not work on other Python implementations. In many cases, it is possible to + avoid writing C extensions and preserve portability to other implementations. + For example, if your use case is calling C library functions or system calls, + you should consider using the :mod:`ctypes` module or the `cffi + `_ library rather than writing custom C code. + These modules let you write Python code to interface with C code and are more + portable between implementations of Python than writing and compiling a C + extension module. .. _extending-simpleexample: diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 5d69dd4..010fdf2 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -284,7 +284,7 @@ Glossary generator A function which returns an iterator. It looks like a normal function except that it contains :keyword:`yield` statements for producing a series - a values usable in a for-loop or that can be retrieved one at a time with + of values usable in a for-loop or that can be retrieved one at a time with 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 diff --git a/Doc/howto/logging-cookbook.rst b/Doc/howto/logging-cookbook.rst index 69fdcca..f0a3221 100644 --- a/Doc/howto/logging-cookbook.rst +++ b/Doc/howto/logging-cookbook.rst @@ -1059,3 +1059,112 @@ A couple of extra points to note: information on how logging supports using user-defined objects in its configuration, and see the other cookbook recipe :ref:`custom-handlers` above. + +.. _custom-format-exception: + +Customized exception formatting +------------------------------- + +There might be times when you want to do customized exception formatting - for +argument's sake, let's say you want exactly one line per logged event, even +when exception information is present. You can do this with a custom formatter +class, as shown in the following example:: + + import logging + + class OneLineExceptionFormatter(logging.Formatter): + def formatException(self, exc_info): + """ + Format an exception so that it prints on a single line. + """ + result = super(OneLineExceptionFormatter, self).formatException(exc_info) + return repr(result) # or format into one line however you want to + + def format(self, record): + s = super(OneLineExceptionFormatter, self).format(record) + if record.exc_text: + s = s.replace('\n', '') + '|' + return s + + def configure_logging(): + fh = logging.FileHandler('output.txt', 'w') + f = OneLineExceptionFormatter('%(asctime)s|%(levelname)s|%(message)s|', + '%d/%m/%Y %H:%M:%S') + fh.setFormatter(f) + root = logging.getLogger() + root.setLevel(logging.DEBUG) + root.addHandler(fh) + + def main(): + configure_logging() + logging.info('Sample message') + try: + x = 1 / 0 + except ZeroDivisionError as e: + logging.exception('ZeroDivisionError: %s', e) + + if __name__ == '__main__': + main() + +When run, this produces a file with exactly two lines:: + + 28/01/2015 07:21:23|INFO|Sample message| + 28/01/2015 07:21:23|ERROR|ZeroDivisionError: integer division or modulo by zero|'Traceback (most recent call last):\n File "logtest7.py", line 30, in main\n x = 1 / 0\nZeroDivisionError: integer division or modulo by zero'| + +While the above treatment is simplistic, it points the way to how exception +information can be formatted to your liking. The :mod:`traceback` module may be +helpful for more specialized needs. + +.. _spoken-messages: + +Speaking logging messages +------------------------- + +There might be situations when it is desirable to have logging messages rendered +in an audible rather than a visible format. This is easy to do if you have text- +to-speech (TTS) functionality available in your system, even if it doesn't have +a Python binding. Most TTS systems have a command line program you can run, and +this can be invoked from a handler using :mod:`subprocess`. It's assumed here +that TTS command line programs won't expect to interact with users or take a +long time to complete, and that the frequency of logged messages will be not so +high as to swamp the user with messages, and that it's acceptable to have the +messages spoken one at a time rather than concurrently, The example implementation +below waits for one message to be spoken before the next is processed, and this +might cause other handlers to be kept waiting. Here is a short example showing +the approach, which assumes that the ``espeak`` TTS package is available:: + + import logging + import subprocess + import sys + + class TTSHandler(logging.Handler): + def emit(self, record): + msg = self.format(record) + # Speak slowly in a female English voice + cmd = ['espeak', '-s150', '-ven+f3', msg] + p = subprocess.Popen(cmd, stdout=subprocess.PIPE, + stderr=subprocess.STDOUT) + # wait for the program to finish + p.communicate() + + def configure_logging(): + h = TTSHandler() + root = logging.getLogger() + root.addHandler(h) + # the default formatter just returns the message + root.setLevel(logging.DEBUG) + + def main(): + logging.info('Hello') + logging.debug('Goodbye') + + if __name__ == '__main__': + configure_logging() + sys.exit(main()) + +When run, this script should say "Hello" and then "Goodbye" in a female voice. + +The above approach can, of course, be adapted to other TTS systems and even +other systems altogether which can process messages via external programs run +from a command line. + diff --git a/Doc/howto/pyporting.rst b/Doc/howto/pyporting.rst index 212853e..bd80dfd 100644 --- a/Doc/howto/pyporting.rst +++ b/Doc/howto/pyporting.rst @@ -19,599 +19,374 @@ Porting Python 2 Code to Python 3 If you would like to read one core Python developer's take on why Python 3 came into existence, you can read Nick Coghlan's `Python 3 Q & A`_. - If you prefer to read a (free) book on porting a project to Python 3, - consider reading `Porting to Python 3`_ by Lennart Regebro which should cover - much of what is discussed in this HOWTO. - For help with porting, you can email the python-porting_ mailing list with questions. -The Short Version -================= - -* Decide what's the oldest version of Python 2 you want to support (if at all) -* Make sure you have a thorough test suite and use continuous integration - testing to make sure you stay compatible with the versions of Python you care - about -* If you have dependencies, check their Python 3 status using caniusepython3 - (`command-line tool `__, - `web app `__) - -With that done, your options are: - -* If you are dropping Python 2 support, use :ref:`2to3 <2to3-reference>` to port - to Python 3 - -* If you are keeping Python 2 support, then start writing Python 2/3-compatible - code starting **TODAY** - - + If you have dependencies that have not been ported, reach out to them to port - their project while working to make your code compatible with Python 3 so - you're ready when your dependencies are all ported - + If all your dependencies have been ported (or you have none), go ahead and - port to Python 3 - -* If you are creating a new project that wants to have 2/3 compatibility, - code in Python 3 and then backport to Python 2 - - -Before You Begin -================ - -If your project is on the Cheeseshop_/PyPI_, make sure it has the proper -`trove classifiers`_ to signify what versions of Python it **currently** -supports. At minimum you should specify the major version(s), e.g. -``Programming Language :: Python :: 2`` if your project currently only supports -Python 2. It is preferrable that you be as specific as possible by listing every -major/minor version of Python that you support, e.g. if your project supports -Python 2.6 and 2.7, then you want the classifiers of:: - - Programming Language :: Python :: 2 - Programming Language :: Python :: 2.6 - Programming Language :: Python :: 2.7 - -Once your project supports Python 3 you will want to go back and add the -appropriate classifiers for Python 3 as well. This is important as setting the -``Programming Language :: Python :: 3`` classifier will lead to your project -being listed under the `Python 3 Packages`_ section of PyPI. - -Make sure you have a robust test suite. You need to -make sure everything continues to work, just like when you support a new -minor/feature release of Python. This means making sure your test suite is -thorough and is ported properly between Python 2 & 3 (consider using coverage_ -to measure that you have effective test coverage). You will also most likely -want to use something like tox_ to automate testing between all of your -supported versions of Python. You will also want to **port your tests first** so -that you can make sure that you detect breakage during the transition. Tests also -tend to be simpler than the code they are testing so it gives you an idea of how -easy it can be to port code. - -Drop support for older Python versions if possible. Python 2.5 -introduced a lot of useful syntax and libraries which have become idiomatic -in Python 3. Python 2.6 introduced future statements which makes -compatibility much easier if you are going from Python 2 to 3. -Python 2.7 continues the trend in the stdlib. Choose the newest version -of Python which you believe can be your minimum support version -and work from there. - -Target the newest version of Python 3 that you can. Beyond just the usual -bugfixes, compatibility has continued to improve between Python 2 and 3 as time -has passed. E.g. Python 3.3 added back the ``u`` prefix for -strings, making source-compatible Python code easier to write. - - -Writing Source-Compatible Python 2/3 Code -========================================= - -Over the years the Python community has discovered that the easiest way to -support both Python 2 and 3 in parallel is to write Python code that works in -either version. While this might sound counter-intuitive at first, it actually -is not difficult and typically only requires following some select -(non-idiomatic) practices and using some key projects to help make bridging -between Python 2 and 3 easier. - -Projects to Consider --------------------- - -The lowest level library for supporting Python 2 & 3 simultaneously is six_. -Reading through its documentation will give you an idea of where exactly the -Python language changed between versions 2 & 3 and thus what you will want the -library to help you continue to support. - -To help automate porting your code over to using six, you can use -modernize_. This project will attempt to rewrite your code to be as modern as -possible while using six to smooth out any differences between Python 2 & 3. - -If you want to write your compatible code to feel more like Python 3 there is -the future_ project. It tries to provide backports of objects from Python 3 so -that you can use them from Python 2-compatible code, e.g. replacing the -``bytes`` type from Python 2 with the one from Python 3. -It also provides a translation script like modernize (its translation code is -actually partially based on it) to help start working with a pre-existing code -base. It is also unique in that its translation script will also port Python 3 -code backwards as well as Python 2 code forwards. - - -Tips & Tricks -------------- - -To help with writing source-compatible code using one of the projects mentioned -in `Projects to Consider`_, consider following the below suggestions. Some of -them are handled by the suggested projects, so if you do use one of them then -read their documentation first to see which suggestions below will taken care of -for you. - -Support Python 2.7 -////////////////// - -As a first step, make sure that your project is compatible with Python 2.7. -This is just good to do as Python 2.7 is the last release of Python 2 and thus -will be used for a rather long time. It also allows for use of the ``-3`` flag -to Python to help discover places in your code where compatibility might be an -issue (the ``-3`` flag is in Python 2.6 but Python 2.7 adds more warnings). - -Try to Support Python 2.6 and Newer Only -//////////////////////////////////////// - -While not possible for all projects, if you can support Python 2.6 and newer -**only**, your life will be much easier. Various future statements, stdlib -additions, etc. exist only in Python 2.6 and later which greatly assist in -supporting Python 3. But if you project must keep support for Python 2.5 then -it is still possible to simultaneously support Python 3. - -Below are the benefits you gain if you only have to support Python 2.6 and -newer. Some of these options are personal choice while others are -**strongly** recommended (the ones that are more for personal choice are -labeled as such). If you continue to support older versions of Python then you -at least need to watch out for situations that these solutions fix and handle -them appropriately (which is where library help from e.g. six_ comes in handy). - - -``from __future__ import print_function`` -''''''''''''''''''''''''''''''''''''''''' - -It will not only get you used to typing ``print()`` as a function instead of a -statement, but it will also give you the various benefits the function has over -the Python 2 statement (six_ provides a function if you support Python 2.5 or -older). - - -``from __future__ import unicode_literals`` -''''''''''''''''''''''''''''''''''''''''''' - -If you choose to use this future statement then all string literals in -Python 2 will be assumed to be Unicode (as is already the case in Python 3). -If you choose not to use this future statement then you should mark all of your -text strings with a ``u`` prefix and only support Python 3.3 or newer. But you -are **strongly** advised to do one or the other (six_ provides a function in -case you don't want to use the future statement **and** you want to support -Python 3.2 or older). - - -Bytes/string literals -''''''''''''''''''''' - -This is a **very** important one. Prefix Python 2 strings that -are meant to contain bytes with a ``b`` prefix to very clearly delineate -what is and is not a Python 3 text string (six_ provides a function to use for -Python 2.5 compatibility). - -This point cannot be stressed enough: make sure you know what all of your string -literals in Python 2 are meant to be in Python 3. Any string literal that -should be treated as bytes should have the ``b`` prefix. Any string literal -that should be Unicode/text in Python 2 should either have the ``u`` literal -(supported, but ignored, in Python 3.3 and later) or you should have -``from __future__ import unicode_literals`` at the top of the file. But the key -point is you should know how Python 3 will treat every one one of your string -literals and you should mark them as appropriate. - -There are some differences between byte literals in Python 2 and those in -Python 3 thanks to the bytes type just being an alias to ``str`` in Python 2. -See the `Handle Common "Gotchas"`_ section for what to watch out for. - -``from __future__ import absolute_import`` -'''''''''''''''''''''''''''''''''''''''''' -Discussed in more detail below, but you should use this future statement to -prevent yourself from accidentally using implicit relative imports. - - -Supporting Python 2.5 and Newer Only -//////////////////////////////////// - -If you are supporting Python 2.5 and newer there are still some features of -Python that you can utilize. - - -``from __future__ import absolute_import`` -'''''''''''''''''''''''''''''''''''''''''' - -Implicit relative imports (e.g., importing ``spam.bacon`` from within -``spam.eggs`` with the statement ``import bacon``) do not work in Python 3. -This future statement moves away from that and allows the use of explicit -relative imports (e.g., ``from . import bacon``). - -In Python 2.5 you must use -the __future__ statement to get to use explicit relative imports and prevent -implicit ones. In Python 2.6 explicit relative imports are available without -the statement, but you still want the __future__ statement to prevent implicit -relative imports. In Python 2.7 the __future__ statement is not needed. In -other words, unless you are only supporting Python 2.7 or a version earlier -than Python 2.5, use this __future__ statement. - - -Mark all Unicode strings with a ``u`` prefix -''''''''''''''''''''''''''''''''''''''''''''' - -While Python 2.6 has a ``__future__`` statement to automatically cause Python 2 -to treat all string literals as Unicode, Python 2.5 does not have that shortcut. -This means you should go through and mark all string literals with a ``u`` -prefix to turn them explicitly into text strings where appropriate and only -support Python 3.3 or newer. Otherwise use a project like six_ which provides a -function to pass all text string literals through. - - -Capturing the Currently Raised Exception -'''''''''''''''''''''''''''''''''''''''' - -In Python 2.5 and earlier the syntax to access the current exception is:: - - try: - raise Exception() - except Exception, exc: - # Current exception is 'exc'. - pass - -This syntax changed in Python 3 (and backported to Python 2.6 and later) -to:: - - try: - raise Exception() - except Exception as exc: - # Current exception is 'exc'. - # In Python 3, 'exc' is restricted to the block; in Python 2.6/2.7 it will "leak". - pass - -Because of this syntax change you must change how you capture the current -exception in Python 2.5 and earlier to:: - - try: - raise Exception() - except Exception: - import sys - exc = sys.exc_info()[1] - # Current exception is 'exc'. - pass - -You can get more information about the raised exception from -:func:`sys.exc_info` than simply the current exception instance, but you most -likely don't need it. - -.. note:: - In Python 3, the traceback is attached to the exception instance - through the ``__traceback__`` attribute. If the instance is saved in - a local variable that persists outside of the ``except`` block, the - traceback will create a reference cycle with the current frame and its - dictionary of local variables. This will delay reclaiming dead - resources until the next cyclic :term:`garbage collection` pass. - - In Python 2, this problem only occurs if you save the traceback itself - (e.g. the third element of the tuple returned by :func:`sys.exc_info`) - in a variable. - - -Handle Common "Gotchas" -/////////////////////// - -These are things to watch out for no matter what version of Python 2 you are -supporting which are not syntactic considerations. - - -``from __future__ import division`` -''''''''''''''''''''''''''''''''''' - -While the exact same outcome can be had by using the ``-Qnew`` argument to -Python, using this future statement lifts the requirement that your users use -the flag to get the expected behavior of division in Python 3 -(e.g., ``1/2 == 0.5; 1//2 == 0``). - - - -Specify when opening a file as binary -''''''''''''''''''''''''''''''''''''' - +The Short Explanation +===================== + +To make your project be single-source Python 2/3 compatible, the basic steps +are: + +#. Update your code to drop support for Python 2.5 or older (supporting only + Python 2.7 is ideal) +#. Make sure you have good test coverage (coverage.py_ can help; + ``pip install coverage``) +#. Learn the differences between Python 2 & 3 +#. Use Modernize_ or Futurize_ to update your code (``pip install modernize`` or + ``pip install future``, respectively) +#. Use Pylint_ to help make sure you don't regress on your Python 3 support + (if only supporting Python 2.7/3.4 or newer; ``pip install pylint``) +#. Use caniusepython3_ to find out which of your dependencies are blocking your + use of Python 3 (``pip install caniusepython3``) +#. Once your dependencies are no longer blocking you, use continuous integration + to make sure you stay compatible with Python 2 & 3 (tox_ can help test + against multiple versions of Python; ``pip install tox``) + +If you are dropping support for Python 2 entirely, then after you learn the +differences between Python 2 & 3 you can run 2to3_ over your code and skip the +rest of the steps outlined above. + + +Details +======= + +A key point about supporting Python 2 & 3 simultaneously is that you can start +**today**! Even if your dependencies are not supporting Python 3 yet that does +not mean you can't modernize your code **now** to support Python 3. Most changes +required to support Python 3 lead to cleaner code using newer practices even in +Python 2. + +Another key point is that modernizing your Python 2 code to also support +Python 3 is largely automated for you. While you might have to make some API +decisions thanks to Python 3 clarifying text data versus binary data, the +lower-level work is now mostly done for you and thus can at least benefit from +the automated changes immediately. + +Keep those key points in mind while you read on about the details of porting +your code to support Python 2 & 3 simultaneously. + + +Drop support for Python 2.5 and older (at least) +------------------------------------------------ + +While you can make Python 2.5 work with Python 3, it is **much** easier if you +only have to work with Python 2.6 or newer (and easier still if you only have +to work with Python 2.7). If dropping Python 2.5 is not an option then the six_ +project can help you support Python 2.5 & 3 simultaneously +(``pip install six``). Do realize, though, that nearly all the projects listed +in this HOWTO will not be available to you. + +If you are able to only support Python 2.6 or newer, then the required changes +to your code should continue to look and feel like idiomatic Python code. At +worst you will have to use a function instead of a method in some instances or +have to import a function instead of using a built-in one, but otherwise the +overall transformation should not feel foreign to you. + +But please aim for Python 2.7. Bugfixes for that version of Python will continue +until 2020 while Python 2.6 is no longer supported. There are also some tools +mentioned in this HOWTO which do not support Python 2.6 (e.g., Pylint_), and +this will become more commonplace as time goes on. + +Make sure you specify the proper version support in your ``setup.py`` file +-------------------------------------------------------------------------- + +In your ``setup.py`` file you should have the proper `trove classifier`_ +specifying what versions of Python you support. As your project does not support +Python 3 yet you should at least have +``Programming Language :: Python :: 2 :: Only`` specified. Ideally you should +also specify each major/minor version of Python that you do support, e.g. +``Programming Language :: Python :: 2.7``. + +Have good test coverage +----------------------- + +Once you have your code supporting the oldest version of Python 2 you want it +to, you will want to make sure your test suite has good coverage. A good rule of +thumb is that if you want to be confident enough in your test suite that any +failures that appear after having tools rewrite your code are actual bugs in the +tools and not in your code. If you want a number to aim for, try to get over 80% +coverage (and don't feel bad if you can't easily get past 90%). If you +don't already have a tool to measure test coverage then coverage.py_ is +recommended. + +Learn the differences between Python 2 & 3 +------------------------------------------- + +Once you have your code well-tested you are ready to begin porting your code to +Python 3! But to fully understand how your code is going to change and what +you want to look out for while you code, you will want to learn what changes +Python 3 makes in terms of Python 2. Typically the two best ways of doing that +is reading the `"What's New"`_ doc for each release of Python 3 and the +`Porting to Python 3`_ book (which is free online). There is also a handy +`cheat sheet`_ from the Python-Future project. + + +Update your code +---------------- + +Once you feel like you know what is different in Python 3 compared to Python 2, +it's time to update your code! You have a choice between two tools in porting +your code automatically: Modernize_ and Futurize_. Which tool you choose will +depend on how much like Python 3 you want your code to be. Futurize_ does its +best to make Python 3 idioms and practices exist in Python 2, e.g. backporting +the ``bytes`` type from Python 3 so that you have semantic parity between the +major versions of Python. Modernize_, +on the other hand, is more conservative and targets a Python 2/3 subset of +Python, relying on six_ to help provide compatibility. + +Regardless of which tool you choose, they will update your code to run under +Python 3 while staying compatible with the version of Python 2 you started with. +Depending on how conservative you want to be, you may want to run the tool over +your test suite first and visually inspect the diff to make sure the +transformation is accurate. After you have transformed your test suite and +verified that all the tests still pass as expected, then you can transform your +application code knowing that any tests which fail is a translation failure. + +Unfortunately the tools can't automate everything to make your code work under +Python 3 and so there are a handful of things you will need to update manually +to get full Python 3 support (which of these steps are necessary vary between +the tools). Read the documentation for the tool you choose to use to see what it +fixes by default and what it can do optionally to know what will (not) be fixed +for you and what you may have to fix on your own (e.g. using ``io.open()`` over +the built-in ``open()`` function is off by default in Modernize). Luckily, +though, there are only a couple of things to watch out for which can be +considered large issues that may be hard to debug if not watched for. + +Division +++++++++ + +In Python 3, ``5 / 2 == 2.5`` and not ``2``; all division between ``int`` values +result in a ``float``. This change has actually been planned since Python 2.2 +which was released in 2002. Since then users have been encouraged to add +``from __future__ import division`` to any and all files which use the ``/`` and +``//`` operators or to be running the interpreter with the ``-Q`` flag. If you +have not been doing this then you will need to go through your code and do two +things: + +#. Add ``from __future__ import division`` to your files +#. Update any division operator as necessary to either use ``//`` to use floor + division or continue using ``/`` and expect a float + +The reason that ``/`` isn't simply translated to ``//`` automatically is that if +an object defines its own ``__div__`` method but not ``__floordiv__`` then your +code would begin to fail. + +Text versus binary data ++++++++++++++++++++++++ + +In Python 2 you could use the ``str`` type for both text and binary data. +Unfortunately this confluence of two different concepts could lead to brittle +code which sometimes worked for either kind of data, sometimes not. It also +could lead to confusing APIs if people didn't explicitly state that something +that accepted ``str`` accepted either text or binary data instead of one +specific type. This complicated the situation especially for anyone supporting +multiple languages as APIs wouldn't bother explicitly supporting ``unicode`` +when they claimed text data support. + +To make the distinction between text and binary data clearer and more +pronounced, Python 3 did what most languages created in the age of the internet +have done and made text and binary data distinct types that cannot blindly be +mixed together (Python predates widespread access to the internet). For any code +that only deals with text or only binary data, this separation doesn't pose an +issue. But for code that has to deal with both, it does mean you might have to +now care about when you are using text compared to binary data, which is why +this cannot be entirely automated. + +To start, you will need to decide which APIs take text and which take binary +(it is **highly** recommended you don't design APIs that can take both due to +the difficulty of keeping the code working; as stated earlier it is difficult to +do well). In Python 2 this means making sure the APIs that take text can work +with ``unicode`` in Python 2 and those that work with binary data work with the +``bytes`` type from Python 3 and thus a subset of ``str`` in Python 2 (which the +``bytes`` type in Python 2 is an alias for). Usually the biggest issue is +realizing which methods exist for which types in Python 2 & 3 simultaneously +(for text that's ``unicode`` in Python 2 and ``str`` in Python 3, for binary +that's ``str``/``bytes`` in Python 2 and ``bytes`` in Python 3). The following +table lists the **unique** methods of each data type across Python 2 & 3 +(e.g., the ``decode()`` method is usable on the equivalent binary data type in +either Python 2 or 3, but it can't be used by the text data type consistently +between Python 2 and 3 because ``str`` in Python 3 doesn't have the method). + +======================== ===================== +**Text data** **Binary data** +------------------------ --------------------- +__mod__ (``%`` operator) +------------------------ --------------------- +\ decode +------------------------ --------------------- +encode +------------------------ --------------------- +format +------------------------ --------------------- +isdecimal +------------------------ --------------------- +isnumeric +======================== ===================== + +Making the distinction easier to handle can be accomplished by encoding and +decoding between binary data and text at the edge of your code. This means that +when you receive text in binary data, you should immediately decode it. And if +your code needs to send text as binary data then encode it as late as possible. +This allows your code to work with only text internally and thus eliminates +having to keep track of what type of data you are working with. + +The next issue is making sure you know whether the string literals in your code +represent text or binary data. At minimum you should add a ``b`` prefix to any +literal that presents binary data. For text you should either use the +``from __future__ import unicode_literals`` statement or add a ``u`` prefix to +the text literal. + +As part of this dichotomy you also need to be careful about opening files. Unless you have been working on Windows, there is a chance you have not always bothered to add the ``b`` mode when opening a binary file (e.g., ``rb`` for binary reading). Under Python 3, binary files and text files are clearly distinct and mutually incompatible; see the :mod:`io` module for details. Therefore, you **must** make a decision of whether a file will be used for -binary access (allowing to read and/or write bytes data) or text access -(allowing to read and/or write unicode data). - -Text files -'''''''''' - -Text files created using ``open()`` under Python 2 return byte strings, -while under Python 3 they return unicode strings. Depending on your porting -strategy, this can be an issue. - -If you want text files to return unicode strings in Python 2, you have two -possibilities: - -* Under Python 2.6 and higher, use :func:`io.open`. Since :func:`io.open` - is essentially the same function in both Python 2 and Python 3, it will - help iron out any issues that might arise. - -* If pre-2.6 compatibility is needed, then you should use :func:`codecs.open` - instead. This will make sure that you get back unicode strings in Python 2. - -Subclass ``object`` -''''''''''''''''''' - -New-style classes have been around since Python 2.2. You need to make sure -you are subclassing from ``object`` to avoid odd edge cases involving method -resolution order, etc. This continues to be totally valid in Python 3 (although -unneeded as all classes implicitly inherit from ``object``). - - -Deal With the Bytes/String Dichotomy -'''''''''''''''''''''''''''''''''''' - -One of the biggest issues people have when porting code to Python 3 is handling -the bytes/string dichotomy. Because Python 2 allowed the ``str`` type to hold -textual data, people have over the years been rather loose in their delineation -of what ``str`` instances held text compared to bytes. In Python 3 you cannot -be so care-free anymore and need to properly handle the difference. The key to -handling this issue is to make sure that **every** string literal in your -Python 2 code is either syntactically or functionally marked as either bytes or -text data. After this is done you then need to make sure your APIs are designed -to either handle a specific type or made to be properly polymorphic. - - -Mark Up Python 2 String Literals -******************************** - -First thing you must do is designate every single string literal in Python 2 -as either textual or bytes data. If you are only supporting Python 2.6 or -newer, this can be accomplished by marking bytes literals with a ``b`` prefix -and then designating textual data with a ``u`` prefix or using the -``unicode_literals`` future statement. - -If your project supports versions of Python predating 2.6, then you should use -the six_ project and its ``b()`` function to denote bytes literals. For text -literals you can either use six's ``u()`` function or use a ``u`` prefix. - - -Decide what APIs Will Accept -**************************** - -In Python 2 it was very easy to accidentally create an API that accepted both -bytes and textual data. But in Python 3, thanks to the more strict handling of -disparate types, this loose usage of bytes and text together tends to fail. - -Take the dict ``{b'a': 'bytes', u'a': 'text'}`` in Python 2.6. It creates the -dict ``{u'a': 'text'}`` since ``b'a' == u'a'``. But in Python 3 the equivalent -dict creates ``{b'a': 'bytes', 'a': 'text'}``, i.e., no lost data. Similar -issues can crop up when transitioning Python 2 code to Python 3. - -This means you need to choose what an API is going to accept and create and -consistently stick to that API in both Python 2 and 3. - - -Bytes / Unicode Comparison -************************** - -In Python 3, mixing bytes and unicode is forbidden in most situations; it -will raise a :class:`TypeError` where Python 2 would have attempted an implicit -coercion between types. However, there is one case where it doesn't and -it can be very misleading:: - - >>> b"" == "" - False - -This is because an equality comparison is required by the language to always -succeed (and return ``False`` for incompatible types). However, this also -means that code incorrectly ported to Python 3 can display buggy behaviour -if such comparisons are silently executed. To detect such situations, -Python 3 has a ``-b`` flag that will display a warning:: - - $ python3 -b - >>> b"" == "" - __main__:1: BytesWarning: Comparison between bytes and string - False - -To turn the warning into an exception, use the ``-bb`` flag instead:: - - $ python3 -bb - >>> b"" == "" - Traceback (most recent call last): - File "", line 1, in - BytesWarning: Comparison between bytes and string - - -Indexing bytes objects -'''''''''''''''''''''' - -Another potentially surprising change is the indexing behaviour of bytes -objects in Python 3:: - - >>> b"xyz"[0] - 120 - -Indeed, Python 3 bytes objects (as well as :class:`bytearray` objects) -are sequences of integers. But code converted from Python 2 will often -assume that indexing a bytestring produces another bytestring, not an -integer. To reconcile both behaviours, use slicing:: - - >>> b"xyz"[0:1] - b'x' - >>> n = 1 - >>> b"xyz"[n:n+1] - b'y' - -The only remaining gotcha is that an out-of-bounds slice returns an empty -bytes object instead of raising ``IndexError``: - - >>> b"xyz"[3] - Traceback (most recent call last): - File "", line 1, in - IndexError: index out of range - >>> b"xyz"[3:4] - b'' - - -``__str__()``/``__unicode__()`` -''''''''''''''''''''''''''''''' - -In Python 2, objects can specify both a string and unicode representation of -themselves. In Python 3, though, there is only a string representation. This -becomes an issue as people can inadvertently do things in their ``__str__()`` -methods which have unpredictable results (e.g., infinite recursion if you -happen to use the ``unicode(self).encode('utf8')`` idiom as the body of your -``__str__()`` method). - -You can use a mixin class to work around this. This allows you to only define a -``__unicode__()`` method for your class and let the mixin derive -``__str__()`` for you (code from -http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/):: - - import sys - - class UnicodeMixin(object): - - """Mixin class to handle defining the proper __str__/__unicode__ - methods in Python 2 or 3.""" - - if sys.version_info[0] >= 3: # Python 3 - def __str__(self): - return self.__unicode__() - else: # Python 2 - def __str__(self): - return self.__unicode__().encode('utf8') - - - class Spam(UnicodeMixin): - - def __unicode__(self): - return u'spam-spam-bacon-spam' # 2to3 will remove the 'u' prefix - - -Don't Index on Exceptions -''''''''''''''''''''''''' - -In Python 2, the following worked:: - - >>> exc = Exception(1, 2, 3) - >>> exc.args[1] - 2 - >>> exc[1] # Python 2 only! - 2 - -But in Python 3, indexing directly on an exception is an error. You need to -make sure to only index on the :attr:`BaseException.args` attribute which is a -sequence containing all arguments passed to the :meth:`__init__` method. - -Even better is to use the documented attributes the exception provides. - - -Don't use ``__getslice__`` & Friends -'''''''''''''''''''''''''''''''''''' - -Been deprecated for a while, but Python 3 finally drops support for -``__getslice__()``, etc. Move completely over to :meth:`__getitem__` and -friends. - - -Updating doctests -''''''''''''''''' - -Don't forget to make them Python 2/3 compatible as well. If you wrote a -monolithic set of doctests (e.g., a single docstring containing all of your -doctests), you should at least consider breaking the doctests up into smaller -pieces to make it more manageable to fix. Otherwise it might very well be worth -your time and effort to port your tests to :mod:`unittest`. - - -Update ``map`` for imbalanced input sequences -''''''''''''''''''''''''''''''''''''''''''''' - -With Python 2, when ``map`` was given more than one input sequence it would pad -the shorter sequences with ``None`` values, returning a sequence as long as the -longest input sequence. - -With Python 3, if the input sequences to ``map`` are of unequal length, ``map`` -will stop at the termination of the shortest of the sequences. For full -compatibility with ``map`` from Python 2.x, wrap the sequence arguments in -:func:`itertools.zip_longest`, e.g. ``map(func, *sequences)`` becomes -``list(map(func, itertools.zip_longest(*sequences)))``. - -Eliminate ``-3`` Warnings -------------------------- - -When you run your application's test suite, run it using the ``-3`` flag passed -to Python. This will cause various warnings to be raised during execution about -things that are semantic changes between Python 2 and 3. Try to eliminate those -warnings to make your code even more portable to Python 3. - - -Alternative Approaches -====================== - -While supporting Python 2 & 3 simultaneously is typically the preferred choice -by people so that they can continue to improve code and have it work for the -most number of users, your life may be easier if you only have to support one -major version of Python going forward. - -Supporting Only Python 3 Going Forward From Python 2 Code ---------------------------------------------------------- - -If you have Python 2 code but going forward only want to improve it as Python 3 -code, then you can use :ref:`2to3 <2to3-reference>` to translate your Python 2 -code to Python 3 code. This is only recommended, though, if your current -version of your project is going into maintenance mode and you want all new features to be exclusive to Python 3. - - -Backporting Python 3 code to Python 2 -------------------------------------- - -If you have Python 3 code and have little interest in supporting Python 2 you -can use 3to2_ to translate from Python 3 code to Python 2 code. This is only -recommended if you don't plan to heavily support Python 2 users. Otherwise -write your code for Python 3 and then backport as far back as you want. This -is typically easier than going from Python 2 to 3 as you will have worked out -any difficulties with e.g. bytes/strings, etc. - - -Other Resources -=============== - -The authors of the following blog posts, wiki pages, and books deserve special -thanks for making public their tips for porting Python 2 code to Python 3 (and -thus helping provide information for this document and its various revisions -over the years): - -* https://wiki.python.org/moin/PortingPythonToPy3k -* http://python3porting.com/ -* http://docs.pythonsprints.com/python3_porting/py-porting.html -* http://techspot.zzzeek.org/2011/01/24/zzzeek-s-guide-to-python-3-porting/ -* http://dabeaz.blogspot.com/2011/01/porting-py65-and-my-superboard-to.html -* http://lucumr.pocoo.org/2011/1/22/forwards-compatible-python/ -* http://lucumr.pocoo.org/2010/2/11/porting-to-python-3-a-guide/ -* https://wiki.ubuntu.com/Python/3 - -If you feel there is something missing from this document that should be added, -please email the python-porting_ mailing list. - - -.. _3to2: https://pypi.python.org/pypi/3to2 -.. _Cheeseshop: PyPI_ -.. _coverage: https://pypi.python.org/pypi/coverage -.. _future: http://python-future.org/ -.. _modernize: https://github.com/mitsuhiko/python-modernize +binary access (allowing to read and/or write binary data) or text access +(allowing to read and/or write text data). You should also use :func:`io.open` +for opening files instead of the built-in :func:`open` function as the :mod:`io` +module is consistent from Python 2 to 3 while the built-in :func:`open` function +is not (in Python 3 it's actually :func:`io.open`). + +The constructors of both ``str`` and ``bytes`` have different semantics for the +same arguments between Python 2 & 3. Passing an integer to ``bytes`` in Python 2 +will give you the string representation of the integer: ``bytes(3) == '3'``. +But in Python 3, an integer argument to ``bytes`` will give you a bytes object +as long as the integer specified, filled with null bytes: +``bytes(3) == b'\x00\x00\x00'``. A similar worry is necessary when passing a +bytes object to ``str``. In Python 2 you just get the bytes object back: +``str(b'3') == b'3'``. But in Python 3 you get the string representation of the +bytes object: ``str(b'3') == "b'3'"``. + +Finally, the indexing of binary data requires careful handling (slicing does +**not** require any special handling). In Python 2, +``b'123'[1] == b'2'`` while in Python 3 ``b'123'[1] == 50``. Because binary data +is simply a collection of binary numbers, Python 3 returns the integer value for +the byte you index on. But in Python 2 because ``bytes == str``, indexing +returns a one-item slice of bytes. The six_ project has a function +named ``six.indexbytes()`` which will return an integer like in Python 3: +``six.indexbytes(b'123', 1)``. + +To summarize: + +#. Decide which of your APIs take text and which take binary data +#. Make sure that your code that works with text also works with ``unicode`` and + code for binary data works with ``bytes`` in Python 2 (see the table above + for what methods you cannot use for each type) +#. Mark all binary literals with a ``b`` prefix, use a ``u`` prefix or + :mod:`__future__` import statement for text literals +#. Decode binary data to text as soon as possible, encode text as binary data as + late as possible +#. Open files using :func:`io.open` and make sure to specify the ``b`` mode when + appropriate +#. Be careful when indexing binary data + +Prevent compatibility regressions +--------------------------------- + +Once you have fully translated your code to be compatible with Python 3, you +will want to make sure your code doesn't regress and stop working under +Python 3. This is especially true if you have a dependency which is blocking you +from actually running under Python 3 at the moment. + +To help with staying compatible, any new modules you create should have +at least the following block of code at the top of it:: + + from __future__ import absolute_import + from __future__ import division + from __future__ import print_function + from __future__ import unicode_literals + +You can also run Python 2 with the ``-3`` flag to be warned about various +compatibility issues your code triggers during execution. If you turn warnings +into errors with ``-Werror`` then you can make sure that you don't accidentally +miss a warning. + + +You can also use the Pylint_ project and its ``--py3k`` flag to lint your code +to receive warnings when your code begins to deviate from Python 3 +compatibility. This also prevents you from having to run Modernize_ or Futurize_ +over your code regularly to catch compatibility regressions. This does require +you only support Python 2.7 and Python 3.4 or newer as that is Pylint's +minimum Python version support. + + +Check which dependencies block your transition +---------------------------------------------- + +**After** you have made your code compatible with Python 3 you should begin to +care about whether your dependencies have also been ported. The caniusepython3_ +project was created to help you determine which projects +-- directly or indirectly -- are blocking you from supporting Python 3. There +is both a command-line tool as well as a web interface at +https://caniusepython3.com . + +The project also provides code which you can integrate into your test suite so +that you will have a failing test when you no longer have dependencies blocking +you from using Python 3. This allows you to avoid having to manually check your +dependencies and to be notified quickly when you can start running on Python 3. + +Update your ``setup.py`` file to denote Python 3 compatibility +-------------------------------------------------------------- + +Once your code works under Python 3, you should update the classifiers in +your ``setup.py`` to contain ``Programming Language :: Python :: 3`` and to not +specify sole Python 2 support. This will tell +anyone using your code that you support Python 2 **and** 3. Ideally you will +also want to add classifiers for each major/minor version of Python you now +support. + +Use continuous integration to stay compatible +--------------------------------------------- + +Once you are able to fully run under Python 3 you will want to make sure your +code always works under both Python 2 & 3. Probably the best tool for running +your tests under multiple Python interpreters is tox_. You can then integrate +tox with your continuous integration system so that you never accidentally break +Python 2 or 3 support. + +You may also want to use use the ``-bb`` flag with the Python 3 interpreter to +trigger an exception when you are comparing bytes to strings. Usually it's +simply ``False``, but if you made a mistake in your separation of text/binary +data handling you may be accidentally comparing text and binary data. This flag +will raise an exception when that occurs to help track down such cases. + +And that's mostly it! At this point your code base is compatible with both +Python 2 and 3 simultaneously. Your testing will also be set up so that you +don't accidentally break Python 2 or 3 compatibility regardless of which version +you typically run your tests under while developing. + + +Dropping Python 2 support completely +==================================== + +If you are able to fully drop support for Python 2, then the steps required +to transition to Python 3 simplify greatly. + +#. Update your code to only support Python 2.7 +#. Make sure you have good test coverage (coverage.py_ can help) +#. Learn the differences between Python 2 & 3 +#. Use 2to3_ to rewrite your code to run only under Python 3 + +After this your code will be fully Python 3 compliant but in a way that is not +supported by Python 2. You should also update the classifiers in your +``setup.py`` to contain ``Programming Language :: Python :: 3 :: Only``. + + +.. _2to3: https://docs.python.org/3/library/2to3.html +.. _caniusepython3: https://pypi.python.org/pypi/caniusepython3 +.. _cheat sheet: http://python-future.org/compatible_idioms.html +.. _coverage.py: https://pypi.python.org/pypi/coverage +.. _Futurize: http://python-future.org/automatic_conversion.html +.. _Modernize: http://python-modernize.readthedocs.org/en/latest/ .. _Porting to Python 3: http://python3porting.com/ -.. _PyPI: https://pypi.python.org/pypi -.. _Python 3 Packages: https://pypi.python.org/pypi?:action=browse&c=533&show=all +.. _Pylint: https://pypi.python.org/pypi/pylint .. _Python 3 Q & A: http://ncoghlan-devs-python-notes.readthedocs.org/en/latest/python3/questions_and_answers.html + +.. _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 classifiers: https://pypi.python.org/pypi?%3Aaction=list_classifiers +.. _trove classifier: https://pypi.python.org/pypi?%3Aaction=list_classifiers +.. _"What's New": https://docs.python.org/3/whatsnew/index.html diff --git a/Doc/howto/unicode.rst b/Doc/howto/unicode.rst index 407a920..8138a09 100644 --- a/Doc/howto/unicode.rst +++ b/Doc/howto/unicode.rst @@ -32,8 +32,8 @@ For a while people just wrote programs that didn't display accents. I remember looking at Apple ][ BASIC programs, published in French-language publications in the mid-1980s, that had lines like these:: - PRINT "FICHIER EST COMPLETE." - PRINT "CARACTERE NON ACCEPTE." + PRINT "MISE A JOUR TERMINEE" + PRINT "PARAMETRES ENREGISTRES" Those messages should contain accents, and they just look wrong to someone who can read French. diff --git a/Doc/howto/webservers.rst b/Doc/howto/webservers.rst index 6534753..d8a0562 100644 --- a/Doc/howto/webservers.rst +++ b/Doc/howto/webservers.rst @@ -732,6 +732,4 @@ found in the Python wiki. `_. Most frameworks also have their own mailing lists and IRC channels, look out - for these on the projects' web sites. There is also a general "Python in the - Web" IRC channel on freenode called `#python.web - `_. + for these on the projects' web sites. diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 25005ee..9955646 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1216,8 +1216,8 @@ Action classes implement the Action API, a callable which returns a callable which processes arguments from the command-line. Any object which follows this API may be passed as the ``action`` parameter to :meth:`add_argument`. -.. class:: Action(option_strings, dest, nargs=None, const=None, default=None, - type=None, choices=None, required=False, help=None, +.. class:: Action(option_strings, dest, nargs=None, const=None, default=None, \ + type=None, choices=None, required=False, help=None, \ metavar=None) Action objects are used by an ArgumentParser to represent the information needed @@ -1499,12 +1499,15 @@ Sub-commands * parser_class - class which will be used to create sub-parser instances, by default the class of the current parser (e.g. ArgumentParser) - * dest - name of the attribute under which sub-command name will be + * action_ - the basic type of action to be taken when this argument is + encountered at the command line + + * dest_ - name of the attribute under which sub-command name will be stored; by default None and no value is stored - * help - help for sub-parser group in help output, by default None + * help_ - help for sub-parser group in help output, by default None - * metavar - string presenting available sub-commands in help; by default it + * metavar_ - string presenting available sub-commands in help; by default it is None and presents sub-commands in form {cmd1, cmd2, ..} Some example usage:: @@ -1881,10 +1884,7 @@ Customizing file parsing as an argument:: def convert_arg_line_to_args(self, arg_line): - for arg in arg_line.split(): - if not arg.strip(): - continue - yield arg + return arg_line.split() Exiting methods diff --git a/Doc/library/cmath.rst b/Doc/library/cmath.rst index 5cbb426..0a05686 100644 --- a/Doc/library/cmath.rst +++ b/Doc/library/cmath.rst @@ -161,13 +161,13 @@ Hyperbolic functions .. function:: acosh(x) - Return the hyperbolic arc cosine of *x*. There is one branch cut, extending left - from 1 along the real axis to -∞, continuous from above. + Return the inverse hyperbolic cosine of *x*. There is one branch cut, + extending left from 1 along the real axis to -∞, continuous from above. .. function:: asinh(x) - Return the hyperbolic arc sine of *x*. There are two branch cuts: + Return the inverse hyperbolic sine of *x*. There are two branch cuts: One extends from ``1j`` along the imaginary axis to ``∞j``, continuous from the right. The other extends from ``-1j`` along the imaginary axis to ``-∞j``, continuous from the left. @@ -178,7 +178,7 @@ Hyperbolic functions .. function:: atanh(x) - Return the hyperbolic arc tangent of *x*. There are two branch cuts: One + Return the inverse hyperbolic tangent of *x*. There are two branch cuts: One extends from ``1`` along the real axis to ``∞``, continuous from below. The other extends from ``-1`` along the real axis to ``-∞``, continuous from above. diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst index 05c7156..feeb236 100644 --- a/Doc/library/codecs.rst +++ b/Doc/library/codecs.rst @@ -787,7 +787,7 @@ methods and attributes from the underlying stream. Encodings and Unicode --------------------- -Unicode strings are stored internally as sequences of codepoints (to be precise +Unicode strings are stored internally as sequences of code points (to be precise as :c:type:`Py_UNICODE` arrays). Depending on the way Python is compiled (either via ``--enable-unicode=ucs2`` or ``--enable-unicode=ucs4``, with the former being the default) :c:type:`Py_UNICODE` is either a 16-bit or 32-bit data @@ -796,24 +796,24 @@ and how these arrays are stored as bytes become an issue. Transforming a unicode object into a sequence of bytes is called encoding and recreating the unicode object from the sequence of bytes is known as decoding. There are many different methods for how this transformation can be done (these methods are -also called encodings). The simplest method is to map the codepoints 0-255 to +also called encodings). The simplest method is to map the code points 0-255 to the bytes ``0x0``-``0xff``. This means that a unicode object that contains -codepoints above ``U+00FF`` can't be encoded with this method (which is called +code points above ``U+00FF`` can't be encoded with this method (which is called ``'latin-1'`` or ``'iso-8859-1'``). :func:`unicode.encode` will raise a :exc:`UnicodeEncodeError` that looks like this: ``UnicodeEncodeError: 'latin-1' codec can't encode character u'\u1234' in position 3: ordinal not in range(256)``. There's another group of encodings (the so called charmap encodings) that choose -a different subset of all unicode code points and how these codepoints are +a different subset of all unicode code points and how these code points are mapped to the bytes ``0x0``-``0xff``. To see how this is done simply open e.g. :file:`encodings/cp1252.py` (which is an encoding that is used primarily on Windows). There's a string constant with 256 characters that shows you which character is mapped to which byte value. -All of these encodings can only encode 256 of the 1114112 codepoints +All of these encodings can only encode 256 of the 1114112 code points defined in unicode. A simple and straightforward way that can store each Unicode -code point, is to store each codepoint as four consecutive bytes. There are two +code point, is to store each code point as four consecutive bytes. There are two possibilities: store the bytes in big endian or in little endian order. These two encodings are called ``UTF-32-BE`` and ``UTF-32-LE`` respectively. Their disadvantage is that if e.g. you use ``UTF-32-BE`` on a little endian machine you diff --git a/Doc/library/copy_reg.rst b/Doc/library/copy_reg.rst index 3d8ef77..b8cb530 100644 --- a/Doc/library/copy_reg.rst +++ b/Doc/library/copy_reg.rst @@ -14,7 +14,7 @@ module: cPickle module: copy -The :mod:`copy_reg` module offers a way to define fuctions used while pickling +The :mod:`copy_reg` module offers a way to define functions used while pickling specific objects. The :mod:`pickle`, :mod:`cPickle`, and :mod:`copy` modules use those functions when pickling/copying those objects. The module provides configuration information about object constructors which are not classes. diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 4276e91..0cc36e9 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -619,8 +619,8 @@ Example of working with :class:`date`: .. _datetime-datetime: -:class:`datetime` Objects -------------------------- +:class:`.datetime` Objects +-------------------------- A :class:`.datetime` object is a single object containing all the information from a :class:`date` object and a :class:`.time` object. Like a :class:`date` diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index d5ba4f0..564d10c 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -236,7 +236,7 @@ For more advanced work, it may be useful to create alternate contexts using the Context() constructor. To make an alternate active, use the :func:`setcontext` function. -In accordance with the standard, the :mod:`Decimal` module provides two ready to +In accordance with the standard, the :mod:`decimal` module provides two ready to use standard contexts, :const:`BasicContext` and :const:`ExtendedContext`. The former is especially useful for debugging because many of the traps are enabled: diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index c9f5e6b..727af41 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -9,9 +9,9 @@ -------------- The :mod:`dis` module supports the analysis of CPython :term:`bytecode` by -disassembling it. The CPython bytecode which this module takes as an -input is defined in the file :file:`Include/opcode.h` and used by the compiler -and the interpreter. +disassembling it. The CPython bytecode which this module takes as an input is +defined in the file :file:`Include/opcode.h` and used by the compiler and the +interpreter. .. impl-detail:: @@ -40,17 +40,18 @@ The :mod:`dis` module defines the following functions and constants: .. function:: dis([bytesource]) - Disassemble the *bytesource* object. *bytesource* can denote either a module, a - class, a method, a function, or a code object. For a module, it disassembles - all functions. For a class, it disassembles all methods. For a single code - sequence, it prints one line per bytecode instruction. If no object is - provided, it disassembles the last traceback. + Disassemble the *bytesource* object. *bytesource* can denote either a module, + a class, a method, a function, or a code object. For a module, it + disassembles all functions. For a class, it disassembles all methods. For a + single code sequence, it prints one line per bytecode instruction. If no + object is provided, it disassembles the last traceback. .. function:: distb([tb]) - Disassembles the top-of-stack function of a traceback, using the last traceback - if none was passed. The instruction causing the exception is indicated. + Disassembles the top-of-stack function of a traceback, using the last + traceback if none was passed. The instruction causing the exception is + indicated. .. function:: disassemble(code[, lasti]) @@ -233,8 +234,8 @@ result back on the stack. .. opcode:: BINARY_DIVIDE () - Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is not - in effect. + Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is + not in effect. .. opcode:: BINARY_FLOOR_DIVIDE () @@ -244,8 +245,8 @@ result back on the stack. .. opcode:: BINARY_TRUE_DIVIDE () - Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is in - effect. + Implements ``TOS = TOS1 / TOS`` when ``from __future__ import division`` is + in effect. .. opcode:: BINARY_MODULO () @@ -445,32 +446,32 @@ Miscellaneous opcodes. .. opcode:: PRINT_EXPR () Implements the expression statement for the interactive mode. TOS is removed - from the stack and printed. In non-interactive mode, an expression statement is - terminated with :opcode:`POP_TOP`. + from the stack and printed. In non-interactive mode, an expression statement + is terminated with :opcode:`POP_TOP`. .. opcode:: PRINT_ITEM () - Prints TOS to the file-like object bound to ``sys.stdout``. There is one such - instruction for each item in the :keyword:`print` statement. + Prints TOS to the file-like object bound to ``sys.stdout``. There is one + such instruction for each item in the :keyword:`print` statement. .. opcode:: PRINT_ITEM_TO () - Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like object - at TOS. This is used by the extended print statement. + Like ``PRINT_ITEM``, but prints the item second from TOS to the file-like + object at TOS. This is used by the extended print statement. .. opcode:: PRINT_NEWLINE () - Prints a new line on ``sys.stdout``. This is generated as the last operation of - a :keyword:`print` statement, unless the statement ends with a comma. + Prints a new line on ``sys.stdout``. This is generated as the last operation + of a :keyword:`print` statement, unless the statement ends with a comma. .. opcode:: PRINT_NEWLINE_TO () - Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on the - TOS. This is used by the extended print statement. + Like ``PRINT_NEWLINE``, but prints the new line on the file-like object on + the TOS. This is used by the extended print statement. .. opcode:: BREAK_LOOP () @@ -487,15 +488,15 @@ Miscellaneous opcodes. .. opcode:: LIST_APPEND (i) Calls ``list.append(TOS[-i], TOS)``. Used to implement list comprehensions. - While the appended value is popped off, the list object remains on the - stack so that it is available for further iterations of the loop. + While the appended value is popped off, the list object remains on the stack + so that it is available for further iterations of the loop. .. opcode:: LOAD_LOCALS () - Pushes a reference to the locals of the current scope on the stack. This is used - in the code for a class definition: After the class body is evaluated, the - locals are passed to the class definition. + Pushes a reference to the locals of the current scope on the stack. This is + used in the code for a class definition: After the class body is evaluated, + the locals are passed to the class definition. .. opcode:: RETURN_VALUE () @@ -510,9 +511,9 @@ Miscellaneous opcodes. .. opcode:: IMPORT_STAR () - Loads all symbols not starting with ``'_'`` directly from the module TOS to the - local namespace. The module is popped after loading all names. This opcode - implements ``from module import *``. + Loads all symbols not starting with ``'_'`` directly from the module TOS to + the local namespace. The module is popped after loading all names. This + opcode implements ``from module import *``. .. opcode:: EXEC_STMT () @@ -523,8 +524,8 @@ Miscellaneous opcodes. .. opcode:: POP_BLOCK () - Removes one block from the block stack. Per frame, there is a stack of blocks, - denoting nested loops, try statements, and such. + Removes one block from the block stack. Per frame, there is a stack of + blocks, denoting nested loops, try statements, and such. .. opcode:: END_FINALLY () @@ -600,8 +601,8 @@ the more significant byte last. .. opcode:: DUP_TOPX (count) - Duplicate *count* items, keeping them in the same order. Due to implementation - limits, *count* should be between 1 and 5 inclusive. + Duplicate *count* items, keeping them in the same order. Due to + implementation limits, *count* should be between 1 and 5 inclusive. .. opcode:: STORE_ATTR (namei) @@ -637,8 +638,8 @@ the more significant byte last. .. opcode:: BUILD_TUPLE (count) - Creates a tuple consuming *count* items from the stack, and pushes the resulting - tuple onto the stack. + Creates a tuple consuming *count* items from the stack, and pushes the + resulting tuple onto the stack. .. opcode:: BUILD_LIST (count) @@ -667,9 +668,9 @@ the more significant byte last. Imports the module ``co_names[namei]``. TOS and TOS1 are popped and provide the *fromlist* and *level* arguments of :func:`__import__`. The module - object is pushed onto the stack. The current namespace is not affected: - for a proper import statement, a subsequent ``STORE_FAST`` instruction - modifies the namespace. + object is pushed onto the stack. The current namespace is not affected: for + a proper import statement, a subsequent ``STORE_FAST`` instruction modifies + the namespace. .. opcode:: IMPORT_FROM (namei) @@ -696,14 +697,14 @@ the more significant byte last. .. opcode:: JUMP_IF_TRUE_OR_POP (target) - If TOS is true, sets the bytecode counter to *target* and leaves TOS - on the stack. Otherwise (TOS is false), TOS is popped. + If TOS is true, sets the bytecode counter to *target* and leaves TOS on the + stack. Otherwise (TOS is false), TOS is popped. .. opcode:: JUMP_IF_FALSE_OR_POP (target) - If TOS is false, sets the bytecode counter to *target* and leaves - TOS on the stack. Otherwise (TOS is true), TOS is popped. + If TOS is false, sets the bytecode counter to *target* and leaves TOS on the + stack. Otherwise (TOS is true), TOS is popped. .. opcode:: JUMP_ABSOLUTE (target) @@ -732,19 +733,19 @@ the more significant byte last. .. opcode:: SETUP_EXCEPT (delta) - Pushes a try block from a try-except clause onto the block stack. *delta* points - to the first except block. + Pushes a try block from a try-except clause onto the block stack. *delta* + points to the first except block. .. opcode:: SETUP_FINALLY (delta) - Pushes a try block from a try-except clause onto the block stack. *delta* points - to the finally block. + Pushes a try block from a try-except clause onto the block stack. *delta* + points to the finally block. .. opcode:: STORE_MAP () - Store a key and value pair in a dictionary. Pops the key and value while leaving - the dictionary on the stack. + Store a key and value pair in a dictionary. Pops the key and value while + leaving the dictionary on the stack. .. opcode:: LOAD_FAST (var_num) @@ -764,8 +765,8 @@ the more significant byte last. .. opcode:: LOAD_CLOSURE (i) Pushes a reference to the cell contained in slot *i* of the cell and free - variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is - less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i - + variable storage. The name of the variable is ``co_cellvars[i]`` if *i* is + less than the length of *co_cellvars*. Otherwise it is ``co_freevars[i - len(co_cellvars)]``. @@ -797,18 +798,19 @@ the more significant byte last. 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. + 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. .. opcode:: MAKE_FUNCTION (argc) - Pushes a new function object on the stack. TOS is the code associated with the - function. The function object is defined to have *argc* default parameters, - which are found below TOS. + Pushes a new function object on the stack. TOS is the code associated with + the function. The function object is defined to have *argc* default + parameters, which are found below TOS. .. opcode:: MAKE_CLOSURE (argc) @@ -832,34 +834,34 @@ the more significant byte last. Prefixes any opcode which has an argument too big to fit into the default two bytes. *ext* holds two additional bytes which, taken together with the - subsequent opcode's argument, comprise a four-byte argument, *ext* being the two - most-significant bytes. + subsequent opcode's argument, comprise a four-byte argument, *ext* being the + two most-significant bytes. .. 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 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. .. 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 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. .. 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 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. .. opcode:: HAVE_ARGUMENT () - This is not really an opcode. It identifies the dividing line between opcodes - which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>= - HAVE_ARGUMENT``. - + This is not really an opcode. It identifies the dividing line between + opcodes which don't take arguments ``< HAVE_ARGUMENT`` and those which do + ``>= HAVE_ARGUMENT``. diff --git a/Doc/library/fnmatch.rst b/Doc/library/fnmatch.rst index b14c551..a539654 100644 --- a/Doc/library/fnmatch.rst +++ b/Doc/library/fnmatch.rst @@ -85,7 +85,7 @@ patterns. >>> >>> regex = fnmatch.translate('*.txt') >>> regex - '.*\\.txt$' + '.*\\.txt\\Z(?ms)' >>> reobj = re.compile(regex) >>> reobj.match('foobar.txt') <_sre.SRE_Match object at 0x...> diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst index b42cf64..2d85de1 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -55,18 +55,26 @@ The module defines the following items: *timeout* was added. -.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, timeout]]]]]]]) +.. class:: FTP_TLS([host[, user[, passwd[, acct[, keyfile[, certfile[, context[, timeout]]]]]]]]) A :class:`FTP` subclass which adds TLS support to FTP as described in :rfc:`4217`. Connect as usual to port 21 implicitly securing the FTP control connection before authenticating. Securing the data connection requires the user to - explicitly ask for it by calling the :meth:`prot_p` method. - *keyfile* and *certfile* are optional -- they can contain a PEM formatted - private key and certificate chain file name for the SSL connection. + explicitly ask for it by calling the :meth:`prot_p` method. *context* + is a :class:`ssl.SSLContext` object which allows bundling SSL configuration + options, certificates and private keys into a single (potentially + long-lived) structure. Please read :ref:`ssl-security` for best practices. + + *keyfile* and *certfile* are a legacy alternative to *context* -- they + can point to PEM-formatted private key and certificate chain files + (respectively) for the SSL connection. .. versionadded:: 2.7 + .. versionchanged:: 2.7.10 + The *context* parameter was added. + Here's a sample session using the :class:`FTP_TLS` class: >>> from ftplib import FTP_TLS @@ -384,7 +392,7 @@ FTP_TLS Objects .. attribute:: FTP_TLS.ssl_version - The SSL version to use (defaults to *TLSv1*). + The SSL version to use (defaults to :attr:`ssl.PROTOCOL_SSLv23`). .. method:: FTP_TLS.auth() diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 99ba882..8af9f58 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -22,12 +22,17 @@ available. They are listed here in alphabetical order. :func:`classmethod` :func:`getattr` :func:`map` |func-repr|_ :func:`xrange` :func:`cmp` :func:`globals` :func:`max` :func:`reversed` :func:`zip` :func:`compile` :func:`hasattr` |func-memoryview|_ :func:`round` :func:`__import__` -:func:`complex` :func:`hash` :func:`min` |func-set|_ :func:`apply` -:func:`delattr` :func:`help` :func:`next` :func:`setattr` :func:`buffer` -|func-dict|_ :func:`hex` :func:`object` :func:`slice` :func:`coerce` -:func:`dir` :func:`id` :func:`oct` :func:`sorted` :func:`intern` +:func:`complex` :func:`hash` :func:`min` |func-set|_ .. +:func:`delattr` :func:`help` :func:`next` :func:`setattr` .. +|func-dict|_ :func:`hex` :func:`object` :func:`slice` .. +:func:`dir` :func:`id` :func:`oct` :func:`sorted` .. =================== ================= ================== ================= ==================== +In addition, there are other four built-in functions that are no longer +considered essential: :func:`apply`, :func:`buffer`, :func:`coerce`, and +:func:`intern`. They are documented in the :ref:`non-essential-built-in-funcs` +section. + .. using :func:`dict` would create a link to another page, so local targets are used, with replacement texts to make the output in the table consistent @@ -1173,12 +1178,6 @@ available. They are listed here in alphabetical order. There are a number of other caveats: - If a module is syntactically correct but its initialization fails, the first - :keyword:`import` statement for it does not bind its name locally, but does - store a (partially initialized) module object in ``sys.modules``. To reload the - module you must first :keyword:`import` it again (this will bind the name to the - partially initialized module object) before you can :func:`reload` it. - When a module is reloaded, its dictionary (containing the module's global variables) is retained. Redefinitions of names will override the old definitions, so this is generally not a problem. If the new version of a module diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst index 617e3fe..a7d1f45 100644 --- a/Doc/library/heapq.rst +++ b/Doc/library/heapq.rst @@ -49,7 +49,8 @@ The following functions are provided: .. function:: heappop(heap) Pop and return the smallest item from the *heap*, maintaining the heap - invariant. If the heap is empty, :exc:`IndexError` is raised. + invariant. If the heap is empty, :exc:`IndexError` is raised. To access the + smallest item without popping it, use ``heap[0]``. .. function:: heappushpop(heap, item) @@ -125,7 +126,8 @@ The module also offers three general purpose functions based on heaps. The latter two functions perform best for smaller values of *n*. For larger values, it is more efficient to use the :func:`sorted` function. Also, when ``n==1``, it is more efficient to use the built-in :func:`min` and :func:`max` -functions. +functions. If repeated usage of these functions is required, consider turning +the iterable into an actual heap. Basic Examples @@ -274,11 +276,11 @@ However, there are other representations which are more efficient overall, yet the worst cases might be terrible. Heaps are also very useful in big disk sorts. You most probably all know that a -big sort implies producing "runs" (which are pre-sorted sequences, which size is +big sort implies producing "runs" (which are pre-sorted sequences, whose size is usually related to the amount of CPU memory), followed by a merging passes for these runs, which merging is often very cleverly organised [#]_. It is very important that the initial sort produces the longest runs possible. Tournaments -are a good way to that. If, using all the memory available to hold a +are a good way to achieve that. If, using all the memory available to hold a tournament, you replace and percolate items that happen to fit the current run, you'll produce runs which are twice the size of the memory for random input, and much better for input fuzzily ordered. diff --git a/Doc/library/htmllib.rst b/Doc/library/htmllib.rst index 9e68f45..d9d81df 100644 --- a/Doc/library/htmllib.rst +++ b/Doc/library/htmllib.rst @@ -185,14 +185,14 @@ can be handled using simple textual substitution in the Latin-1 character set .. data:: name2codepoint - A dictionary that maps HTML entity names to the Unicode codepoints. + A dictionary that maps HTML entity names to the Unicode code points. .. versionadded:: 2.3 .. data:: codepoint2name - A dictionary that maps Unicode codepoints to HTML entity names. + A dictionary that maps Unicode code points to HTML entity names. .. versionadded:: 2.3 diff --git a/Doc/library/httplib.rst b/Doc/library/httplib.rst index 354edb2..45d8295 100644 --- a/Doc/library/httplib.rst +++ b/Doc/library/httplib.rst @@ -24,6 +24,11 @@ This module defines classes which implement the client side of the HTTP and HTTPS protocols. It is normally not used directly --- the module :mod:`urllib` uses it to handle URLs that use HTTP and HTTPS. +.. seealso:: + + The `Requests package `_ + is recommended for a higher-level http client interface. + .. note:: HTTPS support is only available if the :mod:`socket` module was compiled with @@ -433,9 +438,16 @@ HTTPConnection Objects and the selector *url*. If the *body* argument is present, it should be a string of data to send after the headers are finished. Alternatively, it may be an open file object, in which case the contents of the file is sent; this - file object should support ``fileno()`` and ``read()`` methods. The header - Content-Length is automatically set to the correct value. The *headers* - argument should be a mapping of extra HTTP headers to send with the request. + file object should support ``fileno()`` and ``read()`` methods. The + *headers* argument should be a mapping of extra HTTP headers to send with + the request. + + If one is not provided in *headers*, a ``Content-Length`` header is added + automatically for all methods if the length of the body can be determined, + either from the length of the ``str`` representation, or from the reported + size of the file on disk. If *body* is ``None`` the header is not set except + for methods that expect a body (``PUT``, ``POST``, and ``PATCH``) in which + case it is set to ``0``. .. versionchanged:: 2.6 *body* can be a file object. @@ -579,13 +591,13 @@ Examples Here is an example session that uses the ``GET`` method:: >>> import httplib - >>> conn = httplib.HTTPConnection("www.python.org") - >>> conn.request("GET", "/index.html") + >>> conn = httplib.HTTPSConnection("www.python.org") + >>> conn.request("GET", "/") >>> r1 = conn.getresponse() >>> print r1.status, r1.reason 200 OK >>> data1 = r1.read() - >>> conn.request("GET", "/parrot.spam") + >>> conn.request("GET", "/") >>> r2 = conn.getresponse() >>> print r2.status, r2.reason 404 Not Found @@ -596,8 +608,8 @@ Here is an example session that uses the ``HEAD`` method. Note that the ``HEAD`` method never returns any data. :: >>> import httplib - >>> conn = httplib.HTTPConnection("www.python.org") - >>> conn.request("HEAD","/index.html") + >>> conn = httplib.HTTPSConnection("www.python.org") + >>> conn.request("HEAD","/") >>> res = conn.getresponse() >>> print res.status, res.reason 200 OK diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 36d78b0..c842b26 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -3,200 +3,291 @@ IDLE ==== -.. moduleauthor:: Guido van Rossum - .. index:: single: IDLE single: Python Editor single: Integrated Development Environment +.. moduleauthor:: Guido van Rossum + IDLE is the Python IDE built with the :mod:`tkinter` GUI toolkit. IDLE has the following features: * coded in 100% pure Python, using the :mod:`tkinter` GUI toolkit -* cross-platform: works on Windows and Unix +* cross-platform: works on Windows, Unix, and Mac OS X -* multi-window text editor with multiple undo, Python colorizing and many other - features, e.g. smart indent and call tips +* multi-window text editor with multiple undo, Python colorizing, + smart indent, call tips, and many other features * Python shell window (a.k.a. interactive interpreter) -* debugger (not complete, but you can set breakpoints, view and step) +* debugger (not complete, but you can set breakpoints, view and step) Menus ----- +IDLE has two main window types, the Shell window and the Editor window. It is +possible to have multiple editor windows simultaneously. Output windows, such +as used for Edit / Find in Files, are a subtype of edit window. They currently +have the same top menu as Editor windows but a different default title and +context menu. -File menu -^^^^^^^^^ +IDLE's menus dynamically change based on which window is currently selected. +Each menu documented below indicates which window type it is associated with. +Click on the dotted line at the top of a menu to "tear it off": a separate +window containing the menu is created (for Unix and Windows only). -New file - create a new file editing window +File menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Open... - open an existing file +New File + Create a new file editing window. -Open module... - open an existing module (searches sys.path) +Open... + Open an existing file with an Open dialog. -Class browser - show classes and methods in current file +Recent Files + Open a list of recent files. Click one to open it. -Path browser - show sys.path directories, modules, classes and methods +Open Module... + Open an existing module (searches sys.path). .. index:: single: Class browser single: Path browser +Class Browser + Show functions, classes, and methods in the current Editor file in a + tree structure. In the shell, open a module first. + +Path Browser + Show sys.path directories, modules, functions, classes and methods in a + tree structure. + Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) + Save the current window to the associated file, if there is one. Windows + that have been changed since being opened or last saved have a \* before + and after the window title. If there is no associated file, + do Save As instead. Save As... - save current window to new file, which becomes the associated file + Save the current window with a Save As dialog. The file saved becomes the + new associated file for the window. Save Copy As... - save current window to different file without changing the associated file + Save the current window to different file without changing the associated + file. + +Print Window + Print the current window to the default printer. Close - close current window (asks to save if unsaved) + Close the current window (ask to save if unsaved). Exit - close all windows and quit IDLE (asks to save if unsaved) + Close all windows and quit IDLE (ask to save unsaved windows). - -Edit menu -^^^^^^^^^ +Edit menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Undo - Undo last change to current window (max 1000 changes) + Undo the last change to the current window. A maximum of 1000 changes may + be undone. Redo - Redo last undone change to current window + Redo the last undone change to the current window. Cut - Copy selection into system-wide clipboard; then delete selection + Copy selection into the system-wide clipboard; then delete the selection. Copy - Copy selection into system-wide clipboard + Copy selection into the system-wide clipboard. Paste - Insert system-wide clipboard into window + Insert contents of the system-wide clipboard into the current window. + +The clipboard functions are also available in context menus. Select All - Select the entire contents of the edit buffer + Select the entire contents of the current window. Find... - Open a search dialog box with many options + Open a search dialog with many options -Find again - Repeat last search +Find Again + Repeat the last search, if there is one. -Find selection - Search for the string in the selection +Find Selection + Search for the currently selected string, if there is one. Find in Files... - Open a search dialog box for searching files + Open a file search dialog. Put results in an new output window. Replace... - Open a search-and-replace dialog box + Open a search-and-replace dialog. -Go to line - Ask for a line number and show that line +Go to Line + Move cursor to the line number requested and make that line visible. -Indent region - Shift selected lines right 4 spaces +Show Completions + Open a scrollable list allowing selection of keywords and attributes. See + Completions in the Tips sections below. -Dedent region - Shift selected lines left 4 spaces +Expand Word + Expand a prefix you have typed to match a full word in the same window; + repeat to get a different expansion. -Comment out region - Insert ## in front of selected lines +Show call tip + After an unclosed parenthesis for a function, open a small window with + function parameter hints. -Uncomment region - Remove leading # or ## from selected lines +Show surrounding parens + Highlight the surrounding parenthesis. -Tabify region - Turns *leading* stretches of spaces into tabs +Format menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Untabify region - Turn *all* tabs into the right number of spaces +Indent Region + Shift selected lines right by the indent width (default 4 spaces). -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion +Dedent Region + Shift selected lines left by the indent width (default 4 spaces). -Format Paragraph - Reformat the current blank-line-separated paragraph +Comment Out Region + Insert ## in front of selected lines. + +Uncomment Region + Remove leading # or ## from selected lines. + +Tabify Region + Turn *leading* stretches of spaces into tabs. (Note: We recommend using + 4 space blocks to indent Python code.) -Import module - Import or reload the current module +Untabify Region + Turn *all* tabs into the correct number of spaces. -Run script - Execute the current file in the __main__ namespace +Toggle Tabs + Open a dialog to switch between indenting with spaces and tabs. + +New Indent Width + Open a dialog to change indent width. The accepted default by the Python + community is 4 spaces. + +Format Paragraph + Reformat the current blank-line-delimited paragraph in comment block or + multiline string or selected line in a string. All lines in the + paragraph will be formatted to less than N columns, where N defaults to 72. + +Strip trailing whitespace + Remove any space characters after the last non-space character of a line. .. index:: - single: Import module single: Run script +Run menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Windows menu -^^^^^^^^^^^^ +Python Shell + Open or wake up the Python Shell window. -Zoom Height - toggles the window between normal size (24x80) and maximum height. +Check Module + Check the syntax of the module currently open in the Editor window. If the + module has not been saved IDLE will either prompt the user to save or + autosave, as selected in the General tab of the Idle Settings dialog. If + there is a syntax error, the approximate location is indicated in the + Editor window. -The rest of this menu lists the names of all open windows; select one to bring -it to the foreground (deiconifying it if necessary). +Run Module + Do Check Module (above). If no error, restart the shell to clean the + environment, then execute the module. +Shell menu (Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Debug menu -^^^^^^^^^^ +View Last Restart + Scroll the shell window to the last Shell restart. -* in the Python Shell window only +Restart Shell + Restart the shell to clean the environment. -Go to file/line - Look around the insert point for a filename and line number, open the file, - and show the line. Useful to view the source lines referenced in an - exception traceback. +Debug menu (Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Go to File/Line + Look on the current line. with the cursor, and the line above for a filename + and line number. If found, open the file if not already open, and show the + line. Use this to view source lines referenced in an exception traceback + and lines found by Find in Files. Also available in the context menu of + the Shell window and Output windows. + +.. index:: + single: debugger + single: stack viewer -Debugger - Run commands in the shell under the debugger. +Debugger (toggle) + When actived, code entered in the Shell or run from an Editor will run + under the debugger. In the Editor, breakpoints can be set with the context + menu. This feature is still incomplete and somewhat experimental. -Stack viewer - Show the stack traceback of the last exception. +Stack Viewer + Show the stack traceback of the last exception in a tree widget, with + access to locals and globals. Auto-open Stack Viewer - Open stack viewer on traceback. + Toggle automatically opening the stack viewer on an unhandled exception. -.. index:: - single: stack viewer - single: debugger +Options menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Configure IDLE + Open a configuration dialog. Fonts, indentation, keybindings, and color + themes may be altered. Startup Preferences may be set, and additional + help sources can be specified. Non-default user setting are saved in a + .idlerc directory in the user's home directory. Problems caused by bad user + configuration files are solved by editing or deleting one or more of the + files in .idlerc. -Edit context menu -^^^^^^^^^^^^^^^^^ +Configure Extensions + Open a configuration dialog for setting preferences for extensions + (discussed below). See note above about the location of user settings. -* Right-click in Edit window (Control-click on OS X) +Code Context (toggle)(Editor Window only) + Open a pane at the top of the edit window which shows the block context + of the code which has scrolled above the top of the window. -Cut - Copy selection into system-wide clipboard; then delete selection +Window menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Copy - Copy selection into system-wide clipboard +Zoom Height + Toggles the window between normal size and maximum height. The initial size + defaults to 40 lines by 80 chars unless changed on the General tab of the + Configure IDLE dialog. -Paste - Insert system-wide clipboard into window +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). -Set Breakpoint - Sets a breakpoint. Breakpoints are only enabled when the debugger is open. +Help menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Clear Breakpoint - Clears the breakpoint on that line. +About IDLE + Display version, copyright, license, credits, and more. + +IDLE Help + Display a help file for IDLE detailing the menu options, basic editing and + navigation, and other tips. + +Python Docs + Access local Python documentation, if installed, or start a web browser + and open docs.python.org showing the latest Python documentation. + +Turtle Demo + Run the turtledemo module with example python code and turtle drawings. + +Additional help sources may be added here with the Configure IDLE dialog under +the General tab. .. index:: single: Cut @@ -206,38 +297,78 @@ Clear Breakpoint single: Clear Breakpoint single: breakpoints +Context Menus +^^^^^^^^^^^^^^^^^^^^^^^^^^ -Shell context menu -^^^^^^^^^^^^^^^^^^ - -* Right-click in Python Shell window (Control-click on OS X) +Open a context menu by right-clicking in a window (Control-click on OS X). +Context menus have the standard clipboard functions also on the Edit menu. Cut - Copy selection into system-wide clipboard; then delete selection + Copy selection into the system-wide clipboard; then delete the selection. Copy - Copy selection into system-wide clipboard + Copy selection into the system-wide clipboard. Paste - Insert system-wide clipboard into window + Insert contents of the system-wide clipboard into the current window. + +Editor windows also have breakpoint functions. Lines with a breakpoint set are +specially marked. Breakpoints only have an effect when running under the +debugger. Breakpoints for a file are saved in the user's .idlerc directory. + +Set Breakpoint + Set a breakpoint on the current line. + +Clear Breakpoint + Clear the breakpoint on that line. + +Shell and Output windows have the following. Go to file/line Same as in Debug menu. -Basic editing and navigation ----------------------------- +Editing and navigation +---------------------- + +In this section, 'C' refers to the Control key on Windows and Unix and +the Command key on Mac OSX. * :kbd:`Backspace` deletes to the left; :kbd:`Del` deletes to the right +* :kbd:`C-Backspace` delete word left; :kbd:`C-Del` delete word to the right + * Arrow keys and :kbd:`Page Up`/:kbd:`Page Down` to move around +* :kbd:`C-LeftArrow` and :kbd:`C-RightArrow` moves by words + * :kbd:`Home`/:kbd:`End` go to begin/end of line * :kbd:`C-Home`/:kbd:`C-End` go to begin/end of file -* Some :program:`Emacs` bindings may also work, including :kbd:`C-B`, - :kbd:`C-P`, :kbd:`C-A`, :kbd:`C-E`, :kbd:`C-D`, :kbd:`C-L` +* Some useful Emacs bindings are inherited from Tcl/Tk: + + * :kbd:`C-a` beginning of line + + * :kbd:`C-e` end of line + + * :kbd:`C-k` kill line (but doesn't put it in clipboard) + + * :kbd:`C-l` center window around the insertion point + + * :kbd:`C-b` go backwards one character without deleting (usually you can + also use the cursor key for this) + + * :kbd:`C-f` go forward one character without deleting (usually you can + also use the cursor key for this) + + * :kbd:`C-p` go up one line (usually you can also use the cursor key for + this) + + * :kbd:`C-d` delete next character + +Standard keybindings (like :kbd:`C-c` to copy and :kbd:`C-v` to paste) +may work. Keybindings are selected in the Configure IDLE dialog. Automatic indentation @@ -246,27 +377,75 @@ Automatic indentation After a block-opening statement, the next line is indented by 4 spaces (in the Python Shell window by one tab). After certain keywords (break, return etc.) the next line is dedented. In leading indentation, :kbd:`Backspace` deletes up -to 4 spaces if they are there. :kbd:`Tab` inserts 1-4 spaces (in the Python -Shell window one tab). See also the indent/dedent region commands in the edit -menu. - +to 4 spaces if they are there. :kbd:`Tab` inserts spaces (in the Python +Shell window one tab), number depends on Indent width. Currently tabs +are restricted to four spaces due to Tcl/Tk limitations. + +See also the indent/dedent region commands in the edit menu. + +Completions +^^^^^^^^^^^ + +Completions are supplied for functions, classes, and attributes of classes, +both built-in and user-defined. Completions are also provided for +filenames. + +The AutoCompleteWindow (ACW) will open after a predefined delay (default is +two seconds) after a '.' or (in a string) an os.sep is typed. If after one +of those characters (plus zero or more other characters) a tab is typed +the ACW will open immediately if a possible continuation is found. + +If there is only one possible completion for the characters entered, a +:kbd:`Tab` will supply that completion without opening the ACW. + +'Show Completions' will force open a completions window, by default the +:kbd:`C-space` will open a completions window. In an empty +string, this will contain the files in the current directory. On a +blank line, it will contain the built-in and user-defined functions and +classes in the current name spaces, plus any modules imported. If some +characters have been entered, the ACW will attempt to be more specific. + +If a string of characters is typed, the ACW selection will jump to the +entry most closely matching those characters. Entering a :kbd:`tab` will +cause the longest non-ambiguous match to be entered in the Editor window or +Shell. Two :kbd:`tab` in a row will supply the current ACW selection, as +will return or a double click. Cursor keys, Page Up/Down, mouse selection, +and the scroll wheel all operate on the ACW. + +"Hidden" attributes can be accessed by typing the beginning of hidden +name after a '.', e.g. '_'. This allows access to modules with +``__all__`` set, or to class-private attributes. + +Completions and the 'Expand Word' facility can save a lot of typing! + +Completions are currently limited to those in the namespaces. Names in +an Editor window which are not via ``__main__`` and :data:`sys.modules` will +not be found. Run the module once with your imports to correct this situation. +Note that IDLE itself places quite a few modules in sys.modules, so +much can be found by default, e.g. the re module. + +If you don't like the ACW popping up unbidden, simply make the delay +longer or disable the extension. Or another option is the delay could +be set to zero. Another alternative to preventing ACW popups is to +disable the call tips extension. Python Shell window ^^^^^^^^^^^^^^^^^^^ -* :kbd:`C-C` interrupts executing command +* :kbd:`C-c` interrupts executing command -* :kbd:`C-D` sends end-of-file; closes window if typed at a ``>>>`` prompt +* :kbd:`C-d` sends end-of-file; closes window if typed at a ``>>>`` prompt -* :kbd:`Alt-p` retrieves previous command matching what you have typed +* :kbd:`Alt-/` (Expand word) is also useful to reduce typing -* :kbd:`Alt-n` retrieves next + Command history -* :kbd:`Return` while on any previous command retrieves that command + * :kbd:`Alt-p` retrieves previous command matching what you have typed. On + OS X use :kbd:`C-p`. -* :kbd:`Alt-/` (Expand word) is also useful here + * :kbd:`Alt-n` retrieves next. On OS X use :kbd:`C-n`. -.. index:: single: indentation + * :kbd:`Return` while on any previous command retrieves that command Syntax colors @@ -308,17 +487,17 @@ Startup Upon startup with the ``-s`` option, IDLE will execute the file referenced by the environment variables :envvar:`IDLESTARTUP` or :envvar:`PYTHONSTARTUP`. -Idle first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file -referenced is run. If ``IDLESTARTUP`` is not present, Idle checks for +IDLE first checks for ``IDLESTARTUP``; if ``IDLESTARTUP`` is present the file +referenced is run. If ``IDLESTARTUP`` is not present, IDLE checks for ``PYTHONSTARTUP``. Files referenced by these environment variables are -convenient places to store functions that are used frequently from the Idle +convenient places to store functions that are used frequently from the IDLE shell, or for executing import statements to import common modules. In addition, ``Tk`` also loads a startup file if it is present. Note that the Tk file is loaded unconditionally. This additional file is ``.Idle.py`` and is looked for in the user's home directory. Statements in this file will be -executed in the Tk namespace, so this file is not useful for importing functions -to be used from Idle's Python shell. +executed in the Tk namespace, so this file is not useful for importing +functions to be used from IDLE's Python shell. Command line usage @@ -344,8 +523,71 @@ If there are arguments: #. Otherwise, if neither ``-e`` nor ``-c`` is used, the first argument is a script which is executed with the remaining arguments in - ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the script - name is '-', no script is executed but an interactive Python session is started; - the arguments are still available in ``sys.argv``. + ``sys.argv[1:...]`` and ``sys.argv[0]`` set to the script name. If the + script name is '-', no script is executed but an interactive Python session + is started; the arguments are still available in ``sys.argv``. + +Running without a subprocess +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If IDLE is started with the -n command line switch it will run in a +single process and will not create the subprocess which runs the RPC +Python execution server. This can be useful if Python cannot create +the subprocess or the RPC socket interface on your platform. However, +in this mode user code is not isolated from IDLE itself. Also, the +environment is not restarted when Run/Run Module (F5) is selected. If +your code has been modified, you must reload() the affected modules and +re-import any specific items (e.g. from foo import baz) if the changes +are to take effect. For these reasons, it is preferable to run IDLE +with the default subprocess if at all possible. + +.. deprecated:: 3.4 + + +Help and preferences +-------------------- + +Additional help sources +^^^^^^^^^^^^^^^^^^^^^^^ + +IDLE includes a help menu entry called "Python Docs" that will open the +extensive sources of help, including tutorials, available at docs.python.org. +Selected URLs can be added or removed from the help menu at any time using the +Configure IDLE dialog. See the IDLE help option in the help menu of IDLE for +more information. + + +Setting preferences +^^^^^^^^^^^^^^^^^^^ + +The font preferences, highlighting, keys, and general preferences can be +changed via Configure IDLE on the Option menu. Keys can be user defined; +IDLE ships with four built in key sets. In addition a user can create a +custom key set in the Configure IDLE dialog under the keys tab. + + +Extensions +^^^^^^^^^^ + +IDLE contains an extension facility. Peferences for extensions can be +changed with Configure Extensions. See the beginning of config-extensions.def +in the idlelib directory for further information. The default extensions +are currently: + +* FormatParagraph + +* AutoExpand + +* ZoomHeight + +* ScriptBinding + +* CallTips + +* ParenMatch + +* AutoComplete +* CodeContext +* RstripExtension diff --git a/Doc/library/index.rst b/Doc/library/index.rst index 4b465d9..97cf3ea 100644 --- a/Doc/library/index.rst +++ b/Doc/library/index.rst @@ -20,7 +20,7 @@ everyday programming. Some of these modules are explicitly designed to encourage and enhance the portability of Python programs by abstracting away platform-specifics into platform-neutral APIs. -The Python installers for the Windows platform usually includes +The Python installers for the Windows platform usually include the entire standard library and often also include many additional components. For Unix-like operating systems Python is normally provided as a collection of packages, so it may be necessary to use the packaging diff --git a/Doc/library/json.rst b/Doc/library/json.rst index caee953..6db8f97 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -8,9 +8,11 @@ .. versionadded:: 2.6 `JSON (JavaScript Object Notation) `_, specified by -:rfc:`4627`, is a lightweight data interchange format based on a subset of -`JavaScript `_ syntax (`ECMA-262 3rd -edition `_). +:rfc:`7159` (which obsoletes :rfc:`4627`) and by +`ECMA-404 `_, +is a lightweight data interchange format inspired by +`JavaScript `_ object literal syntax +(although it is not a strict subset of JavaScript [#rfc-errata]_ ). :mod:`json` exposes an API familiar to users of the standard library :mod:`marshal` and :mod:`pickle` modules. @@ -485,18 +487,18 @@ Encoders and Decoders mysocket.write(chunk) -Standard Compliance -------------------- +Standard Compliance and Interoperability +---------------------------------------- -The JSON format is specified by :rfc:`4627`. This section details this -module's level of compliance with the RFC. For simplicity, -:class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and parameters other -than those explicitly mentioned, are not considered. +The JSON format is specified by :rfc:`7159` and by +`ECMA-404 `_. +This section details this module's level of compliance with the RFC. +For simplicity, :class:`JSONEncoder` and :class:`JSONDecoder` subclasses, and +parameters other than those explicitly mentioned, are not considered. This module does not comply with the RFC in a strict fashion, implementing some extensions that are valid JavaScript but not valid JSON. In particular: -- Top-level non-object, non-array values are accepted and output; - Infinite and NaN number values are accepted and output; - Repeated names within an object are accepted, and only the value of the last name-value pair is used. @@ -508,48 +510,30 @@ default settings. Character Encodings ^^^^^^^^^^^^^^^^^^^ -The RFC recommends that JSON be represented using either UTF-8, UTF-16, or -UTF-32, with UTF-8 being the default. Accordingly, this module uses UTF-8 as -the default for its *encoding* parameter. +The RFC requires that JSON be represented using either UTF-8, UTF-16, or +UTF-32, with UTF-8 being the recommended default for maximum interoperability. +Accordingly, this module uses UTF-8 as the default for its *encoding* parameter. This module's deserializer only directly works with ASCII-compatible encodings; UTF-16, UTF-32, and other ASCII-incompatible encodings require the use of workarounds described in the documentation for the deserializer's *encoding* parameter. -The RFC also non-normatively describes a limited encoding detection technique -for JSON texts; this module's deserializer does not implement this or any other -kind of encoding detection. - As permitted, though not required, by the RFC, this module's serializer sets *ensure_ascii=True* by default, thus escaping the output so that the resulting strings only contain ASCII characters. +The RFC prohibits adding a byte order mark (BOM) to the start of a JSON text, +and this module's serializer does not add a BOM to its output. +The RFC permits, but does not require, JSON deserializers to ignore an initial +BOM in their input. This module's deserializer raises a :exc:`ValueError` +when an initial BOM is present. -Top-level Non-Object, Non-Array Values -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The RFC specifies that the top-level value of a JSON text must be either a -JSON object or array (Python :class:`dict` or :class:`list`). This module's -deserializer also accepts input texts consisting solely of a -JSON null, boolean, number, or string value:: - - >>> just_a_json_string = '"spam and eggs"' # Not by itself a valid JSON text - >>> json.loads(just_a_json_string) - u'spam and eggs' - -This module itself does not include a way to request that such input texts be -regarded as illegal. Likewise, this module's serializer also accepts single -Python :data:`None`, :class:`bool`, numeric, and :class:`str` -values as input and will generate output texts consisting solely of a top-level -JSON null, boolean, number, or string value without raising an exception:: - - >>> neither_a_list_nor_a_dict = u"spam and eggs" - >>> json.dumps(neither_a_list_nor_a_dict) # The result is not a valid JSON text - '"spam and eggs"' - -This module's serializer does not itself include a way to enforce the -aforementioned constraint. +The RFC does not explicitly forbid JSON strings which contain byte sequences +that don't correspond to valid Unicode characters (e.g. unpaired UTF-16 +surrogates), but it does note that they may cause interoperability problems. +By default, this module accepts and outputs (when present in the original +:class:`str`) code points for such sequences. Infinite and NaN Number Values @@ -579,7 +563,7 @@ Repeated Names Within an Object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The RFC specifies that the names within a JSON object should be unique, but -does not specify how repeated names in JSON objects should be handled. By +does not mandate how repeated names in JSON objects should be handled. By default, this module does not raise an exception; instead, it ignores all but the last name-value pair for a given name:: @@ -588,3 +572,48 @@ the last name-value pair for a given name:: {u'x': 3} The *object_pairs_hook* parameter can be used to alter this behavior. + + +Top-level Non-Object, Non-Array Values +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The old version of JSON specified by the obsolete :rfc:`4627` required that +the top-level value of a JSON text must be either a JSON object or array +(Python :class:`dict` or :class:`list`), and could not be a JSON null, +boolean, number, or string value. :rfc:`7159` removed that restriction, and +this module does not and has never implemented that restriction in either its +serializer or its deserializer. + +Regardless, for maximum interoperability, you may wish to voluntarily adhere +to the restriction yourself. + + +Implementation Limitations +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some JSON deserializer implementations may set limits on: + +* the size of accepted JSON texts +* the maximum level of nesting of JSON objects and arrays +* the range and precision of JSON numbers +* the content and maximum length of JSON strings + +This module does not impose any such limits beyond those of the relevant +Python datatypes themselves or the Python interpreter itself. + +When serializing to JSON, beware any such limitations in applications that may +consume your JSON. In particular, it is common for JSON numbers to be +deserialized into IEEE 754 double precision numbers and thus subject to that +representation's range and precision limitations. This is especially relevant +when serializing Python :class:`int` values of extremely large magnitude, or +when serializing instances of "exotic" numerical types such as +:class:`decimal.Decimal`. + + +.. rubric:: Footnotes + +.. [#rfc-errata] As noted in `the errata for RFC 7159 + `_, + JSON permits literal U+2028 (LINE SEPARATOR) and + U+2029 (PARAGRAPH SEPARATOR) characters in strings, whereas JavaScript + (as of ECMAScript Edition 5.1) does not. diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index fddb644..5460c3a 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -580,6 +580,18 @@ called ``form01`` in the ``[formatters]`` section will have its configuration specified in a section called ``[formatter_form01]``. The root logger configuration must be specified in a section called ``[logger_root]``. +.. note:: + + The :func:`fileConfig` API is older than the :func:`dictConfig` API and does + not provide functionality to cover certain aspects of logging. For example, + you cannot configure :class:`~logging.Filter` objects, which provide for + filtering of messages beyond simple integer levels, using :func:`fileConfig`. + If you need to have instances of :class:`~logging.Filter` in your logging + configuration, you will need to use :func:`dictConfig`. Note that future + enhancements to configuration functionality will be added to + :func:`dictConfig`, so it's worth considering transitioning to this newer + API when it's convenient to do so. + Examples of these sections in the file are given below. :: [loggers] diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index d0f9be8..6731abc 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -185,15 +185,16 @@ module, supports rotation of disk log files. You can use the *maxBytes* and *backupCount* values to allow the file to :dfn:`rollover` at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs - whenever the current log file is nearly *maxBytes* in length; if *maxBytes* is - zero, rollover never occurs. If *backupCount* is non-zero, the system will save - old log files by appending the extensions '.1', '.2' etc., to the filename. For - example, with a *backupCount* of 5 and a base file name of :file:`app.log`, you - would get :file:`app.log`, :file:`app.log.1`, :file:`app.log.2`, up to - :file:`app.log.5`. The file being written to is always :file:`app.log`. When - this file is filled, it is closed and renamed to :file:`app.log.1`, and if files - :file:`app.log.1`, :file:`app.log.2`, etc. exist, then they are renamed to - :file:`app.log.2`, :file:`app.log.3` etc. respectively. + whenever the current log file is nearly *maxBytes* in length; if either of + *maxBytes* or *backupCount* is zero, rollover never occurs. If *backupCount* + is non-zero, the system will save old log files by appending the extensions + '.1', '.2' etc., to the filename. For example, with a *backupCount* of 5 and + a base file name of :file:`app.log`, you would get :file:`app.log`, + :file:`app.log.1`, :file:`app.log.2`, up to :file:`app.log.5`. The file being + written to is always :file:`app.log`. When this file is filled, it is closed + and renamed to :file:`app.log.1`, and if files :file:`app.log.1`, + :file:`app.log.2`, etc. exist, then they are renamed to :file:`app.log.2`, + :file:`app.log.3` etc. respectively. .. versionchanged:: 2.6 *delay* was added. diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst index 839bdc7..9f778f5 100644 --- a/Doc/library/logging.rst +++ b/Doc/library/logging.rst @@ -227,8 +227,9 @@ is the module's name in the Python package namespace. .. method:: Logger.exception(msg, *args, **kwargs) Logs a message with level :const:`ERROR` on this logger. The arguments are - interpreted as for :meth:`debug`. Exception info is added to the logging - message. This method should only be called from an exception handler. + interpreted as for :meth:`debug`, except that any passed *exc_info* is not + inspected. Exception info is always added to the logging message. This method + should only be called from an exception handler. .. method:: Logger.addFilter(filt) @@ -439,7 +440,9 @@ Formatter Objects responsible for converting a :class:`LogRecord` to (usually) a string which can be interpreted by either a human or an external system. The base :class:`Formatter` allows a formatting string to be specified. If none is -supplied, the default value of ``'%(message)s'`` is used. +supplied, the default value of ``'%(message)s'`` is used, which just includes +the message in the logging call. To have additional items of information in the +formatted output (such as a timestamp), keep reading. A Formatter can be initialized with a format string which makes use of knowledge of the :class:`LogRecord` attributes - such as the default value mentioned above @@ -845,8 +848,9 @@ functions. .. function:: exception(msg[, *args[, **kwargs]]) Logs a message with level :const:`ERROR` on the root logger. The arguments are - interpreted as for :func:`debug`. Exception info is added to the logging - message. This function should only be called from an exception handler. + interpreted as for :func:`debug`, except that any passed *exc_info* is not + inspected. Exception info is always added to the logging message. This + function should only be called from an exception handler. .. function:: log(level, msg[, *args[, **kwargs]]) diff --git a/Doc/library/mimetypes.rst b/Doc/library/mimetypes.rst index 740c2f6..0b7fc92 100644 --- a/Doc/library/mimetypes.rst +++ b/Doc/library/mimetypes.rst @@ -106,8 +106,8 @@ behavior of the module. extension is already known, the new type will replace the old one. When the type is already known the extension will be added to the list of known extensions. - When *strict* is ``True`` (the default), the mapping will added to the official MIME - types, otherwise to the non-standard ones. + When *strict* is ``True`` (the default), the mapping will be added to the + official MIME types, otherwise to the non-standard ones. .. data:: inited diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index fb8ddfb..021e3c8 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -18,41 +18,27 @@ to this, the :mod:`multiprocessing` module allows the programmer to fully leverage multiple processors on a given machine. It runs on both Unix and Windows. -.. warning:: +The :mod:`multiprocessing` module also introduces APIs which do not have +analogs in the :mod:`threading` module. A prime example of this is the +:class:`Pool` object which offers a convenient means of parallelizing the +execution of a function across multiple input values, distributing the +input data across processes (data parallelism). The following example +demonstrates the common practice of defining such functions in a module so +that child processes can successfully import that module. This basic example +of data parallelism using :class:`Pool`, :: - Some of this package's functionality requires a functioning shared semaphore - implementation on the host operating system. Without one, the - :mod:`multiprocessing.synchronize` module will be disabled, and attempts to - import it will result in an :exc:`ImportError`. See - :issue:`3770` for additional information. + from multiprocessing import Pool -.. note:: + def f(x): + return x*x - Functionality within this package requires that the ``__main__`` module be - importable by the children. This is covered in :ref:`multiprocessing-programming` - however it is worth pointing out here. This means that some examples, such - as the :class:`multiprocessing.Pool` examples will not work in the - interactive interpreter. For example:: - - >>> from multiprocessing import Pool - >>> p = Pool(5) - >>> def f(x): - ... return x*x - ... - >>> p.map(f, [1,2,3]) - Process PoolWorker-1: - Process PoolWorker-2: - Process PoolWorker-3: - Traceback (most recent call last): - Traceback (most recent call last): - Traceback (most recent call last): - AttributeError: 'module' object has no attribute 'f' - AttributeError: 'module' object has no attribute 'f' - AttributeError: 'module' object has no attribute 'f' - - (If you try this it will actually output three full tracebacks - interleaved in a semi-random fashion, and then you may have to - stop the master process somehow.) + if __name__ == '__main__': + p = Pool(5) + print(p.map(f, [1, 2, 3])) + +will print to standard output :: + + [1, 4, 9] The :class:`Process` class @@ -99,7 +85,6 @@ For an explanation of why (on Windows) the ``if __name__ == '__main__'`` part is necessary, see :ref:`multiprocessing-programming`. - Exchanging objects between processes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -290,6 +275,34 @@ For example:: Note that the methods of a pool should only ever be used by the process which created it. +.. note:: + + Functionality within this package requires that the ``__main__`` module be + importable by the children. This is covered in :ref:`multiprocessing-programming` + however it is worth pointing out here. This means that some examples, such + as the :class:`Pool` examples will not work in the interactive interpreter. + For example:: + + >>> from multiprocessing import Pool + >>> p = Pool(5) + >>> def f(x): + ... return x*x + ... + >>> p.map(f, [1,2,3]) + Process PoolWorker-1: + Process PoolWorker-2: + Process PoolWorker-3: + Traceback (most recent call last): + Traceback (most recent call last): + Traceback (most recent call last): + AttributeError: 'module' object has no attribute 'f' + AttributeError: 'module' object has no attribute 'f' + AttributeError: 'module' object has no attribute 'f' + + (If you try this it will actually output three full tracebacks + interleaved in a semi-random fashion, and then you may have to + stop the master process somehow.) + Reference --------- @@ -638,6 +651,15 @@ For an example of the usage of queues for interprocess communication see immediately without waiting to flush enqueued data to the underlying pipe, and you don't care about lost data. + .. note:: + + This class's functionality requires a functioning shared semaphore + implementation on the host operating system. Without one, the + functionality in this class will be disabled, and attempts to + instantiate a :class:`Queue` will result in an :exc:`ImportError`. See + :issue:`3770` for additional information. The same holds true for any + of the specialized queue types listed below. + .. class:: multiprocessing.queues.SimpleQueue() @@ -944,6 +966,14 @@ object -- see :ref:`multiprocessing-managers`. This differs from the behaviour of :mod:`threading` where SIGINT will be ignored while the equivalent blocking calls are in progress. +.. note:: + + Some of this package's functionality requires a functioning shared semaphore + implementation on the host operating system. Without one, the + :mod:`multiprocessing.synchronize` module will be disabled, and attempts to + import it will result in an :exc:`ImportError`. See + :issue:`3770` for additional information. + Shared :mod:`ctypes` Objects ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Doc/library/othergui.rst b/Doc/library/othergui.rst index d75ca18..9ce9a16 100644 --- a/Doc/library/othergui.rst +++ b/Doc/library/othergui.rst @@ -39,7 +39,7 @@ available for Python: low-level device context drawing, drag and drop, system clipboard access, an XML-based resource format and more, including an ever growing library of user-contributed modules. wxPython has a book, `wxPython in Action - `_, by Noel Rappin and + `_, by Noel Rappin and Robin Dunn. PyGTK, PyQt, and wxPython, all have a modern look and feel and more diff --git a/Doc/library/profile.rst b/Doc/library/profile.rst index 0fb1489..c7007a6 100644 --- a/Doc/library/profile.rst +++ b/Doc/library/profile.rst @@ -663,7 +663,7 @@ you are using :class:`profile.Profile` or :class:`cProfile.Profile`, pr = cProfile.Profile(your_integer_time_func, 0.001) - As the :mod:`cProfile.Profile` class cannot be calibrated, custom timer + As the :class:`cProfile.Profile` class cannot be calibrated, custom timer functions should be used with care and should be as fast as possible. For the best results with a custom timer, it might be necessary to hard-code it in the C source of the internal :mod:`_lsprof` module. diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst index 494a48d..57521f7 100644 --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -53,6 +53,10 @@ produced for that file. executed on that occasion. Use an ``if __name__ == '__main__':`` guard to only execute code when a file is invoked as a script and not just imported. +When printing output to the console, :program:`pydoc` attempts to paginate the +output for easier reading. If the :envvar:`PAGER` environment variable is set, +:program:`pydoc` will use its value as a pagination program. + Specifying a ``-w`` flag before the argument will cause HTML documentation to be written out to a file in the current directory, instead of displaying text on the console. diff --git a/Doc/library/re.rst b/Doc/library/re.rst index db7e1cf..b353c4c 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -276,7 +276,9 @@ The special characters are: assertion`. ``(?<=abc)def`` will find a match in ``abcdef``, since the lookbehind will back up 3 characters and check if the contained pattern matches. The contained pattern must only match strings of some fixed length, meaning that - ``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Note that + ``abc`` or ``a|b`` are allowed, but ``a*`` and ``a{3,4}`` are not. Group + references are not supported even if they match strings of some fixed length. + Note that patterns which start with positive lookbehind assertions will not match at the beginning of the string being searched; you will most likely want to use the :func:`search` function rather than the :func:`match` function: @@ -296,7 +298,8 @@ The special characters are: Matches if the current position in the string is not preceded by a match for ``...``. This is called a :dfn:`negative lookbehind assertion`. Similar to positive lookbehind assertions, the contained pattern must only match strings of - some fixed length. Patterns which start with negative lookbehind assertions may + some fixed length and shouldn't contain group references. + Patterns which start with negative lookbehind assertions may match at the beginning of the string being searched. ``(?(id/name)yes-pattern|no-pattern)`` diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index fc9e7c1..a08bc94 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -72,6 +72,9 @@ The :mod:`runpy` module provides two functions: arguments. It is recommended that the :mod:`sys` module be left alone when invoking this function from threaded code. + .. seealso:: + The :option:`-m` option offering equivalent functionality from the + command line. .. versionchanged:: 2.7 Added ability to execute packages by looking for a ``__main__`` @@ -134,14 +137,18 @@ The :mod:`runpy` module provides two functions: limitations still apply, use of this function in threaded code should be either serialised with the import lock or delegated to a separate process. + .. seealso:: + :ref:`using-on-interface-options` for equivalent functionality on the + command line (``python path/to/script``). + .. versionadded:: 2.7 .. seealso:: - :pep:`338` - Executing modules as scripts + :pep:`338` -- Executing modules as scripts PEP written and implemented by Nick Coghlan. - :pep:`366` - Main module explicit relative imports + :pep:`366` -- Main module explicit relative imports PEP written and implemented by Nick Coghlan. :ref:`using-on-general` - CPython command line details diff --git a/Doc/library/sgmllib.rst b/Doc/library/sgmllib.rst index 1da19cf..84911fe 100644 --- a/Doc/library/sgmllib.rst +++ b/Doc/library/sgmllib.rst @@ -153,7 +153,7 @@ A single exception is defined as well: .. method:: SGMLParser.convert_codepoint(codepoint) - Convert a codepoint to a :class:`str` value. Encodings can be handled here if + Convert a code point to a :class:`str` value. Encodings can be handled here if appropriate, though the rest of :mod:`sgmllib` is oblivious on this matter. .. versionadded:: 2.5 diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index e897483..f350f5e 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -164,12 +164,9 @@ Directory and files operations Recursively move a file or directory (*src*) to another location (*dst*). - If the destination is a directory or a symlink to a directory, then *src* is - moved inside that directory. - - The destination directory must not already exist. If the destination already - exists but is not a directory, it may be overwritten depending on - :func:`os.rename` semantics. + If the destination is an existing directory, then *src* is moved inside that + directory. If the destination already exists but is not a directory, it may + be overwritten depending on :func:`os.rename` semantics. If the destination is on the current filesystem, then :func:`os.rename` is used. Otherwise, *src* is copied (using :func:`shutil.copy2`) to *dst* and diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index 8ef6cbe..c18d2a0 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -192,7 +192,7 @@ instead. ------------------------ --------- --------- ---------- --------- ----------- ----------- *SSLv2* yes no yes no no no *SSLv3* no yes yes no no no - *SSLv23* yes no yes no no no + *SSLv23* no yes yes yes yes yes *TLSv1* no no yes yes no no *TLSv1.1* no no yes no yes no *TLSv1.2* no no yes no no yes @@ -201,9 +201,8 @@ instead. .. note:: Which connections succeed will vary depending on the version of - OpenSSL. For example, beginning with OpenSSL 1.0.0, an SSLv23 client - will not actually attempt SSLv2 connections unless you explicitly - enable SSLv2 ciphers (which is not recommended, as SSLv2 is broken). + OpenSSL. For example, before OpenSSL 1.0.0, an SSLv23 client + would always attempt SSLv2 connections. The *ciphers* parameter sets the available ciphers for this SSL object. It should be a string in the `OpenSSL cipher list format @@ -246,14 +245,13 @@ purposes. :const:`None`, this function can choose to trust the system's default CA certificates instead. - The settings in Python 2.7.9 are: :data:`PROTOCOL_SSLv23`, - :data:`OP_NO_SSLv2`, and :data:`OP_NO_SSLv3` with high encryption cipher - suites without RC4 and without unauthenticated cipher suites. Passing - :data:`~Purpose.SERVER_AUTH` as *purpose* sets - :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED` and either loads CA - certificates (when at least one of *cafile*, *capath* or *cadata* is given) - or uses :meth:`SSLContext.load_default_certs` to load default CA - certificates. + The settings are: :data:`PROTOCOL_SSLv23`, :data:`OP_NO_SSLv2`, and + :data:`OP_NO_SSLv3` with high encryption cipher suites without RC4 and + without unauthenticated cipher suites. Passing :data:`~Purpose.SERVER_AUTH` + as *purpose* sets :data:`~SSLContext.verify_mode` to :data:`CERT_REQUIRED` + and either loads CA certificates (when at least one of *cafile*, *capath* or + *cadata* is given) or uses :meth:`SSLContext.load_default_certs` to load + default CA certificates. .. note:: The protocol, options, cipher and other settings may change to more @@ -265,29 +263,33 @@ purposes. .. note:: If you find that when certain older clients or servers attempt to connect - with a :class:`SSLContext` created by this function that they get an - error stating "Protocol or cipher suite mismatch", it may be that they - only support SSL3.0 which this function excludes using the - :data:`OP_NO_SSLv3`. SSL3.0 has problematic security due to a number of - poor implementations and it's reliance on MD5 within the protocol. If you - wish to continue to use this function but still allow SSL 3.0 connections - you can re-enable them using:: + with a :class:`SSLContext` created by this function that they get an error + stating "Protocol or cipher suite mismatch", it may be that they only + support SSL3.0 which this function excludes using the + :data:`OP_NO_SSLv3`. SSL3.0 is widely considered to be `completely broken + `_. If you still wish to continue to + use this function but still allow SSL 3.0 connections you can re-enable + them using:: ctx = ssl.create_default_context(Purpose.CLIENT_AUTH) ctx.options &= ~ssl.OP_NO_SSLv3 .. versionadded:: 2.7.9 + .. versionchanged:: 2.7.10 + + RC4 was dropped from the default cipher string. + Random generation ^^^^^^^^^^^^^^^^^ .. function:: RAND_status() - Returns ``True`` if the SSL pseudo-random number generator has been seeded with - 'enough' randomness, and ``False`` otherwise. You can use :func:`ssl.RAND_egd` - and :func:`ssl.RAND_add` to increase the randomness of the pseudo-random - number generator. + Return ``True`` if the SSL pseudo-random number generator has been seeded + with 'enough' randomness, and ``False`` otherwise. You can use + :func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of + the pseudo-random number generator. .. function:: RAND_egd(path) @@ -300,9 +302,11 @@ Random generation See http://egd.sourceforge.net/ or http://prngd.sourceforge.net/ for sources of entropy-gathering daemons. + Availability: not available with LibreSSL. + .. function:: RAND_add(bytes, entropy) - Mixes the given *bytes* into the SSL pseudo-random number generator. The + Mix the given *bytes* into the SSL pseudo-random number generator. The parameter *entropy* (a float) is a lower bound on the entropy contained in string (so you can always use :const:`0.0`). See :rfc:`1750` for more information on sources of entropy. @@ -481,9 +485,9 @@ Constants .. data:: VERIFY_DEFAULT - Possible value for :attr:`SSLContext.verify_flags`. In this mode, - certificate revocation lists (CRLs) are not checked. By default OpenSSL - does neither require nor verify CRLs. + Possible value for :attr:`SSLContext.verify_flags`. In this mode, certificate + revocation lists (CRLs) are not checked. By default OpenSSL does neither + require nor verify CRLs. .. versionadded:: 2.7.9 @@ -511,6 +515,14 @@ Constants .. versionadded:: 2.7.9 +.. data:: VERIFY_X509_TRUSTED_FIRST + + Possible value for :attr:`SSLContext.verify_flags`. It instructs OpenSSL to + prefer trusted certificates when building the trust chain to validate a + certificate. This flag is enabled by default. + + .. versionadded:: 2.7.10 + .. data:: PROTOCOL_SSLv23 Selects the highest protocol version that both the client and server support. @@ -637,6 +649,13 @@ Constants .. versionadded:: 2.7.9 +.. data:: HAS_ALPN + + Whether the OpenSSL library has built-in support for the *Application-Layer + Protocol Negotiation* TLS extension as described in :rfc:`7301`. + + .. versionadded:: 2.7.10 + .. data:: HAS_ECDH Whether the OpenSSL library has built-in support for Elliptic Curve-based @@ -863,9 +882,19 @@ SSL sockets also have the following additional methods and attributes: .. versionadded:: 2.7.9 +.. method:: SSLSocket.selected_alpn_protocol() + + Return the protocol that was selected during the TLS handshake. If + :meth:`SSLContext.set_alpn_protocols` was not called, if the other party does + not support ALPN, if this socket does not support any of the client's + proposed protocols, or if the handshake has not happened yet, ``None`` is + returned. + + .. versionadded:: 2.7.10 + .. method:: SSLSocket.selected_npn_protocol() - Returns the higher-level protocol that was selected during the TLS/SSL + Return the higher-level protocol that was selected during the TLS/SSL handshake. If :meth:`SSLContext.set_npn_protocols` was not called, or if the other party does not support NPN, or if the handshake has not yet happened, this will return ``None``. @@ -1033,6 +1062,20 @@ 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. +.. method:: SSLContext.set_alpn_protocols(protocols) + + Specify which protocols the socket should advertise during the SSL/TLS + handshake. It should be a list of ASCII strings, like ``['http/1.1', + 'spdy/2']``, ordered by preference. The selection of a protocol will happen + during the handshake, and will play out according to :rfc:`7301`. After a + successful handshake, the :meth:`SSLSocket.selected_alpn_protocol` method will + return the agreed-upon protocol. + + This method will raise :exc:`NotImplementedError` if :data:`HAS_ALPN` is + False. + + .. versionadded:: 2.7.10 + .. method:: SSLContext.set_npn_protocols(protocols) Specify which protocols the socket should advertise during the SSL/TLS @@ -1071,7 +1114,7 @@ to speed up repeated connections from the same clients. Due to the early negotiation phase of the TLS connection, only limited methods and attributes are usable like - :meth:`SSLSocket.selected_npn_protocol` and :attr:`SSLSocket.context`. + :meth:`SSLSocket.selected_alpn_protocol` and :attr:`SSLSocket.context`. :meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.getpeercert`, :meth:`SSLSocket.cipher` and :meth:`SSLSocket.compress` methods require that the TLS connection has progressed beyond the TLS Client Hello and therefore diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index fa4304c..bc437a4 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2031,16 +2031,32 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: Return the item of *d* with key *key*. Raises a :exc:`KeyError` if *key* is not in the map. + .. index:: __missing__() + + If a subclass of dict defines a method :meth:`__missing__` and *key* + is not present, the ``d[key]`` operation calls that method with the key *key* + as argument. The ``d[key]`` operation then returns or raises whatever is + returned or raised by the ``__missing__(key)`` call. + No other operations or methods invoke :meth:`__missing__`. If + :meth:`__missing__` is not defined, :exc:`KeyError` is raised. + :meth:`__missing__` must be a method; it cannot be an instance variable:: + + >>> class Counter(dict): + ... def __missing__(self, key): + ... return 0 + >>> c = Counter() + >>> c['red'] + 0 + >>> c['red'] += 1 + >>> c['red'] + 1 + + The example above shows part of the implementation of + :class:`collections.Counter`. A different ``__missing__`` method is used + by :class:`collections.defaultdict`. + .. versionadded:: 2.5 - If a subclass of dict defines a method :meth:`__missing__`, if the key - *key* is not present, the ``d[key]`` operation calls that method with - the key *key* as argument. The ``d[key]`` operation then returns or - raises whatever is returned or raised by the ``__missing__(key)`` call - if the key is not present. No other operations or methods invoke - :meth:`__missing__`. If :meth:`__missing__` is not defined, - :exc:`KeyError` is raised. :meth:`__missing__` must be a method; it - cannot be an instance variable. For an example, see - :class:`collections.defaultdict`. + Recognition of __missing__ methods of dict subclasses. .. describe:: d[key] = value diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 04ddef9..be2dd15 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -222,12 +222,13 @@ The module defines the following functions and data items: .. function:: sleep(secs) - Suspend execution for the given number of seconds. The argument may be a - floating point number to indicate a more precise sleep time. The actual - suspension time may be less than that requested because any caught signal will - terminate the :func:`sleep` following execution of that signal's catching - routine. Also, the suspension time may be longer than requested by an arbitrary - amount because of the scheduling of other activity in the system. + Suspend execution of the current thread for the given number of seconds. + The argument may be a floating point number to indicate a more precise sleep + time. The actual suspension time may be less than that requested because any + caught signal will terminate the :func:`sleep` following execution of that + signal's catching routine. Also, the suspension time may be longer than + requested by an arbitrary amount because of the scheduling of other activity + in the system. .. function:: strftime(format[, t]) diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 29f6959..846f96e 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -35,13 +35,13 @@ is maintained at ActiveState.) `Tcl/Tk manual `_ Official manual for the latest tcl/tk version. - `Programming Python `_ + `Programming Python `_ 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. - `Python and Tkinter Programming `_ + `Python and Tkinter Programming `_ The book by John Grayson (ISBN 1-884777-81-3). @@ -190,7 +190,7 @@ documentation that exists. Here are some hints: `Tcl and the Tk Toolkit `_ The book by John Ousterhout, the inventor of Tcl. - `Practical Programming in Tcl and Tk `_ + `Practical Programming in Tcl and Tk `_ Brent Welch's encyclopedic book. diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 556829a..bc3046a 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -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 `_ and `py.test `_ + `Nose `_ and `py.test `_ Third-party unittest frameworks with a lighter-weight syntax for writing tests. For example, ``assert func(10) == 42``. @@ -109,37 +109,29 @@ The :mod:`unittest` module provides a rich set of tools for constructing and running tests. This section demonstrates that a small subset of the tools suffice to meet the needs of most users. -Here is a short script to test three functions from the :mod:`random` module:: +Here is a short script to test three string methods:: - import random - import unittest - - class TestSequenceFunctions(unittest.TestCase): + import unittest - def setUp(self): - self.seq = range(10) + class TestStringMethods(unittest.TestCase): - def test_shuffle(self): - # make sure the shuffled sequence does not lose any elements - random.shuffle(self.seq) - self.seq.sort() - self.assertEqual(self.seq, range(10)) + def test_upper(self): + self.assertEqual('foo'.upper(), 'FOO') - # should raise an exception for an immutable sequence - self.assertRaises(TypeError, random.shuffle, (1,2,3)) + def test_isupper(self): + self.assertTrue('FOO'.isupper()) + self.assertFalse('Foo'.isupper()) - def test_choice(self): - element = random.choice(self.seq) - self.assertTrue(element in self.seq) + def test_split(self): + s = 'hello world' + self.assertEqual(s.split(), ['hello', 'world']) + # check that s.split fails when the separator is not a string + with self.assertRaises(TypeError): + s.split(2) - def test_sample(self): - with self.assertRaises(ValueError): - random.sample(self.seq, 20) - for element in random.sample(self.seq, 5): - self.assertTrue(element in self.seq) + if __name__ == '__main__': + unittest.main() - if __name__ == '__main__': - unittest.main() A testcase is created by subclassing :class:`unittest.TestCase`. The three individual tests are defined with methods whose names start with the letters @@ -147,16 +139,15 @@ individual tests are defined with methods whose names start with the letters represent tests. The crux of each test is a call to :meth:`~TestCase.assertEqual` to check for an -expected result; :meth:`~TestCase.assertTrue` to verify a condition; or -:meth:`~TestCase.assertRaises` to verify that an expected exception gets raised. -These methods are used instead of the :keyword:`assert` statement so the test -runner can accumulate all test results and produce a report. +expected result; :meth:`~TestCase.assertTrue` or :meth:`~TestCase.assertFalse` +to verify a condition; or :meth:`~TestCase.assertRaises` to verify that a +specific exception gets raised. These methods are used instead of the +:keyword:`assert` statement so the test runner can accumulate all test results +and produce a report. -When a :meth:`~TestCase.setUp` method is defined, the test runner will run that -method prior to each test. Likewise, if a :meth:`~TestCase.tearDown` method is -defined, the test runner will invoke that method after each test. In the -example, :meth:`~TestCase.setUp` was used to create a fresh sequence for each -test. +The :meth:`~TestCase.setUp` and :meth:`~TestCase.tearDown` methods allow you +to define instructions that will be executed before and after each test method. +They are covered in more details in the section :ref:`organizing-tests`. The final block shows a simple way to run the tests. :func:`unittest.main` provides a command-line interface to the test script. When run from the command @@ -172,18 +163,18 @@ Instead of :func:`unittest.main`, there are other ways to run the tests with a finer level of control, less terse output, and no requirement to be run from the command line. For example, the last two lines may be replaced with:: - suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions) + suite = unittest.TestLoader().loadTestsFromTestCase(TestStringMethods) unittest.TextTestRunner(verbosity=2).run(suite) Running the revised script from the interpreter or another script produces the following output:: - test_choice (__main__.TestSequenceFunctions) ... ok - test_sample (__main__.TestSequenceFunctions) ... ok - test_shuffle (__main__.TestSequenceFunctions) ... ok + test_isupper (__main__.TestStringMethods) ... ok + test_split (__main__.TestStringMethods) ... ok + test_upper (__main__.TestStringMethods) ... ok ---------------------------------------------------------------------- - Ran 3 tests in 0.110s + Ran 3 tests in 0.001s OK diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst index b2a817d..d0cc548 100644 --- a/Doc/library/urllib.rst +++ b/Doc/library/urllib.rst @@ -24,6 +24,11 @@ built-in function :func:`open`, but accepts Universal Resource Locators (URLs) instead of filenames. Some restrictions apply --- it can only open URLs for reading, and no seek operations are available. +.. seealso:: + + The `Requests package `_ + is recommended for a higher-level http client interface. + .. warning:: When opening HTTPS URLs, it does not attempt to validate the server certificate. Use at your own risk! diff --git a/Doc/library/urllib2.rst b/Doc/library/urllib2.rst index f599894..3fe4f25 100644 --- a/Doc/library/urllib2.rst +++ b/Doc/library/urllib2.rst @@ -18,6 +18,11 @@ The :mod:`urllib2` module defines functions and classes which help in opening URLs (mostly HTTP) in a complex world --- basic and digest authentication, redirections, cookies and more. +.. seealso:: + + The `Requests package `_ + is recommended for a higher-level http client interface. + The :mod:`urllib2` module defines the following functions: diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 3afabb4..46396dd 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -266,6 +266,73 @@ sub-elements for a given element:: >>> ET.dump(a) +Parsing XML with Namespaces +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the XML input has `namespaces +`__, tags and attributes +with prefixes in the form ``prefix:sometag`` get expanded to +``{uri}sometag`` where the *prefix* is replaced by the full *URI*. +Also, if there is a `default namespace +`__, +that full URI gets prepended to all of the non-prefixed tags. + +Here is an XML example that incorporates two namespaces, one with the +prefix "fictional" and the other serving as the default namespace: + +.. code-block:: xml + + + + + John Cleese + Lancelot + Archie Leach + + + Eric Idle + Sir Robin + Gunther + Commander Clement + + + +One way to search and explore this XML example is to manually add the +URI to every tag or attribute in the xpath of a +:meth:`~Element.find` or :meth:`~Element.findall`:: + + root = fromstring(xml_text) + for actor in root.findall('{http://people.example.com}actor'): + name = actor.find('{http://people.example.com}name') + print name.text + for char in actor.findall('{http://characters.example.com}character'): + print ' |-->', char.text + + +A better way to search the namespaced XML example is to create a +dictionary with your own prefixes and use those in the search functions:: + + ns = {'real_person': 'http://people.example.com', + 'role': 'http://characters.example.com'} + + for actor in root.findall('real_person:actor', ns): + name = actor.find('real_person:name', ns) + print name.text + for char in actor.findall('role:character', ns): + print ' |-->', char.text + +These two approaches both output:: + + John Cleese + |--> Lancelot + |--> Archie Leach + Eric Idle + |--> Sir Robin + |--> Gunther + |--> Commander Clement + + Additional resources ^^^^^^^^^^^^^^^^^^^^ @@ -345,6 +412,10 @@ Supported XPath syntax | ``[tag]`` | Selects all elements that have a child named | | | ``tag``. Only immediate children are supported. | +-----------------------+------------------------------------------------------+ +| ``[tag='text']`` | Selects all elements that have a child named | +| | ``tag`` whose complete text content, including | +| | descendants, equals the given ``text``. | ++-----------------------+------------------------------------------------------+ | ``[position]`` | Selects all elements that are located at the given | | | position. The position can be either an integer | | | (1 is the first position), the expression ``last()`` | diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 261747a..173dfb0 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -212,6 +212,8 @@ ZipFile Objects to extract to. *member* can be a filename or a :class:`ZipInfo` object. *pwd* is the password used for encrypted files. + Returns the normalized path created (a directory or new file). + .. versionadded:: 2.6 .. note:: diff --git a/Doc/license.rst b/Doc/license.rst index 6a23fc0..c47f478 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -84,7 +84,7 @@ Terms and conditions for accessing or otherwise using Python 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-2014 Python Software Foundation; All Rights + copyright, i.e., "Copyright © 2001-2015 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 1070166..251f822 100644 --- a/Doc/make.bat +++ b/Doc/make.bat @@ -1,124 +1,124 @@ -@echo off -setlocal - -pushd %~dp0 - -set this=%~n0 - -if "%SPHINXBUILD%" EQU "" set SPHINXBUILD=sphinx-build -if "%PYTHON%" EQU "" set PYTHON=py - -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 - -if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/extensions/patchlevel.py`) do set DISTVERSION=%%v - -if "%BUILDDIR%" EQU "" set BUILDDIR=build - -rem Targets that don't require sphinx-build -if "%1" EQU "" goto help -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% - goto end -) - -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - goto end -) - -rem Targets that do require sphinx-build and have their own label -if "%1" EQU "htmlview" goto htmlview - -rem Everything else -goto build - -:help -echo.usage: %this% BUILDER [filename ...] -echo. -echo.Call %this% with the desired Sphinx builder as the first argument, e.g. -echo.``%this% html`` or ``%this% doctest``. Interesting targets that are -echo.always available include: -echo. -echo. Provided by Sphinx: -echo. html, htmlhelp, latex, text -echo. suspicious, linkcheck, changes, doctest -echo. Provided by this script: -echo. clean, check, serve, htmlview -echo. -echo.All arguments past the first one are passed through to sphinx-build as -echo.filenames to build or are ignored. See README.txt in this directory or -echo.the documentation for your version of Sphinx for more exhaustive lists -echo.of available targets and descriptions of each. -echo. -echo.This script assumes that the SPHINXBUILD environment variable contains -echo.a legitimate command for calling sphinx-build, or that sphinx-build is -echo.on your PATH if SPHINXBUILD is not set. Options for sphinx-build can -echo.be passed by setting the SPHINXOPTS environment variable. -goto end - -:build -if NOT "%PAPER%" == "" ( - set SPHINXOPTS=-D latex_paper_size=%PAPER% %SPHINXOPTS% -) -cmd /C %SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%* - -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 - 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 -) - -echo. -if errorlevel 1 ( - echo.Build failed (exit code %ERRORLEVEL%^), check for error messages - echo.above. Any output will be found in %BUILDDIR%\%1 -) else ( - echo.Build succeeded. All output should be in %BUILDDIR%\%1 -) -goto end - -:htmlview -if NOT "%2" EQU "" ( - echo.Can't specify filenames to build with htmlview target, ignoring. -) -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 -) - -goto end - -:check -cmd /C %PYTHON% tools\rstlint.py -i tools -goto end - -:serve -cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html -goto end - -:end -popd +@echo off +setlocal + +pushd %~dp0 + +set this=%~n0 + +if "%SPHINXBUILD%" EQU "" set SPHINXBUILD=sphinx-build +if "%PYTHON%" EQU "" set PYTHON=py + +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 + +if "%DISTVERSION%" EQU "" for /f "usebackq" %%v in (`%PYTHON% tools/extensions/patchlevel.py`) do set DISTVERSION=%%v + +if "%BUILDDIR%" EQU "" set BUILDDIR=build + +rem Targets that don't require sphinx-build +if "%1" EQU "" goto help +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% + goto end +) + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + goto end +) + +rem Targets that do require sphinx-build and have their own label +if "%1" EQU "htmlview" goto htmlview + +rem Everything else +goto build + +:help +echo.usage: %this% BUILDER [filename ...] +echo. +echo.Call %this% with the desired Sphinx builder as the first argument, e.g. +echo.``%this% html`` or ``%this% doctest``. Interesting targets that are +echo.always available include: +echo. +echo. Provided by Sphinx: +echo. html, htmlhelp, latex, text +echo. suspicious, linkcheck, changes, doctest +echo. Provided by this script: +echo. clean, check, serve, htmlview +echo. +echo.All arguments past the first one are passed through to sphinx-build as +echo.filenames to build or are ignored. See README.txt in this directory or +echo.the documentation for your version of Sphinx for more exhaustive lists +echo.of available targets and descriptions of each. +echo. +echo.This script assumes that the SPHINXBUILD environment variable contains +echo.a legitimate command for calling sphinx-build, or that sphinx-build is +echo.on your PATH if SPHINXBUILD is not set. Options for sphinx-build can +echo.be passed by setting the SPHINXOPTS environment variable. +goto end + +:build +if NOT "%PAPER%" == "" ( + set SPHINXOPTS=-D latex_paper_size=%PAPER% %SPHINXOPTS% +) +cmd /C %SPHINXBUILD% %SPHINXOPTS% -b%1 -dbuild\doctrees . %BUILDDIR%\%* + +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 + 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 +) + +echo. +if errorlevel 1 ( + echo.Build failed (exit code %ERRORLEVEL%^), check for error messages + echo.above. Any output will be found in %BUILDDIR%\%1 +) else ( + echo.Build succeeded. All output should be in %BUILDDIR%\%1 +) +goto end + +:htmlview +if NOT "%2" EQU "" ( + echo.Can't specify filenames to build with htmlview target, ignoring. +) +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 +) + +goto end + +:check +cmd /C %PYTHON% tools\rstlint.py -i tools +goto end + +:serve +cmd /C %PYTHON% ..\Tools\scripts\serve.py %BUILDDIR%\html +goto end + +:end +popd diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 206853b..c61c55b 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1225,13 +1225,17 @@ Basic customization .. index:: pair: class; constructor - Called when the instance is created. The arguments are those passed to the + Called after the instance has been created (by :meth:`__new__`), but before + it is returned to the caller. The arguments are those passed to the class constructor expression. If a base class has an :meth:`__init__` method, the derived class's :meth:`__init__` method, if any, must explicitly call it to ensure proper initialization of the base class part of the instance; for - example: ``BaseClass.__init__(self, [args...])``. As a special constraint on - constructors, no value may be returned; doing so will cause a :exc:`TypeError` - to be raised at runtime. + example: ``BaseClass.__init__(self, [args...])``. + + Because :meth:`__new__` and :meth:`__init__` work together in constructing + objects (:meth:`__new__` to create it, and :meth:`__init__` to customise it), + no non-``None`` value may be returned by :meth:`__init__`; doing so will + cause a :exc:`TypeError` to be raised at runtime. .. method:: object.__del__(self) @@ -1904,6 +1908,12 @@ 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 @@ -1983,15 +1993,15 @@ objects. Immutable sequences methods should at most only define :meth:`__getslice__`. Therefore, you have to override it in derived classes when implementing slicing.) - Called to implement evaluation of ``self[i:j]``. The returned object should be - of the same type as *self*. Note that missing *i* or *j* in the slice - expression are replaced by zero or ``sys.maxint``, respectively. If negative - indexes are used in the slice, the length of the sequence is added to that - index. If the instance does not implement the :meth:`__len__` method, an - :exc:`AttributeError` is raised. No guarantee is made that indexes adjusted this - way are not still negative. Indexes which are greater than the length of the - sequence are not modified. If no :meth:`__getslice__` is found, a slice object - is created instead, and passed to :meth:`__getitem__` instead. + Called to implement evaluation of ``self[i:j]``. The returned object should + be of the same type as *self*. Note that missing *i* or *j* in the slice + expression are replaced by zero or :attr:`sys.maxsize`, respectively. If + negative indexes are used in the slice, the length of the sequence is added + to that index. If the instance does not implement the :meth:`__len__` method, + an :exc:`AttributeError` is raised. No guarantee is made that indexes + adjusted this way are not still negative. Indexes which are greater than the + length of the sequence are not modified. If no :meth:`__getslice__` is found, + a slice object is created instead, and passed to :meth:`__getitem__` instead. .. method:: object.__setslice__(self, i, j, sequence) diff --git a/Doc/tools/static/basic.css b/Doc/tools/static/basic.css index 21c3db2..85a4318 100644 --- a/Doc/tools/static/basic.css +++ b/Doc/tools/static/basic.css @@ -306,7 +306,7 @@ dd { margin-left: 30px; } -dt:target, .highlight { +dt:target, .highlighted { background-color: #fbe54e; } diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst index 2d79a00..89589bc 100644 --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -179,9 +179,9 @@ There are three built-in functions that are very useful when used with lists: ``filter(function, sequence)`` returns a sequence consisting of those items from the sequence for which ``function(item)`` is true. If *sequence* is a -:class:`string` or :class:`tuple`, the result will be of the same type; -otherwise, it is always a :class:`list`. For example, to compute a sequence of -numbers divisible by 3 or 5:: +:class:`str`, :class:`unicode` or :class:`tuple`, the result will be of the +same type; otherwise, it is always a :class:`list`. For example, to compute a +sequence of numbers divisible by 3 or 5:: >>> def f(x): return x % 3 == 0 or x % 5 == 0 ... diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index 514c5f1..67f927f 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -62,6 +62,8 @@ When a script file is used, it is sometimes useful to be able to run the script and enter interactive mode afterwards. This can be done by passing :option:`-i` before the script. +All command-line options are described in :ref:`using-on-general`. + .. _tut-argpassing: @@ -138,7 +140,7 @@ encodings can be found in the Python Library Reference, in the section on For example, to write Unicode literals including the Euro currency symbol, the ISO-8859-15 encoding can be used, with the Euro symbol having the ordinal value 164. This script, when saved in the ISO-8859-15 encoding, will print the value -8364 (the Unicode codepoint corresponding to the Euro symbol) and then exit:: +8364 (the Unicode code point corresponding to the Euro symbol) and then exit:: # -*- coding: iso-8859-15 -*- diff --git a/Doc/tutorial/introduction.rst b/Doc/tutorial/introduction.rst index d30b194..e5ced49 100644 --- a/Doc/tutorial/introduction.rst +++ b/Doc/tutorial/introduction.rst @@ -170,7 +170,7 @@ and special characters:: >>> print '"Isn\'t," she said.' "Isn't," she said. >>> s = 'First line.\nSecond line.' # \n means newline - >>> s # without print(), \n is included in the output + >>> s # without print, \n is included in the output 'First line.\nSecond line.' >>> print s # with print, \n produces a new line First line. @@ -309,7 +309,7 @@ indices, if both are within bounds. For example, the length of ``word[1:3]`` is Attempting to use a index that is too large will result in an error:: - >>> word[42] # the word only has 7 characters + >>> word[42] # the word only has 6 characters Traceback (most recent call last): File "", line 1, in IndexError: string index out of range diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index b657f3f..ce5e76f 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -1,7 +1,7 @@ -.. highlightlang:: none +.. highlightlang:: sh .. ATTENTION: You probably should update Misc/python.man, too, if you modify -.. this file. + this file. .. _using-on-general: @@ -130,6 +130,10 @@ source. ``"-"`` and the current directory will be added to the start of :data:`sys.path`. + .. seealso:: + :func:`runpy.run_path` + Equivalent functionality directly available to Python code + .. describe::