diff options
Diffstat (limited to 'Doc/library')
71 files changed, 3471 insertions, 943 deletions
diff --git a/Doc/library/2to3.rst b/Doc/library/2to3.rst index 97e692f..158b3be 100644 --- a/Doc/library/2to3.rst +++ b/Doc/library/2to3.rst @@ -342,6 +342,10 @@ and off individually. They are described here in more detail. Handles the move of :func:`reduce` to :func:`functools.reduce`. +.. 2to3fixer:: reload + + Converts :func:`reload` to :func:`imp.reload`. + .. 2to3fixer:: renames Changes :data:`sys.maxint` to :data:`sys.maxsize`. diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst index 6f23596..1f21b57 100644 --- a/Doc/library/abc.rst +++ b/Doc/library/abc.rst @@ -12,9 +12,9 @@ -------------- This module provides the infrastructure for defining :term:`abstract base -classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this -was added to Python. (See also :pep:`3141` and the :mod:`numbers` module -regarding a type hierarchy for numbers based on ABCs.) +classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; +see the PEP for why this was added to Python. (See also :pep:`3141` and the +:mod:`numbers` module regarding a type hierarchy for numbers based on ABCs.) The :mod:`collections` module has some concrete classes that derive from ABCs; these can, of course, be further derived. In addition the @@ -23,7 +23,7 @@ a class or instance provides a particular interface, for example, is it hashable or a mapping. -This module provides the following class: +This module provides the following classes: .. class:: ABCMeta @@ -58,6 +58,10 @@ This module provides the following class: .. versionchanged:: 3.3 Returns the registered subclass, to allow usage as a class decorator. + .. versionchanged:: 3.4 + To detect calls to :meth:`register`, you can use the + :func:`get_cache_token` function. + You can also override this method in an abstract base class: .. method:: __subclasshook__(subclass) @@ -127,6 +131,19 @@ This module provides the following class: available as a method of ``Foo``, so it is provided separately. +.. class:: ABC + + A helper class that has :class:`ABCMeta` as its metaclass. With this class, + an abstract base class can be created by simply deriving from :class:`ABC`, + avoiding sometimes confusing metaclass usage. + + Note that the type of :class:`ABC` is still :class:`ABCMeta`, therefore + inheriting from :class:`ABC` requires the usual precautions regarding metaclass + usage, as multiple inheritance may lead to metaclass conflicts. + + .. versionadded:: 3.4 + + The :mod:`abc` module also provides the following decorators: .. decorator:: abstractmethod @@ -295,6 +312,19 @@ The :mod:`abc` module also provides the following decorators: :func:`abstractmethod`, making this decorator redundant. +The :mod:`abc` module also provides the following functions: + +.. function:: get_cache_token() + + Returns the current abstract base class cache token. + + The token is an opaque integer identifying the current version of the + abstract base class cache for virtual subclasses. This number changes + with every call to :meth:`ABCMeta.register` on any ABC. + + .. versionadded:: 3.4 + + .. rubric:: Footnotes .. [#] C++ programmers should note that Python's virtual base class diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst index 999bad8..44a0a24 100644 --- a/Doc/library/aifc.rst +++ b/Doc/library/aifc.rst @@ -51,6 +51,11 @@ Module :mod:`aifc` defines the following function: used for writing, the file object should be seekable, unless you know ahead of time how many samples you are going to write in total and use :meth:`writeframesraw` and :meth:`setnframes`. + The :func:`.open` function may be used in a :keyword:`with` statement. When + the :keyword:`with` block completes, the :meth:`~aifc.close` method is called. + +.. versionchanged:: 3.4 + Support for the :keyword:`with` statement was added. Objects returned by :func:`.open` when a file is opened for reading have the following methods: @@ -92,7 +97,9 @@ following methods: .. method:: aifc.getparams() - Return a tuple consisting of all of the above values in the above order. + Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, + framerate, nframes, comptype, compname)``, equivalent to output of the + :meth:`get\*` methods. .. method:: aifc.getmarkers() diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 7267ae4..f3eb9dd 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -977,9 +977,9 @@ See the section on the default_ keyword argument for information on when the ``type`` argument is applied to default arguments. To ease the use of various types of files, the argparse module provides the -factory FileType which takes the ``mode=`` and ``bufsize=`` arguments of the -:func:`open` function. For example, ``FileType('w')`` can be used to create a -writable file:: +factory FileType which takes the ``mode=``, ``bufsize=``, ``encoding=`` and +``errors=`` arguments of the :func:`open` function. For example, +``FileType('w')`` can be used to create a writable file:: >>> parser = argparse.ArgumentParser() >>> parser.add_argument('bar', type=argparse.FileType('w')) @@ -1619,17 +1619,19 @@ Sub-commands FileType objects ^^^^^^^^^^^^^^^^ -.. class:: FileType(mode='r', bufsize=None) +.. class:: FileType(mode='r', bufsize=-1, encoding=None, errors=None) The :class:`FileType` factory creates objects that can be passed to the type argument of :meth:`ArgumentParser.add_argument`. Arguments that have - :class:`FileType` objects as their type will open command-line arguments as files - with the requested modes and buffer sizes:: + :class:`FileType` objects as their type will open command-line arguments as + files with the requested modes, buffer sizes, encodings and error handling + (see the :func:`open` function for more details):: >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--output', type=argparse.FileType('wb', 0)) - >>> parser.parse_args(['--output', 'out']) - Namespace(output=<_io.BufferedWriter name='out'>) + >>> parser.add_argument('--raw', type=argparse.FileType('wb', 0)) + >>> parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8')) + >>> parser.parse_args(['--raw', 'raw.dat', 'file.txt']) + Namespace(out=<_io.TextIOWrapper name='file.txt' mode='w' encoding='UTF-8'>, raw=<_io.FileIO name='raw.dat' mode='wb'>) FileType objects understand the pseudo-argument ``'-'`` and automatically convert this into ``sys.stdin`` for readable :class:`FileType` objects and diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index a65fe5b..96c5aef 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -76,14 +76,19 @@ The class can be used to simulate nested scopes and is useful in templating. be modified to change which mappings are searched. The list should always contain at least one mapping. - .. method:: new_child() + .. method:: new_child(m=None) - Returns a new :class:`ChainMap` containing a new :class:`dict` followed by - all of the maps in the current instance. A call to ``d.new_child()`` is - equivalent to: ``ChainMap({}, *d.maps)``. This method is used for + Returns a new :class:`ChainMap` containing a new map followed by + all of the maps in the current instance. If ``m`` is specified, + it becomes the new map at the front of the list of mappings; if not + specified, an empty dict is used, so that a call to ``d.new_child()`` + is equivalent to: ``ChainMap({}, *d.maps)``. This method is used for creating subcontexts that can be updated without altering values in any of the parent mappings. + .. versionchanged:: 3.4 + The optional ``m`` parameter was added. + .. attribute:: parents Property returning a new :class:`ChainMap` containing all of the maps in diff --git a/Doc/library/contextlib.rst b/Doc/library/contextlib.rst index fba48f4..349b805 100644 --- a/Doc/library/contextlib.rst +++ b/Doc/library/contextlib.rst @@ -94,6 +94,26 @@ Functions and classes provided: without needing to explicitly close ``page``. Even if an error occurs, ``page.close()`` will be called when the :keyword:`with` block is exited. +.. function:: ignored(*exceptions) + + Return a context manager that ignores the specified exceptions if they + occur in the body of a with-statement. + + For example:: + + from contextlib import ignored + + with ignored(OSError): + os.remove('somefile.tmp') + + This code is equivalent to:: + + try: + os.remove('somefile.tmp') + except OSError: + pass + + .. versionadded:: 3.4 .. class:: ContextDecorator() diff --git a/Doc/library/datatypes.rst b/Doc/library/datatypes.rst index d0382e0..48af082 100644 --- a/Doc/library/datatypes.rst +++ b/Doc/library/datatypes.rst @@ -30,3 +30,4 @@ The following modules are documented in this chapter: copy.rst pprint.rst reprlib.rst + enum.rst diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 30b63e1..bb268e1 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -170,10 +170,12 @@ dates or times. * ``0 <= seconds < 3600*24`` (the number of seconds in one day) * ``-999999999 <= days <= 999999999`` - If any argument is a float and there are fractional microseconds, the fractional - microseconds left over from all arguments are combined and their sum is rounded - to the nearest microsecond. If no argument is a float, the conversion and - normalization processes are exact (no information is lost). + If any argument is a float and there are fractional microseconds, + the fractional microseconds left over from all arguments are + combined and their sum is rounded to the nearest microsecond using + round-half-to-even tiebreaker. If no argument is a float, the + conversion and normalization processes are exact (no information is + lost). If the normalized value of days lies outside the indicated range, :exc:`OverflowError` is raised. diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 4339f55..a546f68 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -26,7 +26,8 @@ Example: Given the function :func:`myfunc`:: def myfunc(alist): return len(alist) -the following command can be used to get the disassembly of :func:`myfunc`:: +the following command can be used to display the disassembly of +:func:`myfunc`:: >>> dis.dis(myfunc) 2 0 LOAD_GLOBAL 0 (len) @@ -36,8 +37,62 @@ the following command can be used to get the disassembly of :func:`myfunc`:: (The "2" is a line number). -The :mod:`dis` module defines the following functions and constants: +Bytecode analysis +----------------- +The bytecode analysis API allows pieces of Python code to be wrapped in a +:class:`Bytecode` object that provides easy access to details of the +compiled code. + +.. class:: Bytecode + + The bytecode operations of a piece of code + + This is a convenient wrapper around many of the functions listed below. + Instantiate it with a function, method, string of code, or a code object + (as returned by :func:`compile`). + + Iterating over this yields the bytecode operations as :class:`Instruction` + instances. + + .. data:: codeobj + + The compiled code object. + + .. method:: display_code(*, file=None) + + Print a formatted view of the bytecode operations, like :func:`dis`. + + .. method:: info() + + Return a formatted multi-line string with detailed information about the + code object, like :func:`code_info`. + + .. method:: show_info(*, file=None) + + Print the information about the code object as returned by :meth:`info`. + + .. versionadded:: 3.4 + +Example:: + + >>> bytecode = dis.Bytecode(myfunc) + >>> for instr in bytecode: + ... print(instr.opname) + ... + LOAD_GLOBAL + LOAD_FAST + CALL_FUNCTION + RETURN_VALUE + + +Analysis functions +------------------ + +The :mod:`dis` module also defines the following analysis functions that +convert the input directly to the desired output. They can be useful if +only a single operation is being performed, so the intermediate analysis +object isn't useful: .. function:: code_info(x) @@ -51,17 +106,22 @@ The :mod:`dis` module defines the following functions and constants: .. versionadded:: 3.2 -.. function:: show_code(x) +.. function:: show_code(x, *, file=None) Print detailed code object information for the supplied function, method, - source code string or code object to stdout. + source code string or code object to *file* (or ``sys.stdout`` if *file* + is not specified). - This is a convenient shorthand for ``print(code_info(x))``, intended for - interactive exploration at the interpreter prompt. + This is a convenient shorthand for ``print(code_info(x), file=file)``, + intended for interactive exploration at the interpreter prompt. .. versionadded:: 3.2 -.. function:: dis(x=None) + .. versionchanged:: 3.4 + Added ``file`` parameter + + +.. function:: dis(x=None, *, file=None) Disassemble the *x* object. *x* can denote either a module, a class, a method, a function, a code object, a string of source code or a byte sequence @@ -72,16 +132,28 @@ The :mod:`dis` module defines the following functions and constants: disassembled. If no object is provided, this function disassembles the last traceback. + The disassembly is written as text to the supplied ``file`` argument if + provided and to ``sys.stdout`` otherwise. + + .. versionchanged:: 3.4 + Added ``file`` parameter + -.. function:: distb(tb=None) +.. function:: distb(tb=None, *, file=None) Disassemble the top-of-stack function of a traceback, using the last traceback if none was passed. The instruction causing the exception is indicated. + The disassembly is written as text to the supplied ``file`` argument if + provided and to ``sys.stdout`` otherwise. -.. function:: disassemble(code, lasti=-1) - disco(code, lasti=-1) + .. versionchanged:: 3.4 + Added ``file`` parameter + + +.. function:: disassemble(code, lasti=-1, *, file=None) + disco(code, lasti=-1, *, file=None) Disassemble a code object, indicating the last instruction if *lasti* was provided. The output is divided in the following columns: @@ -97,6 +169,26 @@ The :mod:`dis` module defines the following functions and constants: The parameter interpretation recognizes local and global variable names, constant values, branch targets, and compare operators. + The disassembly is written as text to the supplied ``file`` argument if + provided and to ``sys.stdout`` otherwise. + + .. versionchanged:: 3.4 + Added ``file`` parameter + + +.. function:: get_instructions(x, *, line_offset=0) + + Return an iterator over the instructions in the supplied function, method, + source code string or code object. + + The iterator generates a series of :class:`Instruction` named tuples + giving the details of each operation in the supplied code. + + The given *line_offset* is added to the ``starts_line`` attribute of any + instructions that start a new line. + + .. versionadded:: 3.4 + .. function:: findlinestarts(code) @@ -110,61 +202,60 @@ The :mod:`dis` module defines the following functions and constants: Detect all offsets in the code object *code* which are jump targets, and return a list of these offsets. +.. _bytecodes: -.. data:: opname +Python Bytecode Instructions +---------------------------- - Sequence of operation names, indexable using the bytecode. +The :func:`get_instructions` function and :class:`Bytecode` class provide +details of bytecode instructions as :class:`Instruction` instances: +.. class:: Instruction -.. data:: opmap + Details for a bytecode operation - Dictionary mapping operation names to bytecodes. + .. data:: opcode + numeric code for operation, corresponding to the opcode values listed + below and the bytecode values in the :ref:`opcode_collections`. -.. data:: cmp_op - Sequence of all compare operation names. + .. data:: opname + human readable name for operation -.. data:: hasconst - Sequence of bytecodes that have a constant parameter. + .. data:: arg + numeric argument to operation (if any), otherwise None -.. data:: hasfree - Sequence of bytecodes that access a free variable. + .. data:: argval - -.. data:: hasname - - Sequence of bytecodes that access an attribute by name. + resolved arg value (if known), otherwise same as arg -.. data:: hasjrel - - Sequence of bytecodes that have a relative jump target. + .. data:: argrepr + human readable description of operation argument -.. data:: hasjabs - Sequence of bytecodes that have an absolute jump target. + .. data:: offset + start index of operation within bytecode sequence -.. data:: haslocal - Sequence of bytecodes that access a local variable. + .. data:: starts_line + line started by this opcode (if any), otherwise None -.. data:: hascompare - Sequence of bytecodes of Boolean operations. + .. data:: is_jump_target + True if other code jumps to here, otherwise False -.. _bytecodes: + .. versionadded:: 3.4 -Python Bytecode Instructions ----------------------------- The Python compiler currently generates the following bytecode instructions. @@ -506,12 +597,6 @@ the stack so that it is available for further iterations of the loop. .. XXX explain the WHY stuff! -.. opcode:: STORE_LOCALS - - Pops TOS from the stack and stores it as the current frame's ``f_locals``. - This is used in class construction. - - All of the following opcodes expect arguments. An argument is two bytes, with the more significant byte last. @@ -722,6 +807,13 @@ the more significant byte last. Pushes a reference to the object the cell contains on the stack. +.. opcode:: LOAD_CLASSDEREF (i) + + Much like :opcode:`LOAD_DEREF` but first checks the locals dictionary before + consulting the cell. This is used for loading free variables in class + bodies. + + .. opcode:: STORE_DEREF (i) Stores TOS into the cell contained in slot *i* of the cell and free variable @@ -813,3 +905,62 @@ the more significant byte last. which don't take arguments ``< HAVE_ARGUMENT`` and those which do ``>= HAVE_ARGUMENT``. +.. _opcode_collections: + +Opcode collections +------------------ + +These collections are provided for automatic introspection of bytecode +instructions: + +.. data:: opname + + Sequence of operation names, indexable using the bytecode. + + +.. data:: opmap + + Dictionary mapping operation names to bytecodes. + + +.. data:: cmp_op + + Sequence of all compare operation names. + + +.. data:: hasconst + + Sequence of bytecodes that have a constant parameter. + + +.. data:: hasfree + + Sequence of bytecodes that access a free variable (note that 'free' in + this context refers to names in the current scope that are referenced by + inner scopes or names in outer scopes that are referenced from this scope. + It does *not* include references to global or builtin scopes). + + +.. data:: hasname + + Sequence of bytecodes that access an attribute by name. + + +.. data:: hasjrel + + Sequence of bytecodes that have a relative jump target. + + +.. data:: hasjabs + + Sequence of bytecodes that have an absolute jump target. + + +.. data:: haslocal + + Sequence of bytecodes that access a local variable. + + +.. data:: hascompare + + Sequence of bytecodes of Boolean operations. diff --git a/Doc/library/doctest.rst b/Doc/library/doctest.rst index 222c719..6138e30 100644 --- a/Doc/library/doctest.rst +++ b/Doc/library/doctest.rst @@ -495,7 +495,10 @@ Option Flags A number of option flags control various aspects of doctest's behavior. Symbolic names for the flags are supplied as module constants, which can be or'ed together and passed to various functions. The names can also be used in -:ref:`doctest directives <doctest-directives>`. +:ref:`doctest directives <doctest-directives>`, and may be passed to the +doctest command line interface via the ``-o`` option. + +.. versionadded:: 3.4 the ``-o`` command line option The first group of options define test semantics, controlling aspects of how doctest decides whether actual output matches an example's expected output: @@ -633,6 +636,19 @@ The second group of options controls how test failures are reported: the output is suppressed. +.. data:: FAIL_FAST + + When specified, exit after the first failing example and don't attempt to run + the remaining examples. Thus, the number of failures reported will be at most + 1. This flag may be useful during debugging, since examples after the first + failure won't even produce debugging output. + + The doctest command line accepts the option ``-f`` as a shorthand for ``-o + FAIL_FAST``. + + .. versionadded:: 3.4 + + .. data:: REPORTING_FLAGS A bitmask or'ing together all the reporting flags above. diff --git a/Doc/library/email.message.rst b/Doc/library/email.message.rst index 576531d..4a34c36 100644 --- a/Doc/library/email.message.rst +++ b/Doc/library/email.message.rst @@ -42,14 +42,21 @@ Here are the methods of the :class:`Message` class: .. versionchanged:: 3.3 The *policy* keyword argument was added. - .. method:: as_string(unixfrom=False, maxheaderlen=0) + .. method:: as_string(unixfrom=False, maxheaderlen=0, policy=None) Return the entire message flattened as a string. When optional *unixfrom* - is ``True``, the envelope header is included in the returned string. - *unixfrom* defaults to ``False``. Flattening the message may trigger - changes to the :class:`Message` if defaults need to be filled in to - complete the transformation to a string (for example, MIME boundaries may - be generated or modified). + is true, the envelope header is included in the returned string. + *unixfrom* defaults to ``False``. For backward compabitility reasons, + *maxheaderlen* defaults to ``0``, so if you want a different value you + must override it explicitly (the value specified for *max_line_length* in + the policy will be ignored by this method). The *policy* argument may be + used to override the default policy obtained from the message instance. + This can be used to control some of the formatting produced by the + method, since the specified *policy* will be passed to the ``Generator``. + + Flattening the message may trigger changes to the :class:`Message` if + defaults need to be filled in to complete the transformation to a string + (for example, MIME boundaries may be generated or modified). Note that this method is provided as a convenience and may not always format the message the way you want. For example, by default it does @@ -65,10 +72,58 @@ Here are the methods of the :class:`Message` class: g.flatten(msg) text = fp.getvalue() + If the message object contains binary data that is not encoded according + to RFC standards, the non-compliant data will be replaced by unicode + "unknown character" code points. (See also :meth:`.as_bytes` and + :class:`~email.generator.BytesGenerator`.) + + .. versionchanged:: 3.4 the *policy* keyword argument was added. + .. method:: __str__() - Equivalent to ``as_string(unixfrom=True)``. + Equivalent to :meth:`.as_string()`. Allows ``str(msg)`` to produce a + string containing the formatted message. + + + .. method:: as_bytes(unixfrom=False, policy=None) + + Return the entire message flattened as a bytes object. When optional + *unixfrom* is true, the envelope header is included in the returned + string. *unixfrom* defaults to ``False``. The *policy* argument may be + used to override the default policy obtained from the message instance. + This can be used to control some of the formatting produced by the + method, since the specified *policy* will be passed to the + ``BytesGenerator``. + + Flattening the message may trigger changes to the :class:`Message` if + defaults need to be filled in to complete the transformation to a string + (for example, MIME boundaries may be generated or modified). + + Note that this method is provided as a convenience and may not always + format the message the way you want. For example, by default it does + not do the mangling of lines that begin with ``From`` that is + required by the unix mbox format. For more flexibility, instantiate a + :class:`~email.generator.BytesGenerator` instance and use its + :meth:`~email.generator.BytesGenerator.flatten` method directly. + For example:: + + from io import BytesIO + from email.generator import BytesGenerator + fp = BytesIO() + g = BytesGenerator(fp, mangle_from_=True, maxheaderlen=60) + g.flatten(msg) + text = fp.getvalue() + + .. versionadded:: 3.4 + + + .. method:: __bytes__() + + Equivalent to :meth:`.as_bytes()`. Allows ``bytes(msg)`` to produce a + bytes object containing the formatted message. + + .. versionadded:: 3.4 .. method:: is_multipart() diff --git a/Doc/library/email.policy.rst b/Doc/library/email.policy.rst index cb2023c..5856879 100644 --- a/Doc/library/email.policy.rst +++ b/Doc/library/email.policy.rst @@ -97,6 +97,17 @@ correct line separator characters when creating the binary string to feed into ``sendmail's`` ``stdin``, where the default policy would use ``\n`` line separators. +Some email package methods accept a *policy* keyword argument, allowing the +policy to be overridden for that method. For example, the following code uses +the :meth:`~email.message.Message.as_string` method of the *msg* object from +the previous example and writes the message to a file using the native line +separators for the platform on which it is running:: + + >>> import os + >>> with open('converted.txt', 'wb') as f: + ... f.write(msg.as_bytes(policy=msg.policy.clone(linesep=os.linesep))) + 17 + Policy objects can also be combined using the addition operator, producing a policy object whose settings are a combination of the non-default values of the summed objects:: diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst new file mode 100644 index 0000000..6864705 --- /dev/null +++ b/Doc/library/enum.rst @@ -0,0 +1,593 @@ +:mod:`enum` --- Support for enumerations +======================================== + +.. module:: enum + :synopsis: Implementation of an enumeration class. + +.. :moduleauthor:: Ethan Furman <ethan@stoneleaf.us> +.. :sectionauthor:: Barry Warsaw <barry@python.org>, +.. :sectionauthor:: Eli Bendersky <eliben@gmail.com>, +.. :sectionauthor:: Ethan Furman <ethan@stoneleaf.us> + +**Source code:** :source:`Lib/enum.py` + +---------------- + +An enumeration is a set of symbolic names (members) bound to unique, constant +values. Within an enumeration, the members can be compared by identity, and +the enumeration itself can be iterated over. + +This module defines two enumeration classes that can be used to define unique +sets of names and values: :class:`Enum` and :class:`IntEnum`. It also defines +one decorator, :func:`unique`, that ensures only unique member values are +present in an enumeration. + + +Creating an Enum +---------------- + +Enumerations are created using the :keyword:`class` syntax, which makes them +easy to read and write. An alternative creation method is described in +`Functional API`_. To define an enumeration, subclass :class:`Enum` as +follows:: + + >>> from enum import Enum + >>> class Color(Enum): + ... red = 1 + ... green = 2 + ... blue = 3 + +**A note on nomenclature**: we call :class:`Color` an *enumeration* (or *enum*) +and :attr:`Color.red`, :attr:`Color.green` are *enumeration members* (or +*enum members*). Enumeration members also have *values* (the value of +:attr:`Color.red` is ``1``, etc.) + +Enumeration members have human readable string representations:: + + >>> print(Color.red) + Color.red + +...while their ``repr`` has more information:: + + >>> print(repr(Color.red)) + <Color.red: 1> + +The *type* of an enumeration member is the enumeration it belongs to:: + + >>> type(Color.red) + <enum 'Color'> + >>> isinstance(Color.green, Color) + True + >>> + +Enum members also have a property that contains just their item name:: + + >>> print(Color.red.name) + red + +Enumerations support iteration, in definition order:: + + >>> class Shake(Enum): + ... vanilla = 7 + ... chocolate = 4 + ... cookies = 9 + ... mint = 3 + ... + >>> for shake in Shake: + ... print(shake) + ... + Shake.vanilla + Shake.chocolate + Shake.cookies + Shake.mint + +Enumeration members are hashable, so they can be used in dictionaries and sets:: + + >>> apples = {} + >>> apples[Color.red] = 'red delicious' + >>> apples[Color.green] = 'granny smith' + >>> apples == {Color.red: 'red delicious', Color.green: 'granny smith'} + True + + +Programmatic access to enumeration members and their attributes +--------------------------------------------------------------- + +Sometimes it's useful to access members in enumerations programmatically (i.e. +situations where ``Color.red`` won't do because the exact color is not known +at program-writing time). ``Enum`` allows such access:: + + >>> Color(1) + <Color.red: 1> + >>> Color(3) + <Color.blue: 3> + +If you want to access enum members by *name*, use item access:: + + >>> Color['red'] + <Color.red: 1> + >>> Color['green'] + <Color.green: 2> + +If have an enum member and need its :attr:`name` or :attr:`value`:: + + >>> member = Color.red + >>> member.name + 'red' + >>> member.value + 1 + + +Duplicating enum members and values +----------------------------------- + +Having two enum members with the same name is invalid:: + + >>> class Shape(Enum): + ... square = 2 + ... square = 3 + ... + Traceback (most recent call last): + ... + TypeError: Attempted to reuse key: 'square' + +However, two enum members are allowed to have the same value. Given two members +A and B with the same value (and A defined first), B is an alias to A. By-value +lookup of the value of A and B will return A. By-name lookup of B will also +return A:: + + >>> class Shape(Enum): + ... square = 2 + ... diamond = 1 + ... circle = 3 + ... alias_for_square = 2 + ... + >>> Shape.square + <Shape.square: 2> + >>> Shape.alias_for_square + <Shape.square: 2> + >>> Shape(2) + <Shape.square: 2> + + +Ensuring unique enumeration values +================================== + +By default, enumerations allow multiple names as aliases for the same value. +When this behavior isn't desired, the following decorator can be used to +ensure each value is used only once in the enumeration: + +.. decorator:: unique + +A :keyword:`class` decorator specifically for enumerations. It searches an +enumeration's :attr:`__members__` gathering any aliases it finds; if any are +found :exc:`ValueError` is raised with the details:: + + >>> from enum import Enum, unique + >>> @unique + ... class Mistake(Enum): + ... one = 1 + ... two = 2 + ... three = 3 + ... four = 3 + Traceback (most recent call last): + ... + ValueError: duplicate values found in <enum 'Mistake'>: four -> three + + +Iteration +========= + +Iterating over the members of an enum does not provide the aliases:: + + >>> list(Shape) + [<Shape.square: 2>, <Shape.diamond: 1>, <Shape.circle: 3>] + +The special attribute ``__members__`` is an ordered dictionary mapping names +to members. It includes all names defined in the enumeration, including the +aliases:: + + >>> for name, member in Shape.__members__.items(): + ... name, member + ... + ('square', <Shape.square: 2>) + ('diamond', <Shape.diamond: 1>) + ('circle', <Shape.circle: 3>) + ('alias_for_square', <Shape.square: 2>) + +The ``__members__`` attribute can be used for detailed programmatic access to +the enumeration members. For example, finding all the aliases:: + + >>> [name for name, member in Shape.__members__.items() if member.name != name] + ['alias_for_square'] + + +Comparisons +----------- + +Enumeration members are compared by identity:: + + >>> Color.red is Color.red + True + >>> Color.red is Color.blue + False + >>> Color.red is not Color.blue + True + +Ordered comparisons between enumeration values are *not* supported. Enum +members are not integers (but see `IntEnum`_ below):: + + >>> Color.red < Color.blue + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: unorderable types: Color() < Color() + +Equality comparisons are defined though:: + + >>> Color.blue == Color.red + False + >>> Color.blue != Color.red + True + >>> Color.blue == Color.blue + True + +Comparisons against non-enumeration values will always compare not equal +(again, class:`IntEnum` was explicitly designed to behave differently, see +below):: + + >>> Color.blue == 2 + False + + +Allowed members and attributes of enumerations +---------------------------------------------- + +The examples above use integers for enumeration values. Using integers is +short and handy (and provided by default by the `Functional API`_), but not +strictly enforced. In the vast majority of use-cases, one doesn't care what +the actual value of an enumeration is. But if the value *is* important, +enumerations can have arbitrary values. + +Enumerations are Python classes, and can have methods and special methods as +usual. If we have this enumeration:: + + >>> class Mood(Enum): + ... funky = 1 + ... happy = 3 + ... + ... def describe(self): + ... # self is the member here + ... return self.name, self.value + ... + ... def __str__(self): + ... return 'my custom str! {0}'.format(self.value) + ... + ... @classmethod + ... def favorite_mood(cls): + ... # cls here is the enumeration + ... return cls.happy + +Then:: + + >>> Mood.favorite_mood() + <Mood.happy: 3> + >>> Mood.happy.describe() + ('happy', 3) + >>> str(Mood.funky) + 'my custom str! 1' + +The rules for what is allowed are as follows: _sunder_ names (starting and +ending with a single underscore) are reserved by enum and cannot be used; +all other attributes defined within an enumeration will become members of this +enumeration, with the exception of *__dunder__* names and descriptors (methods +are also descriptors). + +Note: if your enumeration defines :meth:`__new__` and/or :meth:`__init__` then +whatever value(s) were given to the enum member will be passed into those +methods. See `Planet`_ for an example. + + +Restricted subclassing of enumerations +-------------------------------------- + +Subclassing an enumeration is allowed only if the enumeration does not define +any members. So this is forbidden:: + + >>> class MoreColor(Color): + ... pink = 17 + Traceback (most recent call last): + ... + TypeError: Cannot extend enumerations + +But this is allowed:: + + >>> class Foo(Enum): + ... def some_behavior(self): + ... pass + ... + >>> class Bar(Foo): + ... happy = 1 + ... sad = 2 + ... + +Allowing subclassing of enums that define members would lead to a violation of +some important invariants of types and instances. On the other hand, it makes +sense to allow sharing some common behavior between a group of enumerations. +(See `OrderedEnum`_ for an example.) + + +Pickling +-------- + +Enumerations can be pickled and unpickled:: + + >>> from test.test_enum import Fruit + >>> from pickle import dumps, loads + >>> Fruit.tomato is loads(dumps(Fruit.tomato)) + True + +The usual restrictions for pickling apply: picklable enums must be defined in +the top level of a module, since unpickling requires them to be importable +from that module. + +.. warning:: + + In order to support the singleton nature of enumeration members, pickle + protocol version 2 or higher must be used. + + +Functional API +-------------- + +The :class:`Enum` class is callable, providing the following functional API:: + + >>> Animal = Enum('Animal', 'ant bee cat dog') + >>> Animal + <enum 'Animal'> + >>> Animal.ant + <Animal.ant: 1> + >>> Animal.ant.value + 1 + >>> list(Animal) + [<Animal.ant: 1>, <Animal.bee: 2>, <Animal.cat: 3>, <Animal.dog: 4>] + +The semantics of this API resemble :class:`namedtuple`. The first argument +of the call to :class:`Enum` is the name of the enumeration. + +The second argument is the *source* of enumeration member names. It can be a +whitespace-separated string of names, a sequence of names, a sequence of +2-tuples with key/value pairs, or a mapping (e.g. dictionary) of names to +values. The last two options enable assigning arbitrary values to +enumerations; the others auto-assign increasing integers starting with 1. A +new class derived from :class:`Enum` is returned. In other words, the above +assignment to :class:`Animal` is equivalent to:: + + >>> class Animals(Enum): + ... ant = 1 + ... bee = 2 + ... cat = 3 + ... dog = 4 + +The reason for defaulting to ``1`` as the starting number and not ``0`` is +that ``0`` is ``False`` in a boolean sense, but enum members all evaluate +to ``True``. + +Pickling enums created with the functional API can be tricky as frame stack +implementation details are used to try and figure out which module the +enumeration is being created in (e.g. it will fail if you use a utility +function in separate module, and also may not work on IronPython or Jython). +The solution is to specify the module name explicitly as follows:: + + >>> Animals = Enum('Animals', 'ant bee cat dog', module=__name__) + +Derived Enumerations +==================== + +IntEnum +------- + +A variation of :class:`Enum` is provided which is also a subclass of +:class:`int`. Members of an :class:`IntEnum` can be compared to integers; +by extension, integer enumerations of different types can also be compared +to each other:: + + >>> from enum import IntEnum + >>> class Shape(IntEnum): + ... circle = 1 + ... square = 2 + ... + >>> class Request(IntEnum): + ... post = 1 + ... get = 2 + ... + >>> Shape == 1 + False + >>> Shape.circle == 1 + True + >>> Shape.circle == Request.post + True + +However, they still can't be compared to standard :class:`Enum` enumerations:: + + >>> class Shape(IntEnum): + ... circle = 1 + ... square = 2 + ... + >>> class Color(Enum): + ... red = 1 + ... green = 2 + ... + >>> Shape.circle == Color.red + False + +:class:`IntEnum` values behave like integers in other ways you'd expect:: + + >>> int(Shape.circle) + 1 + >>> ['a', 'b', 'c'][Shape.circle] + 'b' + >>> [i for i in range(Shape.square)] + [0, 1] + +For the vast majority of code, :class:`Enum` is strongly recommended, +since :class:`IntEnum` breaks some semantic promises of an enumeration (by +being comparable to integers, and thus by transitivity to other +unrelated enumerations). It should be used only in special cases where +there's no other choice; for example, when integer constants are +replaced with enumerations and backwards compatibility is required with code +that still expects integers. + + +Others +------ + +While :class:`IntEnum` is part of the :mod:`enum` module, it would be very +simple to implement independently:: + + class IntEnum(int, Enum): + pass + +This demonstrates how similar derived enumerations can be defined; for example +a :class:`StrEnum` that mixes in :class:`str` instead of :class:`int`. + +Some rules: + +1. When subclassing :class:`Enum`, mix-in types must appear before + :class:`Enum` itself in the sequence of bases, as in the :class:`IntEnum` + example above. +2. While :class:`Enum` can have members of any type, once you mix in an + additional type, all the members must have values of that type, e.g. + :class:`int` above. This restriction does not apply to mix-ins which only + add methods and don't specify another data type such as :class:`int` or + :class:`str`. +3. When another data type is mixed in, the :attr:`value` attribute is *not the + same* as the enum member itself, although it is equivalant and will compare + equal. + + +Interesting examples +==================== + +While :class:`Enum` and :class:`IntEnum` are expected to cover the majority of +use-cases, they cannot cover them all. Here are recipes for some different +types of enumerations that can be used directly, or as examples for creating +one's own. + + +AutoNumber +---------- + +Avoids having to specify the value for each enumeration member:: + + >>> class AutoNumber(Enum): + ... def __new__(cls): + ... value = len(cls.__members__) + 1 + ... obj = object.__new__(cls) + ... obj._value_ = value + ... return obj + ... + >>> class Color(AutoNumber): + ... red = () + ... green = () + ... blue = () + ... + >>> Color.green.value == 2 + True + + +OrderedEnum +----------- + +An ordered enumeration that is not based on :class:`IntEnum` and so maintains +the normal :class:`Enum` invariants (such as not being comparable to other +enumerations):: + + >>> class OrderedEnum(Enum): + ... def __ge__(self, other): + ... if self.__class__ is other.__class__: + ... return self.value >= other.value + ... return NotImplemented + ... def __gt__(self, other): + ... if self.__class__ is other.__class__: + ... return self.value > other.value + ... return NotImplemented + ... def __le__(self, other): + ... if self.__class__ is other.__class__: + ... return self.value <= other.value + ... return NotImplemented + ... def __lt__(self, other): + ... if self.__class__ is other.__class__: + ... return self.value < other.value + ... return NotImplemented + ... + >>> class Grade(OrderedEnum): + ... A = 5 + ... B = 4 + ... C = 3 + ... D = 2 + ... F = 1 + ... + >>> Grade.C < Grade.A + True + + +DuplicateFreeEnum +----------------- + +Raises an error if a duplicate member name is found instead of creating an +alias:: + + >>> class DuplicateFreeEnum(Enum): + ... def __init__(self, *args): + ... cls = self.__class__ + ... if any(self.value == e.value for e in cls): + ... a = self.name + ... e = cls(self.value).name + ... raise ValueError( + ... "aliases not allowed in DuplicateFreeEnum: %r --> %r" + ... % (a, e)) + ... + >>> class Color(DuplicateFreeEnum): + ... red = 1 + ... green = 2 + ... blue = 3 + ... grene = 2 + Traceback (most recent call last): + ... + ValueError: aliases not allowed in DuplicateFreeEnum: 'grene' --> 'green' + +.. note:: + + This is a useful example for subclassing Enum to add or change other + behaviors as well as disallowing aliases. If the only change desired is + no aliases allowed the :func:`unique` decorator can be used instead. + + +Planet +------ + +If :meth:`__new__` or :meth:`__init__` is defined the value of the enum member +will be passed to those methods:: + + >>> class Planet(Enum): + ... MERCURY = (3.303e+23, 2.4397e6) + ... VENUS = (4.869e+24, 6.0518e6) + ... EARTH = (5.976e+24, 6.37814e6) + ... MARS = (6.421e+23, 3.3972e6) + ... JUPITER = (1.9e+27, 7.1492e7) + ... SATURN = (5.688e+26, 6.0268e7) + ... URANUS = (8.686e+25, 2.5559e7) + ... NEPTUNE = (1.024e+26, 2.4746e7) + ... def __init__(self, mass, radius): + ... self.mass = mass # in kilograms + ... self.radius = radius # in meters + ... @property + ... def surface_gravity(self): + ... # universal gravitational constant (m3 kg-1 s-2) + ... G = 6.67300E-11 + ... return G * self.mass / (self.radius * self.radius) + ... + >>> Planet.EARTH.value + (5.976e+24, 6378140.0) + >>> Planet.EARTH.surface_gravity + 9.802652743337129 diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 9595221..ece035d 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -260,6 +260,12 @@ The following exceptions are the exceptions that are usually raised. :exc:`VMSError`, :exc:`socket.error`, :exc:`select.error` and :exc:`mmap.error` have been merged into :exc:`OSError`. + .. versionchanged:: 3.4 + + The :attr:`filename` attribute is now the original file name passed to + the function, instead of the name encoded to or decoded from the + filesystem encoding. + .. exception:: OverflowError diff --git a/Doc/library/filecmp.rst b/Doc/library/filecmp.rst index 8a88f8c..8471a72 100644 --- a/Doc/library/filecmp.rst +++ b/Doc/library/filecmp.rst @@ -27,6 +27,10 @@ The :mod:`filecmp` module defines the following functions: Note that no external programs are called from this function, giving it portability and efficiency. + This function uses a cache for past comparisons and the results, + with a cache invalidation mechanism relying on stale signatures + or by explicitly calling :func:`clear_cache`. + .. function:: cmpfiles(dir1, dir2, common, shallow=True) @@ -48,6 +52,15 @@ The :mod:`filecmp` module defines the following functions: one of the three returned lists. +.. function:: clear_cache() + + .. versionadded:: 3.4 + + Clear the filecmp cache. This may be useful if a file is compared so quickly + after it is modified that it is within the mtime resolution of + the underlying filesystem. + + .. _dircmp-objects: The :class:`dircmp` class @@ -55,28 +68,25 @@ The :class:`dircmp` class .. class:: dircmp(a, b, ignore=None, hide=None) - Construct a new directory comparison object, to compare the directories *a* and - *b*. *ignore* is a list of names to ignore, and defaults to ``['RCS', 'CVS', - 'tags']``. *hide* is a list of names to hide, and defaults to ``[os.curdir, - os.pardir]``. + Construct a new directory comparison object, to compare the directories *a* + and *b*. *ignore* is a list of names to ignore, and defaults to + :attr:`filecmp.DEFAULT_IGNORES`. *hide* is a list of names to hide, and + defaults to ``[os.curdir, os.pardir]``. The :class:`dircmp` class compares files by doing *shallow* comparisons as described for :func:`filecmp.cmp`. The :class:`dircmp` class provides the following methods: - .. method:: report() Print (to :data:`sys.stdout`) a comparison between *a* and *b*. - .. method:: report_partial_closure() Print a comparison between *a* and *b* and common immediate subdirectories. - .. method:: report_full_closure() Print a comparison between *a* and *b* and common subdirectories @@ -133,7 +143,7 @@ The :class:`dircmp` class .. attribute:: common_files - Files in both *a* and *b* + Files in both *a* and *b*. .. attribute:: common_funny @@ -164,6 +174,12 @@ The :class:`dircmp` class A dictionary mapping names in :attr:`common_dirs` to :class:`dircmp` objects. +.. attribute:: DEFAULT_IGNORES + + .. versionadded:: 3.4 + + List of directories ignored by :class:`dircmp` by default. + Here is a simplified example of using the ``subdirs`` attribute to search recursively through two directories to show common different files:: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c3fff31..399f1ff 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -543,6 +543,10 @@ are always available. They are listed here in alphabetical order. :exc:`TypeError` exception is raised if the method is not found or if either the *format_spec* or the return value are not strings. + .. versionadded:: 3.4 + ``object().__format__(format_spec)`` raises :exc:`TypeError` + if *format_spec* is not empty string. + .. _func-frozenset: .. function:: frozenset([iterable]) @@ -666,6 +670,12 @@ are always available. They are listed here in alphabetical order. The integer type is described in :ref:`typesnumeric`. + .. versionchanged:: 3.4 + If *base* is not an instance of :class:`int` and the *base* object has a + :meth:`base.__index__ <object.__index__>` method, that method is called + to obtain an integer for the base. Previous versions used + :meth:`base.__int__ <object.__int__>` instead of :meth:`base.__index__ + <object.__index__>`. .. function:: isinstance(object, classinfo) @@ -748,19 +758,22 @@ are always available. They are listed here in alphabetical order. already arranged into argument tuples, see :func:`itertools.starmap`\. -.. function:: max(iterable, *[, key]) +.. function:: max(iterable, *[, default, key]) max(arg1, arg2, *args[, key]) Return the largest item in an iterable or the largest of two or more arguments. - If one positional argument is provided, *iterable* must be a non-empty - iterable (such as a non-empty string, tuple or list). The largest item - in the iterable is returned. If two or more positional arguments are - provided, the largest of the positional arguments is returned. + If one positional argument is provided, it should be an :term:`iterable`. + The largest item in the iterable is returned. If two or more positional + arguments are provided, the smallest of the positional arguments is + returned. - The optional keyword-only *key* argument specifies a one-argument ordering - function like that used for :meth:`list.sort`. + There are two optional keyword-only arguments. The *key* argument specifies + a one-argument ordering function like that used for :meth:`list.sort`. The + *default* argument specifies an object to return if the provided iterable is + empty. If the iterable is empty and *default* is not provided, a + :exc:`ValueError` is raised. If multiple items are maximal, the function returns the first one encountered. This is consistent with other sort-stability preserving tools @@ -776,19 +789,22 @@ are always available. They are listed here in alphabetical order. :ref:`typememoryview` for more information. -.. function:: min(iterable, *[, key]) +.. function:: min(iterable, *[, default, key]) min(arg1, arg2, *args[, key]) Return the smallest item in an iterable or the smallest of two or more arguments. - If one positional argument is provided, *iterable* must be a non-empty - iterable (such as a non-empty string, tuple or list). The smallest item - in the iterable is returned. If two or more positional arguments are - provided, the smallest of the positional arguments is returned. + If one positional argument is provided, it should be an :term:`iterable`. + The smallest item in the iterable is returned. If two or more positional + arguments are provided, the smallest of the positional arguments is + returned. - The optional keyword-only *key* argument specifies a one-argument ordering - function like that used for :meth:`list.sort`. + There are two optional keyword-only arguments. The *key* argument specifies + a one-argument ordering function like that used for :meth:`list.sort`. The + *default* argument specifies an object to return if the provided iterable is + empty. If the iterable is empty and *default* is not provided, a + :exc:`ValueError` is raised. If multiple items are minimal, the function returns the first one encountered. This is consistent with other sort-stability preserving tools diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index d8fcf0f..2f6d9af 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -6,6 +6,7 @@ .. moduleauthor:: Peter Harris <scav@blueyonder.co.uk> .. moduleauthor:: Raymond Hettinger <python@rcn.com> .. moduleauthor:: Nick Coghlan <ncoghlan@gmail.com> +.. moduleauthor:: Łukasz Langa <lukasz@langa.pl> .. sectionauthor:: Peter Harris <scav@blueyonder.co.uk> **Source code:** :source:`Lib/functools.py` @@ -186,6 +187,111 @@ The :mod:`functools` module defines the following functions: *sequence* contains only one item, the first item is returned. +.. decorator:: singledispatch(default) + + Transforms a function into a :term:`single-dispatch <single + dispatch>` :term:`generic function`. + + To define a generic function, decorate it with the ``@singledispatch`` + decorator. Note that the dispatch happens on the type of the first argument, + create your function accordingly:: + + >>> from functools import singledispatch + >>> @singledispatch + ... def fun(arg, verbose=False): + ... if verbose: + ... print("Let me just say,", end=" ") + ... print(arg) + + To add overloaded implementations to the function, use the :func:`register` + attribute of the generic function. It is a decorator, taking a type + parameter and decorating a function implementing the operation for that + type:: + + >>> @fun.register(int) + ... def _(arg, verbose=False): + ... if verbose: + ... print("Strength in numbers, eh?", end=" ") + ... print(arg) + ... + >>> @fun.register(list) + ... def _(arg, verbose=False): + ... if verbose: + ... print("Enumerate this:") + ... for i, elem in enumerate(arg): + ... print(i, elem) + + To enable registering lambdas and pre-existing functions, the + :func:`register` attribute can be used in a functional form:: + + >>> def nothing(arg, verbose=False): + ... print("Nothing.") + ... + >>> fun.register(type(None), nothing) + + The :func:`register` attribute returns the undecorated function which + enables decorator stacking, pickling, as well as creating unit tests for + each variant independently:: + + >>> @fun.register(float) + ... @fun.register(Decimal) + ... def fun_num(arg, verbose=False): + ... if verbose: + ... print("Half of your number:", end=" ") + ... print(arg / 2) + ... + >>> fun_num is fun + False + + When called, the generic function dispatches on the type of the first + argument:: + + >>> fun("Hello, world.") + Hello, world. + >>> fun("test.", verbose=True) + Let me just say, test. + >>> fun(42, verbose=True) + Strength in numbers, eh? 42 + >>> fun(['spam', 'spam', 'eggs', 'spam'], verbose=True) + Enumerate this: + 0 spam + 1 spam + 2 eggs + 3 spam + >>> fun(None) + Nothing. + >>> fun(1.23) + 0.615 + + Where there is no registered implementation for a specific type, its + method resolution order is used to find a more generic implementation. + The original function decorated with ``@singledispatch`` is registered + for the base ``object`` type, which means it is used if no better + implementation is found. + + To check which implementation will the generic function choose for + a given type, use the ``dispatch()`` attribute:: + + >>> fun.dispatch(float) + <function fun_num at 0x1035a2840> + >>> fun.dispatch(dict) # note: default implementation + <function fun at 0x103fe0000> + + To access all registered implementations, use the read-only ``registry`` + attribute:: + + >>> fun.registry.keys() + dict_keys([<class 'NoneType'>, <class 'int'>, <class 'object'>, + <class 'decimal.Decimal'>, <class 'list'>, + <class 'float'>]) + >>> fun.registry[float] + <function fun_num at 0x1035a2840> + >>> fun.registry[object] + <function fun at 0x103fe0000> + + .. versionadded:: 3.4 + + .. function:: update_wrapper(wrapper, wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES) Update a *wrapper* function to look like the *wrapped* function. The optional @@ -200,8 +306,8 @@ The :mod:`functools` module defines the following functions: To allow access to the original function for introspection and other purposes (e.g. bypassing a caching decorator such as :func:`lru_cache`), this function - automatically adds a __wrapped__ attribute to the wrapper that refers to - the original function. + automatically adds a ``__wrapped__`` attribute to the wrapper that refers to + the function being wrapped. The main intended use for this function is in :term:`decorator` functions which wrap the decorated function and return the wrapper. If the wrapper function is @@ -224,6 +330,11 @@ The :mod:`functools` module defines the following functions: .. versionchanged:: 3.2 Missing attributes no longer trigger an :exc:`AttributeError`. + .. versionchanged:: 3.4 + The ``__wrapped__`` attribute now always refers to the wrapped + function, even if that function defined a ``__wrapped__`` attribute. + (see :issue:`17482`) + .. decorator:: wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES) diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 5878da5..8e3a4bd 100644 --- a/Doc/library/gc.rst +++ b/Doc/library/gc.rst @@ -67,6 +67,24 @@ The :mod:`gc` module provides the following functions: returned. +.. function:: get_stats() + + Return a list of 3 per-generation dictionaries containing collection + statistics since interpreter start. At this moment, each dictionary will + contain the following items: + + * ``collections`` is the number of times this generation was collected; + + * ``collected`` is the total number of objects collected inside this + generation; + + * ``uncollectable`` is the total number of objects which were found + to be uncollectable (and were therefore moved to the :data:`garbage` + list) inside this generation. + + .. versionadded:: 3.4 + + .. function:: set_threshold(threshold0[, threshold1[, threshold2]]) Set the garbage collection thresholds (the collection frequency). Setting @@ -158,24 +176,13 @@ values but should not rebind them): .. data:: garbage - A list of objects which the collector found to be unreachable but could not be - freed (uncollectable objects). By default, this list contains only objects with - :meth:`__del__` methods. Objects that have :meth:`__del__` methods and are - part of a reference cycle cause the entire reference cycle to be uncollectable, - including objects not necessarily in the cycle but reachable only from it. - Python doesn't collect such cycles automatically because, in general, it isn't - possible for Python to guess a safe order in which to run the :meth:`__del__` - methods. If you know a safe order, you can force the issue by examining the - *garbage* list, and explicitly breaking cycles due to your objects within the - list. Note that these objects are kept alive even so by virtue of being in the - *garbage* list, so they should be removed from *garbage* too. For example, - after breaking cycles, do ``del gc.garbage[:]`` to empty the list. It's - generally better to avoid the issue by not creating cycles containing objects - with :meth:`__del__` methods, and *garbage* can be examined in that case to - verify that no such cycles are being created. - - If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added - to this list rather than freed. + A list of objects which the collector found to be unreachable but could + not be freed (uncollectable objects). Starting with Python 3.4, this + list should be empty most of the time, except when using instances of + C extension types with a non-NULL ``tp_del`` slot. + + If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be + added to this list rather than freed. .. versionchanged:: 3.2 If this list is non-empty at interpreter shutdown, a @@ -183,6 +190,10 @@ values but should not rebind them): :const:`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects are printed. + .. versionchanged:: 3.4 + Following :pep:`442`, objects with a :meth:`__del__` method don't end + up in :attr:`gc.garbage` anymore. + .. data:: callbacks A list of callbacks that will be invoked by the garbage collector before and diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst index 0a1b208..db41db4 100644 --- a/Doc/library/hashlib.rst +++ b/Doc/library/hashlib.rst @@ -51,9 +51,13 @@ concatenation of the data fed to it so far using the :meth:`digest` or .. index:: single: OpenSSL; (use in module hashlib) Constructors for hash algorithms that are always present in this module are -:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, and -:func:`sha512`. Additional algorithms may also be available depending upon the -OpenSSL library that Python uses on your platform. +:func:`md5`, :func:`sha1`, :func:`sha224`, :func:`sha256`, :func:`sha384`, +:func:`sha512`, :func:`sha3_224`, :func:`sha3_256`, :func:`sha3_384`, and +:func:`sha3_512`. Additional algorithms may also be available depending upon +the OpenSSL library that Python uses on your platform. + + .. versionchanged:: 3.4 + Add sha3 family of hash algorithms. For example, to obtain the digest of the byte string ``b'Nobody inspects the spammish repetition'``:: @@ -120,6 +124,18 @@ returned by the constructors: The internal block size of the hash algorithm in bytes. +A hash object has the following attributes: + +.. attribute:: hash.name + + The canonical name of this hash, always lowercase and always suitable as a + parameter to :func:`new` to create another hash of this type. + + .. versionchanged:: 3.4 + The name attribute has been present in CPython since its inception, but + until Python 3.4 was not formally specified, so may not exist on some + platforms. + A hash object has the following methods: diff --git a/Doc/library/hmac.rst b/Doc/library/hmac.rst index c2066a7..4c707e9 100644 --- a/Doc/library/hmac.rst +++ b/Doc/library/hmac.rst @@ -16,20 +16,26 @@ This module implements the HMAC algorithm as described by :rfc:`2104`. .. function:: new(key, msg=None, digestmod=None) - Return a new hmac object. *key* is a bytes object giving the secret key. If - *msg* is present, the method call ``update(msg)`` is made. *digestmod* is - the digest constructor or module for the HMAC object to use. It defaults to - the :func:`hashlib.md5` constructor. + Return a new hmac object. *key* is a bytes or bytearray object giving the + secret key. If *msg* is present, the method call ``update(msg)`` is made. + *digestmod* is the digest constructor or module for the HMAC object to use. + It defaults to the :func:`hashlib.md5` constructor. + .. versionchanged:: 3.4 + Parameter *key* can be a bytes or bytearray object. Parameter *msg* can + be of any type supported by :mod:`hashlib`. An HMAC object has the following methods: .. method:: HMAC.update(msg) - Update the hmac object with the bytes object *msg*. Repeated calls are - equivalent to a single call with the concatenation of all the arguments: + Update the hmac object with *msg*. Repeated calls are equivalent to a + single call with the concatenation of all the arguments: ``m.update(a); m.update(b)`` is equivalent to ``m.update(a + b)``. + .. versionchanged:: 3.4 + Parameter *msg* can be of any type supported by :mod:`hashlib`. + .. method:: HMAC.digest() diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst index 8137573..0fad566 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -27,7 +27,7 @@ HTTPS protocols. It is normally not used directly --- the module The module provides the following classes: -.. class:: HTTPConnection(host, port=None[, strict][, timeout], \ +.. class:: HTTPConnection(host, port=None[, timeout], \ source_address=None) An :class:`HTTPConnection` instance represents one transaction with an HTTP @@ -51,13 +51,13 @@ The module provides the following classes: .. versionchanged:: 3.2 *source_address* was added. - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are + not supported. .. class:: HTTPSConnection(host, port=None, key_file=None, \ - cert_file=None[, strict][, timeout], \ + cert_file=None[, timeout], \ source_address=None, *, context=None, \ check_hostname=None) @@ -89,19 +89,19 @@ The module provides the following classes: This class now supports HTTPS virtual hosts if possible (that is, if :data:`ssl.HAS_SNI` is true). - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9-style "Simple Responses" are + not supported anymore. -.. class:: HTTPResponse(sock, debuglevel=0[, strict], method=None, url=None) +.. class:: HTTPResponse(sock, debuglevel=0, method=None, url=None) Class whose instances are returned upon successful connection. Not instantiated directly by user. - .. deprecated-removed:: 3.2 3.4 - The *strict* parameter is deprecated. HTTP 0.9-style "Simple Responses" - are not supported anymore. + .. versionchanged:: 3.4 + The *strict* parameter is removed. HTTP 0.9 style "Simple Responses" are + not supported anymore. The following exceptions are raised as appropriate: diff --git a/Doc/library/http.server.rst b/Doc/library/http.server.rst index cbad3ed..53139a2 100644 --- a/Doc/library/http.server.rst +++ b/Doc/library/http.server.rst @@ -170,12 +170,19 @@ of which this module provides three different variants: .. versionadded:: 3.2 - .. method:: send_error(code, message=None) + .. method:: send_error(code, message=None, explain=None) Sends and logs a complete error reply to the client. The numeric *code* - specifies the HTTP error code, with *message* as optional, more specific text. A - complete set of headers is sent, followed by text composed using the - :attr:`error_message_format` class variable. + specifies the HTTP error code, with *message* as optional, more specific + text, usually referring to short message response. The *explain* + argument can be used to send a detailed information about the error in + response content body. A complete set of headers is sent, followed by + text composed using the :attr:`error_message_format` class variable. + + .. versionchanged:: 3.4 + The error response includes a Content-Length header. + Added the *explain* argument. + .. method:: send_response(code, message=None) diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 36d78b0..2718cef 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -16,70 +16,82 @@ 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 window types, the Shell window and the Editor window. It is +possible to have multiple editor windows simultaneously. 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). -File menu -^^^^^^^^^ +File menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ New file - create a new file editing window + Create a new file editing window Open... - open an existing file + Open an existing file Open module... - open an existing module (searches sys.path) + Open an existing module (searches sys.path) + +Recent Files + Open a list of recent files Class browser - show classes and methods in current file + Show classes and methods in current file Path browser - show sys.path directories, modules, classes and methods + Show sys.path directories, modules, classes and methods .. index:: single: Class browser single: Path browser Save - save current window to the associated file (unsaved windows have a \* before and - after the window title) + Save current window to the associated file (unsaved windows have a + \* before and after the window title) Save As... - save current window to new file, which becomes the associated file + Save current window to new file, which becomes the associated file Save Copy As... - save current window to different file without changing the associated file + Save current window to different file without changing the associated file + +Print Window + Print the current window Close - close current window (asks to save if unsaved) + Close current window (asks to save if unsaved) Exit - close all windows and quit IDLE (asks to save if unsaved) + Close all windows and quit IDLE (asks to save if unsaved) -Edit menu -^^^^^^^^^ +Edit menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Undo - Undo last change to current window (max 1000 changes) + Undo last change to current window (a maximum of 1000 changes may be undone) Redo Redo last undone change to current window Cut - Copy selection into system-wide clipboard; then delete selection + Copy selection into system-wide clipboard; then delete the selection Copy Copy selection into system-wide clipboard @@ -108,11 +120,30 @@ Replace... Go to line Ask for a line number and show that line +Expand word + Expand the word you have typed to match another word in the same buffer; + repeat to get a different expansion + +Show call tip + After an unclosed parenthesis for a function, open a small window with + function parameter hints + +Show surrounding parens + Highlight the surrounding parenthesis + +Show Completions + Open a scroll window allowing selection keywords and attributes. See + Completions below. + + +Format menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Indent region - Shift selected lines right 4 spaces + Shift selected lines right by the indent width (default 4 spaces) Dedent region - Shift selected lines left 4 spaces + Shift selected lines left by the indent width (default 4 spaces) Comment out region Insert ## in front of selected lines @@ -121,67 +152,121 @@ Uncomment region Remove leading # or ## from selected lines Tabify region - Turns *leading* stretches of spaces into tabs + Turns *leading* stretches of spaces into tabs. (Note: We recommend using + 4 space blocks to indent Python code.) Untabify region - Turn *all* tabs into the right number of spaces + Turn *all* tabs into the correct number of spaces -Expand word - Expand the word you have typed to match another word in the same buffer; repeat - to get a different expansion +Toggle tabs + Open a dialog to switch between indenting with spaces and tabs. -Format Paragraph - Reformat the current blank-line-separated paragraph +New Indent Width + Open a dialog to change indent width. The accepted default by the Python + community is 4 spaces. -Import module - Import or reload the current module +Format Paragraph + Reformat the current blank-line-separated paragraph. All lines in the + paragraph will be formatted to less than 80 columns. -Run script - Execute the current file in the __main__ namespace +Strip trailing whitespace + Removes any space characters after the end of the last non-space character .. index:: single: Import module single: Run script -Windows menu -^^^^^^^^^^^^ +Run menu (Editor window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Zoom Height - toggles the window between normal size (24x80) and maximum height. +Python Shell + Open or wake up the Python Shell 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). +Check module + Check the syntax of the module currently open in the Editor window. If the + module has not been saved IDLE will prompt the user to save the code. + +Run module + Restart the shell to clean the environment, then execute the currently + open module. If the module has not been saved IDLE will prompt the user + to save the code. +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 + +Debug menu (Shell window only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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. + exception traceback. Available in the context menu of the Shell window. -Debugger - Run commands in the shell under the debugger. +Debugger (toggle) + This feature is not complete and considered experimental. Run commands in + the shell under the debugger Stack viewer - Show the stack traceback of the last exception. + Show the stack traceback of the last exception Auto-open Stack Viewer - Open stack viewer on traceback. + Toggle automatically opening the stack viewer on 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. + +Code Context (toggle)(Editor Window only) + Open a pane at the top of the edit window which shows the block context + of the section of code which is scrolling off the top of the window. + +Windows menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Zoom Height + Toggles the window between normal size (40x80 initial setting) and maximum + height. The initial size is in the Configure IDLE dialog under the general + tab. + +The rest of this menu lists the names of all open windows; select one to bring +it to the foreground (deiconifying it if necessary). + +Help menu (Shell and Editor) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +About IDLE + Version, copyright, license, credits + +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 will start a web browser + and open docs.python.org showing the latest Python documentation. -Edit context menu -^^^^^^^^^^^^^^^^^ +Additional help sources may be added here with the Configure IDLE dialog under +the General tab. -* Right-click in Edit window (Control-click on OS X) +Editor Window context menu +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* Right-click in Editor window (Control-click on OS X) Cut Copy selection into system-wide clipboard; then delete selection @@ -207,8 +292,8 @@ Clear Breakpoint single: breakpoints -Shell context menu -^^^^^^^^^^^^^^^^^^ +Shell Window context menu +^^^^^^^^^^^^^^^^^^^^^^^^^ * Right-click in Python Shell window (Control-click on OS X) @@ -225,19 +310,44 @@ Go to file/line Same as in Debug menu. -Basic editing and navigation ----------------------------- +Editing and navigation +---------------------- * :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 +356,76 @@ 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 + (this is :kbd:`C-z` on Windows). -* :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 +467,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. +to be used from IDLE's Python shell. Command line usage @@ -349,3 +508,45 @@ If there are arguments: the arguments are still available in ``sys.argv``. +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. + + +Other preferences +----------------- + +The font preferences, highlighting, keys, and general preferences can be +changed via the Configure IDLE menu option. Be sure to note that +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. 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 + diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst index af98489..5253e69 100644 --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -1,6 +1,9 @@ :mod:`imp` --- Access the :ref:`import <importsystem>` internals ================================================================ +.. deprecated:: 3.4 + The :mod:`imp` package is pending deprecation in favor of :mod:`importlib`. + .. module:: imp :synopsis: Access the implementation of the import statement. @@ -11,10 +14,6 @@ This module provides an interface to the mechanisms used to implement the :keyword:`import` statement. It defines the following constants and functions: -.. note:: - New programs should use :mod:`importlib` rather than this module. - - .. function:: get_magic() .. index:: pair: file; byte-code @@ -22,6 +21,9 @@ This module provides an interface to the mechanisms used to implement the Return the magic string value used to recognize byte-compiled code files (:file:`.pyc` files). (This value may be different for each Python version.) + .. deprecated:: 3.4 + Use :attr:`importlib.util.MAGIC_NUMBER` instead. + .. function:: get_suffixes() @@ -101,8 +103,10 @@ This module provides an interface to the mechanisms used to implement the using a :keyword:`try` ... :keyword:`finally` statement. .. deprecated:: 3.3 - Unneeded as loaders should be used to load modules and - :func:`find_module` is deprecated. + If previously used in conjunction with :func:`imp.find_module` then + call ``load_module()`` on the returned loader. If you wish to load a + module from a specific file, then use one of the file-based loaders found + in :mod:`importlib.machinery`. .. function:: new_module(name) @@ -110,6 +114,9 @@ This module provides an interface to the mechanisms used to implement the Return a new empty module object called *name*. This object is *not* inserted in ``sys.modules``. + .. deprecated:: 3.4 + Use :class:`types.ModuleType` instead. + .. function:: reload(module) @@ -172,6 +179,9 @@ This module provides an interface to the mechanisms used to implement the the class does not affect the method definitions of the instances --- they continue to use the old class definition. The same is true for derived classes. + .. deprecated:: 3.4 + Use :func:`importlib.reload` instead. + The following functions are conveniences for handling :pep:`3147` byte-compiled file paths. @@ -197,6 +207,9 @@ file paths. If :attr:`sys.implementation.cache_tag` is ``None``, then :exc:`NotImplementedError` is raised. + .. deprecated:: 3.4 + Use :func:`importlib.util.cache_from_source` instead. + .. function:: source_from_cache(path) @@ -212,14 +225,17 @@ file paths. Raise :exc:`NotImplementedError` when :attr:`sys.implementation.cache_tag` is not defined. + .. deprecated:: 3.4 + Use :func:`importlib.util.source_from_cache` instead. + .. function:: get_tag() Return the :pep:`3147` magic tag string matching this version of Python's magic number, as returned by :func:`get_magic`. - .. note:: - You may use :attr:`sys.implementation.cache_tag` directly starting + .. deprecated:: 3.4 + Use :attr:`sys.implementation.cache_tag` directly starting in Python 3.3. @@ -247,6 +263,8 @@ that circular imports work without any deadlocks. the most part. A global import lock is kept for some critical tasks, such as initializing the per-module locks. +.. deprecated:: 3.4 + .. function:: acquire_lock() @@ -265,6 +283,8 @@ that circular imports work without any deadlocks. the most part. A global import lock is kept for some critical tasks, such as initializing the per-module locks. +.. deprecated:: 3.4 + .. function:: release_lock() @@ -276,6 +296,8 @@ that circular imports work without any deadlocks. the most part. A global import lock is kept for some critical tasks, such as initializing the per-module locks. +.. deprecated:: 3.4 + The following constants with integer values, defined in this module, are used to indicate the search result of :func:`find_module`. @@ -341,6 +363,9 @@ to indicate the search result of :func:`find_module`. ``None`` is inserted into ``sys.path_importer_cache`` instead of an instance of :class:`NullImporter`. + .. deprecated:: 3.4 + Insert ``None`` into ``sys.path_importer_cache`` instead. + .. _examples-imp: diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index efd027b..1c0eff7 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -90,7 +90,7 @@ Functions Find the loader for a module, optionally within the specified *path*. If the module is in :attr:`sys.modules`, then ``sys.modules[name].__loader__`` is - returned (unless the loader would be ``None``, in which case + returned (unless the loader would be ``None`` or is not set, in which case :exc:`ValueError` is raised). Otherwise a search using :attr:`sys.meta_path` is done. ``None`` is returned if no loader is found. @@ -99,6 +99,12 @@ Functions will need to import all parent packages of the submodule and use the correct argument to *path*. + .. versionadded:: 3.3 + + .. versionchanged:: 3.4 + If ``__loader__`` is not set, raise :exc:`ValueError`, just like when the + attribute is set to ``None``. + .. function:: invalidate_caches() Invalidate the internal caches of finders stored at @@ -109,6 +115,73 @@ Functions .. versionadded:: 3.3 +.. function:: reload(module) + + Reload a previously imported *module*. The argument must be a module object, + so it must have been successfully imported before. This is useful if you + have edited the module source file using an external editor and want to try + out the new version without leaving the Python interpreter. The return value + is the module object (the same as the *module* argument). + + When :func:`.reload` is executed: + + * Python modules' code is recompiled and the module-level code re-executed, + defining a new set of objects which are bound to names in the module's + dictionary by reusing the :term:`loader` which originally loaded the + module. The ``init`` function of extension modules is not called a second + time. + + * As with all other objects in Python the old objects are only reclaimed + after their reference counts drop to zero. + + * The names in the module namespace are updated to point to any new or + changed objects. + + * Other references to the old objects (such as names external to the module) are + not rebound to refer to the new objects and must be updated in each namespace + where they occur if that is desired. + + 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 does not define a name that was defined by the old version, the old + definition remains. This feature can be used to the module's advantage if it + maintains a global table or cache of objects --- with a :keyword:`try` + statement it can test for the table's presence and skip its initialization if + desired:: + + try: + cache + except NameError: + cache = {} + + It is legal though generally not very useful to reload built-in or + dynamically loaded modules (this is not true for e.g. :mod:`sys`, + :mod:`__main__`, :mod:`__builtin__` and other key modules where reloading is + frowned upon). In many cases, however, extension modules are not designed to + be initialized more than once, and may fail in arbitrary ways when reloaded. + + If a module imports objects from another module using :keyword:`from` ... + :keyword:`import` ..., calling :func:`reload` for the other module does not + redefine the objects imported from it --- one way around this is to + re-execute the :keyword:`from` statement, another is to use :keyword:`import` + and qualified names (*module.name*) instead. + + If a module instantiates instances of a class, reloading the module that + defines the class does not affect the method definitions of the instances --- + they continue to use the old class definition. The same is true for derived + classes. + + .. versionadded:: 3.4 + :mod:`importlib.abc` -- Abstract base classes related to import --------------------------------------------------------------- @@ -132,8 +205,6 @@ ABC hierarchy:: +-- ExecutionLoader --+ +-- FileLoader +-- SourceLoader - +-- PyLoader (deprecated) - +-- PyPycLoader (deprecated) .. class:: Finder @@ -149,6 +220,10 @@ ABC hierarchy:: module. Originally specified in :pep:`302`, this method was meant for use in :data:`sys.meta_path` and in the path-based import subsystem. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of raising + :exc:`NotImplementedError`. + .. class:: MetaPathFinder @@ -165,12 +240,19 @@ ABC hierarchy:: will be the value of :attr:`__path__` from the parent package. If a loader cannot be found, ``None`` is returned. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of raising + :exc:`NotImplementedError`. + .. method:: invalidate_caches() An optional method which, when called, should invalidate any internal cache used by the finder. Used by :func:`importlib.invalidate_caches` when invalidating the caches of all finders on :data:`sys.meta_path`. + .. versionchanged:: 3.4 + Returns ``None`` when called instead of ``NotImplemented``. + .. class:: PathEntryFinder @@ -178,7 +260,7 @@ ABC hierarchy:: it bears some similarities to :class:`MetaPathFinder`, ``PathEntryFinder`` is meant for use only within the path-based import subsystem provided by :class:`PathFinder`. This ABC is a subclass of :class:`Finder` for - compatibility. + compatibility reasons only. .. versionadded:: 3.3 @@ -190,9 +272,12 @@ ABC hierarchy:: package. The loader may be ``None`` while specifying ``portion`` to signify the contribution of the file system locations to a namespace package. An empty list can be used for ``portion`` to signify the loader - is not part of a package. If ``loader`` is ``None`` and ``portion`` is - the empty list then no loader or location for a namespace package were - found (i.e. failure to find anything for the module). + is not part of a namespace package. If ``loader`` is ``None`` and + ``portion`` is the empty list then no loader or location for a namespace + package were found (i.e. failure to find anything for the module). + + .. versionchanged:: 3.4 + Returns ``(None, [])`` instead of raising :exc:`NotImplementedError`. .. method:: find_module(fullname) @@ -224,12 +309,11 @@ ABC hierarchy:: from the import. If the loader inserted a module and the load fails, it must be removed by the loader from :data:`sys.modules`; modules already in :data:`sys.modules` before the loader began execution should be left - alone. The :func:`importlib.util.module_for_loader` decorator handles - all of these details. + alone (see :func:`importlib.util.module_to_load`). The loader should set several attributes on the module. (Note that some of these attributes can change when a module is - reloaded.) + reloaded; see :meth:`init_module_attrs`): - :attr:`__name__` The name of the module. @@ -249,20 +333,39 @@ ABC hierarchy:: - :attr:`__package__` The parent package for the module/package. If the module is top-level then it has a value of the empty string. The - :func:`importlib.util.set_package` decorator can handle the details - for :attr:`__package__`. + :func:`importlib.util.module_for_loader` decorator can handle the + details for :attr:`__package__`. - :attr:`__loader__` - The loader used to load the module. - (This is not set by the built-in import machinery, - but it should be set whenever a :term:`loader` is used.) + The loader used to load the module. The + :func:`importlib.util.module_for_loader` decorator can handle the + details for :attr:`__package__`. + + .. versionchanged:: 3.4 + Raise :exc:`ImportError` when called instead of + :exc:`NotImplementedError`. .. method:: module_repr(module) - An abstract method which when implemented calculates and returns the - given module's repr, as a string. + An optional method which when implemented calculates and returns the + given module's repr, as a string. The module type's default repr() will + use the result of this method as appropriate. + + .. versionadded:: 3.3 + + .. versionchanged:: 3.4 + Made optional instead of an abstractmethod. + + .. method:: init_module_attrs(module) + + Set the :attr:`__loader__` attribute on the module. + + Subclasses overriding this method should set whatever appropriate + attributes it can, getting the module's name from :attr:`__name__` when + needed. All values should also be overridden so that reloading works as + expected. - .. versionadded: 3.3 + .. versionadded:: 3.4 .. class:: ResourceLoader @@ -281,6 +384,9 @@ ABC hierarchy:: be found. The *path* is expected to be constructed using a module's :attr:`__file__` attribute or an item from a package's :attr:`__path__`. + .. versionchanged:: 3.4 + Raises :exc:`IOError` instead of :exc:`NotImplementedError`. + .. class:: InspectLoader @@ -289,14 +395,21 @@ ABC hierarchy:: .. method:: get_code(fullname) - An abstract method to return the :class:`code` object for a module. - ``None`` is returned if the module does not have a code object + Return the code object for a module. + ``None`` should be returned if the module does not have a code object (e.g. built-in module). :exc:`ImportError` is raised if loader cannot find the requested module. + .. note:: + While the method has a default implementation, it is suggested that + it be overridden if possible for performance. + .. index:: single: universal newlines; importlib.abc.InspectLoader.get_source method + .. versionchanged:: 3.4 + No longer abstract and a concrete implementation is provided. + .. method:: get_source(fullname) An abstract method to return the source of a module. It is returned as @@ -305,12 +418,41 @@ ABC hierarchy:: if no source is available (e.g. a built-in module). Raises :exc:`ImportError` if the loader cannot find the module specified. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + .. method:: is_package(fullname) An abstract method to return a true value if the module is a package, a false value otherwise. :exc:`ImportError` is raised if the :term:`loader` cannot find the module. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + + .. method:: source_to_code(data, path='<string>') + + Create a code object from Python source. + + The *data* argument can be whatever the :func:`compile` function + supports (i.e. string or bytes). The *path* argument should be + the "path" to where the source code originated from, which can be an + abstract concept (e.g. location in a zip file). + + .. versionadded:: 3.4 + + .. method:: init_module_attrs(module) + + Set the :attr:`__package__` attribute and :attr:`__path__` attribute to + the empty list if appropriate along with what + :meth:`importlib.abc.Loader.init_module_attrs` sets. + + .. versionadded:: 3.4 + + .. method:: load_module(fullname) + + Implementation of :meth:`Loader.load_module`. + .. class:: ExecutionLoader @@ -328,6 +470,18 @@ ABC hierarchy:: the source file, regardless of whether a bytecode was used to load the module. + .. versionchanged:: 3.4 + Raises :exc:`ImportError` instead of :exc:`NotImplementedError`. + + .. method:: init_module_attrs(module) + + Set :attr:`__file__` and if initializing a package then set + :attr:`__path__` to ``[os.path.dirname(__file__)]`` along with + all attributes set by + :meth:`importlib.abc.InspectLoader.init_module_attrs`. + + .. versionadded:: 3.4 + .. class:: FileLoader(fullname, path) @@ -358,7 +512,7 @@ ABC hierarchy:: .. method:: get_data(path) - Returns the open, binary file for *path*. + Reads *path* as a binary file and returns the bytes from it. .. class:: SourceLoader @@ -373,7 +527,8 @@ ABC hierarchy:: loading is not supported. The abstract methods defined by this class are to add optional bytecode - file support. Not implementing these optional methods causes the loader to + file support. Not implementing these optional methods (or causing them to + raise :exc:`NotImplementedError`) causes the loader to only work with source code. Implementing the methods allows the loader to work with source *and* bytecode files; it does not allow for *sourceless* loading where only bytecode is provided. Bytecode files are an @@ -390,10 +545,13 @@ ABC hierarchy:: - ``'size'`` (optional): the size in bytes of the source code. Any other keys in the dictionary are ignored, to allow for future - extensions. + extensions. If the path cannot be handled, :exc:`IOError` is raised. .. versionadded:: 3.3 + .. versionchanged:: 3.4 + Raise :exc:`IOError` instead of :exc:`NotImplementedError`. + .. method:: path_mtime(path) Optional abstract method which returns the modification time for the @@ -402,7 +560,10 @@ ABC hierarchy:: .. deprecated:: 3.3 This method is deprecated in favour of :meth:`path_stats`. You don't have to implement it, but it is still available for compatibility - purposes. + purposes. Raise :exc:`IOError` if the path cannot be handled. + + .. versionchanged:: 3.4 + Raise :exc:`IOError` instead of :exc:`NotImplementedError`. .. method:: set_data(path, data) @@ -414,6 +575,9 @@ ABC hierarchy:: (:attr:`errno.EACCES`/:exc:`PermissionError`), do not propagate the exception. + .. versionchanged:: 3.4 + No longer raises :exc:`NotImplementedError` when called. + .. method:: get_code(fullname) Concrete implementation of :meth:`InspectLoader.get_code`. @@ -434,141 +598,13 @@ ABC hierarchy:: ``__init__`` when the file extension is removed **and** the module name itself does not end in ``__init__``. + .. method:: init_module_attr(module) -.. class:: PyLoader - - An abstract base class inheriting from - :class:`ExecutionLoader` and - :class:`ResourceLoader` designed to ease the loading of - Python source modules (bytecode is not handled; see - :class:`SourceLoader` for a source/bytecode ABC). A subclass - implementing this ABC will only need to worry about exposing how the source - code is stored; all other details for loading Python source code will be - handled by the concrete implementations of key methods. - - .. deprecated:: 3.2 - This class has been deprecated in favor of :class:`SourceLoader` and is - slated for removal in Python 3.4. See below for how to create a - subclass that is compatible with Python 3.1 onwards. - - If compatibility with Python 3.1 is required, then use the following idiom - to implement a subclass that will work with Python 3.1 onwards (make sure - to implement :meth:`ExecutionLoader.get_filename`):: - - try: - from importlib.abc import SourceLoader - except ImportError: - from importlib.abc import PyLoader as SourceLoader - - - class CustomLoader(SourceLoader): - def get_filename(self, fullname): - """Return the path to the source file.""" - # Implement ... + Set :attr:`__cached__` using :func:`imp.cache_from_source`. Other + attributes set by + :meth:`importlib.abc.ExecutionLoader.init_module_attrs`. - def source_path(self, fullname): - """Implement source_path in terms of get_filename.""" - try: - return self.get_filename(fullname) - except ImportError: - return None - - def is_package(self, fullname): - """Implement is_package by looking for an __init__ file - name as returned by get_filename.""" - filename = os.path.basename(self.get_filename(fullname)) - return os.path.splitext(filename)[0] == '__init__' - - - .. method:: source_path(fullname) - - An abstract method that returns the path to the source code for a - module. Should return ``None`` if there is no source code. - Raises :exc:`ImportError` if the loader knows it cannot handle the - module. - - .. method:: get_filename(fullname) - - A concrete implementation of - :meth:`importlib.abc.ExecutionLoader.get_filename` that - relies on :meth:`source_path`. If :meth:`source_path` returns - ``None``, then :exc:`ImportError` is raised. - - .. method:: load_module(fullname) - - A concrete implementation of :meth:`importlib.abc.Loader.load_module` - that loads Python source code. All needed information comes from the - abstract methods required by this ABC. The only pertinent assumption - made by this method is that when loading a package - :attr:`__path__` is set to ``[os.path.dirname(__file__)]``. - - .. method:: get_code(fullname) - - A concrete implementation of - :meth:`importlib.abc.InspectLoader.get_code` that creates code objects - from Python source code, by requesting the source code (using - :meth:`source_path` and :meth:`get_data`) and compiling it with the - built-in :func:`compile` function. - - .. method:: get_source(fullname) - - A concrete implementation of - :meth:`importlib.abc.InspectLoader.get_source`. Uses - :meth:`importlib.abc.ResourceLoader.get_data` and :meth:`source_path` - to get the source code. It tries to guess the source encoding using - :func:`tokenize.detect_encoding`. - - -.. class:: PyPycLoader - - An abstract base class inheriting from :class:`PyLoader`. - This ABC is meant to help in creating loaders that support both Python - source and bytecode. - - .. deprecated:: 3.2 - This class has been deprecated in favor of :class:`SourceLoader` and to - properly support :pep:`3147`. If compatibility is required with - Python 3.1, implement both :class:`SourceLoader` and :class:`PyLoader`; - instructions on how to do so are included in the documentation for - :class:`PyLoader`. Do note that this solution will not support - sourceless/bytecode-only loading; only source *and* bytecode loading. - - .. versionchanged:: 3.3 - Updated to parse (but not use) the new source size field in bytecode - files when reading and to write out the field properly when writing. - - .. method:: source_mtime(fullname) - - An abstract method which returns the modification time for the source - code of the specified module. The modification time should be an - integer. If there is no source code, return ``None``. If the - module cannot be found then :exc:`ImportError` is raised. - - .. method:: bytecode_path(fullname) - - An abstract method which returns the path to the bytecode for the - specified module, if it exists. It returns ``None`` - if no bytecode exists (yet). - Raises :exc:`ImportError` if the loader knows it cannot handle the - module. - - .. method:: get_filename(fullname) - - A concrete implementation of - :meth:`ExecutionLoader.get_filename` that relies on - :meth:`PyLoader.source_path` and :meth:`bytecode_path`. - If :meth:`source_path` returns a path, then that value is returned. - Else if :meth:`bytecode_path` returns a path, that path will be - returned. If a path is not available from both methods, - :exc:`ImportError` is raised. - - .. method:: write_bytecode(fullname, bytecode) - - An abstract method which has the loader write *bytecode* for future - use. If the bytecode is written, return ``True``. Return - ``False`` if the bytecode could not be written. This method - should not be called if :data:`sys.dont_write_bytecode` is true. - The *bytecode* argument should be a bytes string or bytes array. + .. versionadded:: 3.4 :mod:`importlib.machinery` -- Importers and path hooks @@ -844,6 +880,51 @@ find and load modules. This module contains the various objects that help in the construction of an :term:`importer`. +.. attribute:: MAGIC_NUMBER + + The bytes which represent the bytecode version number. If you need help with + loading/writing bytecode then consider :class:`importlib.abc.SourceLoader`. + + .. versionadded:: 3.4 + +.. function:: cache_from_source(path, debug_override=None) + + Return the :pep:`3147` path to the byte-compiled file associated with the + source *path*. For example, if *path* is ``/foo/bar/baz.py`` the return + value would be ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. + The ``cpython-32`` string comes from the current magic tag (see + :func:`get_tag`; if :attr:`sys.implementation.cache_tag` is not defined then + :exc:`NotImplementedError` will be raised). The returned path will end in + ``.pyc`` when ``__debug__`` is True or ``.pyo`` for an optimized Python + (i.e. ``__debug__`` is False). By passing in True or False for + *debug_override* you can override the system's value for ``__debug__`` for + extension selection. + + *path* need not exist. + + .. versionadded:: 3.4 + + +.. function:: source_from_cache(path) + + Given the *path* to a :pep:`3147` file name, return the associated source code + file path. For example, if *path* is + ``/foo/bar/__pycache__/baz.cpython-32.pyc`` the returned path would be + ``/foo/bar/baz.py``. *path* need not exist, however if it does not conform + to :pep:`3147` format, a ``ValueError`` is raised. If + :attr:`sys.implementation.cache_tag` is not defined, + :exc:`NotImplementedError` is raised. + + .. versionadded:: 3.4 + +.. function:: decode_source(source_bytes) + + Decode the given bytes representing source code and return it as a string + with universal newlines (as required by + :meth:`importlib.abc.InspectLoader.get_source`). + + .. versionadded:: 3.4 + .. function:: resolve_name(name, package) Resolve a relative module name to an absolute one. @@ -860,9 +941,23 @@ an :term:`importer`. .. versionadded:: 3.3 +.. function:: module_to_load(name, *, reset_name=True) + + Returns a :term:`context manager` which provides the module to load. The + module will either come from :attr:`sys.modules` in the case of reloading or + a fresh module if loading a new module. Proper cleanup of + :attr:`sys.modules` occurs if the module was new and an exception was + raised. + + If **reset_name** is true and the module requested is being reloaded then + the module's :attr:`__name__` attribute will + be reset to **name**, else it will be left untouched. + + .. versionadded:: 3.4 + .. decorator:: module_for_loader - A :term:`decorator` for a :term:`loader` method, + A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to handle selecting the proper module object to load with. The decorated method is expected to have a call signature taking two positional arguments @@ -873,55 +968,54 @@ an :term:`importer`. The decorated method will take in the **name** of the module to be loaded as expected for a :term:`loader`. If the module is not found in - :data:`sys.modules` then a new one is constructed with its - :attr:`__name__` attribute set to **name**, :attr:`__loader__` set to - **self**, and :attr:`__package__` set if - :meth:`importlib.abc.InspectLoader.is_package` is defined for **self** and - does not raise :exc:`ImportError` for **name**. If a new module is not - needed then the module found in :data:`sys.modules` will be passed into the - method. + :data:`sys.modules` then a new one is constructed. Regardless of where the + module came from, :attr:`__loader__` set to **self** and :attr:`__package__` + is set based on what :meth:`importlib.abc.InspectLoader.is_package` returns + (if available). These attributes are set unconditionally to support + reloading. If an exception is raised by the decorated method and a module was added to :data:`sys.modules` it will be removed to prevent a partially initialized module from being in left in :data:`sys.modules`. If the module was already in :data:`sys.modules` then it is left alone. - Use of this decorator handles all the details of which module object a - loader should initialize as specified by :pep:`302` as best as possible. - .. versionchanged:: 3.3 :attr:`__loader__` and :attr:`__package__` are automatically set (when possible). + .. versionchanged:: 3.4 + Set :attr:`__name__`, :attr:`__loader__` :attr:`__package__` + unconditionally to support reloading. + + .. deprecated:: 3.4 + For the benefit of :term:`loader` subclasses, please use + :func:`module_to_load` and + :meth:`importlib.abc.Loader.init_module_attrs` instead. + .. decorator:: set_loader - A :term:`decorator` for a :term:`loader` method, - to set the :attr:`__loader__` - attribute on loaded modules. If the attribute is already set the decorator - does nothing. It is assumed that the first positional argument to the - wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set to. + A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` + to set the :attr:`__loader__` + attribute on the returned module. If the attribute is already set the + decorator does nothing. It is assumed that the first positional argument to + the wrapped method (i.e. ``self``) is what :attr:`__loader__` should be set + to. .. note:: + As this decorator sets :attr:`__loader__` after loading the module, it is + recommended to use :meth:`importlib.abc.Loader.init_module_attrs` instead + when appropriate. - It is recommended that :func:`module_for_loader` be used over this - decorator as it subsumes this functionality. - + .. versionchanged:: 3.4 + Set ``__loader__`` if set to ``None``, as if the attribute does not + exist. .. decorator:: set_package - A :term:`decorator` for a :term:`loader` to set the :attr:`__package__` - attribute on the module returned by the loader. If :attr:`__package__` is - set and has a value other than ``None`` it will not be changed. - Note that the module returned by the loader is what has the attribute - set on and not the module found in :data:`sys.modules`. - - Reliance on this decorator is discouraged when it is possible to set - :attr:`__package__` before importing. By - setting it beforehand the code for the module is executed with the - attribute set and thus can be used by global level code during - initialization. + A :term:`decorator` for :meth:`importlib.abc.Loader.load_module` to set the :attr:`__package__` attribute on the returned module. If :attr:`__package__` + is set and has a value other than ``None`` it will not be changed. .. note:: - - It is recommended that :func:`module_for_loader` be used over this - decorator as it subsumes this functionality. + As this decorator sets :attr:`__package__` after loading the module, it is + recommended to use :meth:`importlib.abc.Loader.init_module_attrs` instead + when appropriate. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 40f482b..9f784fd 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -797,6 +797,23 @@ Classes and functions .. versionadded:: 3.3 +.. function:: unwrap(func, *, stop=None) + + Get the object wrapped by *func*. It follows the chain of :attr:`__wrapped__` + attributes returning the last object in the chain. + + *stop* is an optional callback accepting an object in the wrapper chain + as its sole argument that allows the unwrapping to be terminated early if + the callback returns a true value. If the callback never returns a true + value, the last object in the chain is returned as usual. For example, + :func:`signature` uses this to stop unwrapping if any object in the + chain has a ``__signature__`` attribute defined. + + :exc:`ValueError` is raised if a cycle is encountered. + + .. versionadded:: 3.4 + + .. _inspect-stack: The interpreter stack @@ -829,6 +846,10 @@ index of the current line within that list. finally: del frame + If you want to keep the frame around (for example to print a traceback + later), you can also break reference cycles by using the + :meth:`frame.clear` method. + The optional *context* argument supported by most of these functions specifies the number of lines of context to return, which are centered around the current line. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index f652039..5d97ee8 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -42,8 +42,7 @@ Compact encoding:: Pretty printing:: >>> import json - >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, - ... indent=4, separators=(',', ': '))) + >>> print(json.dumps({'4': 5, '6': 7}, sort_keys=True, indent=4)) { "4": 5, "6": 7 @@ -158,15 +157,13 @@ Basic Usage .. versionchanged:: 3.2 Allow strings for *indent* in addition to integers. - .. note:: - - Since the default item separator is ``', '``, the output might include - trailing whitespace when *indent* is specified. You can use - ``separators=(',', ': ')`` to avoid this. + If specified, *separators* should be an ``(item_separator, key_separator)`` + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. - If *separators* is an ``(item_separator, dict_separator)`` tuple, then it - will be used instead of the default ``(', ', ': ')`` separators. ``(',', - ':')`` is the most compact JSON representation. + .. versionchanged:: 3.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. *default(obj)* is a function that should return a serializable version of *obj* or raise :exc:`TypeError`. The default simply raises :exc:`TypeError`. @@ -248,6 +245,8 @@ Basic Usage kwarg; otherwise :class:`JSONDecoder` is used. Additional keyword arguments will be passed to the constructor of the class. + If the data being deserialized is not a valid JSON document, a + :exc:`ValueError` will be raised. .. function:: loads(s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, parse_constant=None, object_pairs_hook=None, **kw) @@ -257,6 +256,8 @@ Basic Usage The other arguments have the same meaning as in :func:`load`, except *encoding* which is ignored and deprecated. + If the data being deserialized is not a valid JSON document, a + :exc:`ValueError` will be raised. Encoders and Decoders --------------------- @@ -354,23 +355,26 @@ Encoders and Decoders .. _py-to-json-table: - +-------------------+---------------+ - | Python | JSON | - +===================+===============+ - | dict | object | - +-------------------+---------------+ - | list, tuple | array | - +-------------------+---------------+ - | str | string | - +-------------------+---------------+ - | int, float | number | - +-------------------+---------------+ - | True | true | - +-------------------+---------------+ - | False | false | - +-------------------+---------------+ - | None | null | - +-------------------+---------------+ + +----------------------------------------+---------------+ + | Python | JSON | + +========================================+===============+ + | dict | object | + +----------------------------------------+---------------+ + | list, tuple | array | + +----------------------------------------+---------------+ + | str | string | + +----------------------------------------+---------------+ + | int, float, int- & float-derived Enums | number | + +----------------------------------------+---------------+ + | True | true | + +----------------------------------------+---------------+ + | False | false | + +----------------------------------------+---------------+ + | None | null | + +----------------------------------------+---------------+ + + .. versionchanged:: 3.4 + Added support for int- and float-derived Enum classes. To extend this to recognize other objects, subclass and implement a :meth:`default` method with another method that returns a serializable object @@ -410,15 +414,13 @@ Encoders and Decoders .. versionchanged:: 3.2 Allow strings for *indent* in addition to integers. - .. note:: - - Since the default item separator is ``', '``, the output might include - trailing whitespace when *indent* is specified. You can use - ``separators=(',', ': ')`` to avoid this. - If specified, *separators* should be an ``(item_separator, key_separator)`` - tuple. The default is ``(', ', ': ')``. To get the most compact JSON - representation, you should specify ``(',', ':')`` to eliminate whitespace. + tuple. The default is ``(', ', ': ')`` if *indent* is ``None`` and + ``(',', ': ')`` otherwise. To get the most compact JSON representation, + you should specify ``(',', ':')`` to eliminate whitespace. + + .. versionchanged:: 3.4 + Use ``(',', ': ')`` as default if *indent* is not ``None``. If specified, *default* is a function that gets called for objects that can't otherwise be serialized. It should return a JSON encodable version of the diff --git a/Doc/library/logging.config.rst b/Doc/library/logging.config.rst index e34e010..37f29a0 100644 --- a/Doc/library/logging.config.rst +++ b/Doc/library/logging.config.rst @@ -76,11 +76,23 @@ in :mod:`logging` itself) and defining handlers which are declared either in .. function:: fileConfig(fname, defaults=None, disable_existing_loggers=True) - Reads the logging configuration from a :mod:`configparser`\-format file - named *fname*. This function can be called several times from an - application, allowing an end user to select from various pre-canned - configurations (if the developer provides a mechanism to present the choices - and load the chosen configuration). + Reads the logging configuration from a :mod:`configparser`\-format file. + This function can be called several times from an application, allowing an + end user to select from various pre-canned configurations (if the developer + provides a mechanism to present the choices and load the chosen + configuration). + + :param fname: A filename, or a file-like object, or an instance derived + from :class:`~configparser.RawConfigParser`. If a + ``RawConfigParser``-derived instance is passed, it is used as + is. Otherwise, a :class:`~configparser.Configparser` is + instantiated, and the configuration read by it from the + object passed in ``fname``. If that has a :meth:`readline` + method, it is assumed to be a file-like object and read using + :meth:`~configparser.ConfigParser.read_file`; otherwise, + it is assumed to be a filename and passed to + :meth:`~configparser.ConfigParser.read`. + :param defaults: Defaults to be passed to the ConfigParser can be specified in this argument. @@ -94,8 +106,17 @@ in :mod:`logging` itself) and defining handlers which are declared either in their ancestors are explicitly named in the logging configuration. + .. versionchanged:: 3.4 + An instance of a subclass of :class:`~configparser.RawConfigParser` is + now accepted as a value for ``fname``. This facilitates: + + * Use of a configuration file where logging configuration is just part + of the overall application configuration. + * Use of a configuration read from a file, and then modified by the using + application (e.g. based on command-line parameters or other aspects + of the runtime environment) before being passed to ``fileConfig``. -.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT) +.. function:: listen(port=DEFAULT_LOGGING_CONFIG_PORT, verify=None) Starts up a socket server on the specified port, and listens for new configurations. If no port is specified, the module's default @@ -106,6 +127,17 @@ in :mod:`logging` itself) and defining handlers which are declared either in :meth:`~threading.Thread.join` when appropriate. To stop the server, call :func:`stopListening`. + The ``verify`` argument, if specified, should be a callable which should + verify whether bytes received across the socket are valid and should be + processed. This could be done by encrypting and/or signing what is sent + across the socket, such that the ``verify`` callable can perform + signature verification and/or decryption. The ``verify`` callable is called + with a single argument - the bytes received across the socket - and should + return the bytes to be processed, or None to indicate that the bytes should + be discarded. The returned bytes could be the same as the passed in bytes + (e.g. when only verification is done), or they could be completely different + (perhaps if decryption were performed). + To send a configuration to the socket, read in the configuration file and send it to the socket as a string of bytes preceded by a four-byte length string packed in binary using ``struct.pack('>L', n)``. @@ -122,7 +154,12 @@ in :mod:`logging` itself) and defining handlers which are declared either in :func:`listen` socket and sending a configuration which runs whatever code the attacker wants to have executed in the victim's process. This is especially easy to do if the default port is used, but not hard even if a - different port is used). + different port is used). To avoid the risk of this happening, use the + ``verify`` argument to :func:`listen` to prevent unrecognised + configurations from being applied. + + .. versionchanged:: 3.4. + The ``verify`` argument was added. .. function:: stopListening() diff --git a/Doc/library/logging.handlers.rst b/Doc/library/logging.handlers.rst index 0855050..35a81f7 100644 --- a/Doc/library/logging.handlers.rst +++ b/Doc/library/logging.handlers.rst @@ -296,7 +296,7 @@ The :class:`TimedRotatingFileHandler` class, located in the timed intervals. -.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False) +.. class:: TimedRotatingFileHandler(filename, when='h', interval=1, backupCount=0, encoding=None, delay=False, utc=False, atTime=None) Returns a new instance of the :class:`TimedRotatingFileHandler` class. The specified file is opened and used as the stream for logging. On rotating it also @@ -346,6 +346,12 @@ timed intervals. If *delay* is true, then file opening is deferred until the first call to :meth:`emit`. + If *atTime* is not ``None``, it must be a ``datetime.time`` instance which + specifies the time of day when rollover occurs, for the cases where rollover + is set to happen "at midnight" or "on a particular weekday". + + .. versionchanged:: 3.4 + *atTime* parameter was added. .. method:: doRollover() diff --git a/Doc/library/marshal.rst b/Doc/library/marshal.rst index 3b9e3d2..124eb61 100644 --- a/Doc/library/marshal.rst +++ b/Doc/library/marshal.rst @@ -40,10 +40,11 @@ this module. The following types are supported: booleans, integers, floating point numbers, complex numbers, strings, bytes, bytearrays, tuples, lists, sets, frozensets, dictionaries, and code objects, where it should be understood that tuples, lists, sets, frozensets and dictionaries are only supported as long as -the values contained therein are themselves supported; and recursive lists, sets -and dictionaries should not be written (they will cause infinite loops). The +the values contained therein are themselves supported. singletons :const:`None`, :const:`Ellipsis` and :exc:`StopIteration` can also be marshalled and unmarshalled. +For format *version* lower than 3, recursive lists, sets and dictionaries cannot +be written (see below). There are functions that read/write files as well as functions operating on strings. @@ -103,7 +104,9 @@ In addition, the following constants are defined: Indicates the format that the module uses. Version 0 is the historical format, version 1 shares interned strings and version 2 uses a binary format - for floating point numbers. The current version is 2. + for floating point numbers. + Version 3 adds support for object instancing and recursion. + The current version is 3. .. rubric:: Footnotes diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index 3c9c9aa..0071025 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -93,11 +93,80 @@ To show the individual process IDs involved, here is an expanded example:: p.start() p.join() -For an explanation of why (on Windows) the ``if __name__ == '__main__'`` part is +For an explanation of why the ``if __name__ == '__main__'`` part is necessary, see :ref:`multiprocessing-programming`. +Start methods +~~~~~~~~~~~~~ + +Depending on the platform, :mod:`multiprocessing` supports three ways +to start a process. These *start methods* are + + *spawn* + The parent process starts a fresh python interpreter process. The + child process will only inherit those resources necessary to run + the process objects :meth:`~Process.run` method. In particular, + unnecessary file descriptors and handles from the parent process + will not be inherited. Starting a process using this method is + rather slow compared to using *fork* or *forkserver*. + + Available on Unix and Windows. The default on Windows. + + *fork* + The parent process uses :func:`os.fork` to fork the Python + interpreter. The child process, when it begins, is effectively + identical to the parent process. All resources of the parent are + inherited by the child process. Note that safely forking a + multithreaded process is problematic. + + Available on Unix only. The default on Unix. + + *forkserver* + When the program starts and selects the *forkserver* start method, + a server process is started. From then on, whenever a new process + is need the parent process connects to the server and requests + that it fork a new process. The fork server process is single + threaded so it is safe for it to use :func:`os.fork`. No + unnecessary resources are inherited. + + Available on Unix platforms which support passing file descriptors + over unix pipes. + +Before Python 3.4 *fork* was the only option available on Unix. Also, +prior to Python 3.4, child processes would inherit all the parents +inheritable handles on Windows. + +On Unix using the *spawn* or *forkserver* start methods will also +start a *semaphore tracker* process which tracks the unlinked named +semaphores created by processes of the program. When all processes +have exited the semaphore tracker unlinks any remaining semaphores. +Usually there should be none, but if a process was killed by a signal +there may some "leaked" semaphores. (Unlinking the named semaphores +is a serious matter since the system allows only a limited number, and +they will not be automatically unlinked until the next reboot.) + +To select the a start method you use the :func:`set_start_method` in +the ``if __name__ == '__main__'`` clause of the main module. For +example:: + + import multiprocessing as mp + + def foo(): + print('hello') + + if __name__ == '__main__': + mp.set_start_method('spawn') + p = mp.Process(target=foo) + p.start() + p.join() + +:func:`set_start_method` should not be used more than once in the +program. + + + Exchanging objects between processes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -274,15 +343,31 @@ processes in a few different ways. For example:: from multiprocessing import Pool + from time import sleep def f(x): return x*x if __name__ == '__main__': - with Pool(processes=4) as pool: # start 4 worker processes - result = pool.apply_async(f, [10]) # evaluate "f(10)" asynchronously - print(result.get(timeout=1)) # prints "100" unless your computer is *very* slow - print(pool.map(f, range(10))) # prints "[0, 1, 4,..., 81]" + # start 4 worker processes + with Pool(processes=4) as pool: + + # print "[0, 1, 4,..., 81]" + print(pool.map(f, range(10))) + + # print same numbers in arbitrary order + for i in pool.imap_unordered(f, range(10)): + print(i) + + # evaluate "f(10)" asynchronously + res = pool.apply_async(f, [10]) + print(res.get(timeout=1)) # prints "100" + + # make worker sleep for 10 secs + res = pool.apply_async(sleep, 10) + print(res.get(timeout=1)) # raises multiprocessing.TimeoutError + + # exiting the 'with'-block has stopped the pool Note that the methods of a pool should only ever be used by the process which created it. @@ -731,6 +816,9 @@ Miscellaneous Return the number of CPUs in the system. May raise :exc:`NotImplementedError`. + .. seealso:: + :func:`os.cpu_count` + .. function:: current_process() Return the :class:`Process` object corresponding to the current process. @@ -761,6 +849,24 @@ Miscellaneous If the module is being run normally by the Python interpreter then :func:`freeze_support` has no effect. +.. function:: get_all_start_methods() + + Returns a list of the supported start methods, the first of which + is the default. The possible start methods are ``'fork'``, + ``'spawn'`` and ``'forkserver'``. On Windows only ``'spawn'`` is + available. On Unix ``'fork'`` and ``'spawn'`` are always + supported, with ``'fork'`` being the default. + + .. versionadded:: 3.4 + +.. function:: get_start_method() + + Return the current start method. This can be ``'fork'``, + ``'spawn'`` or ``'forkserver'``. ``'fork'`` is the default on + Unix, while ``'spawn'`` is the default on Windows. + + .. versionadded:: 3.4 + .. function:: set_executable() Sets the path of the Python interpreter to use when starting a child process. @@ -769,8 +875,21 @@ Miscellaneous set_executable(os.path.join(sys.exec_prefix, 'pythonw.exe')) - before they can create child processes. (Windows only) + before they can create child processes. + + .. versionchanged:: 3.4 + Now supported on Unix when the ``'spawn'`` start method is used. + +.. function:: set_start_method(method) + + Set the method which should be used to start child processes. + *method* can be ``'fork'``, ``'spawn'`` or ``'forkserver'``. + + Note that this should be called at most once, and it should be + protected inside the ``if __name__ == '__main__'`` clause of the + main module. + .. versionadded:: 3.4 .. note:: @@ -1673,7 +1792,7 @@ with the :class:`Pool` class. callbacks and has a parallel map implementation. *processes* is the number of worker processes to use. If *processes* is - ``None`` then the number returned by :func:`cpu_count` is used. If + ``None`` then the number returned by :func:`os.cpu_count` is used. If *initializer* is not ``None`` then each worker process will call ``initializer(*initargs)`` when it starts. @@ -2177,43 +2296,8 @@ Below is an example session with logging turned on:: [INFO/MainProcess] sending shutdown message to manager [INFO/SyncManager-...] manager exiting with exitcode 0 -In addition to having these two logging functions, the multiprocessing also -exposes two additional logging level attributes. These are :const:`SUBWARNING` -and :const:`SUBDEBUG`. The table below illustrates where theses fit in the -normal level hierarchy. - -+----------------+----------------+ -| Level | Numeric value | -+================+================+ -| ``SUBWARNING`` | 25 | -+----------------+----------------+ -| ``SUBDEBUG`` | 5 | -+----------------+----------------+ - For a full table of logging levels, see the :mod:`logging` module. -These additional logging levels are used primarily for certain debug messages -within the multiprocessing module. Below is the same example as above, except -with :const:`SUBDEBUG` enabled:: - - >>> import multiprocessing, logging - >>> logger = multiprocessing.log_to_stderr() - >>> logger.setLevel(multiprocessing.SUBDEBUG) - >>> logger.warning('doomed') - [WARNING/MainProcess] doomed - >>> m = multiprocessing.Manager() - [INFO/SyncManager-...] child process calling self.run() - [INFO/SyncManager-...] created temp directory /.../pymp-... - [INFO/SyncManager-...] manager serving at '/.../pymp-djGBXN/listener-...' - >>> del m - [SUBDEBUG/MainProcess] finalizer calling ... - [INFO/MainProcess] sending shutdown message to manager - [DEBUG/SyncManager-...] manager received shutdown message - [SUBDEBUG/SyncManager-...] calling <Finalize object, callback=unlink, ... - [SUBDEBUG/SyncManager-...] finalizer calling <built-in function unlink> ... - [SUBDEBUG/SyncManager-...] calling <Finalize object, dead> - [SUBDEBUG/SyncManager-...] finalizer calling <function rmtree at 0x5aa730> ... - [INFO/SyncManager-...] manager exiting with exitcode 0 The :mod:`multiprocessing.dummy` module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2234,8 +2318,10 @@ There are certain guidelines and idioms which should be adhered to when using :mod:`multiprocessing`. -All platforms -~~~~~~~~~~~~~ +All start methods +~~~~~~~~~~~~~~~~~ + +The following applies to all start methods. Avoid shared state @@ -2269,11 +2355,13 @@ Joining zombie processes Better to inherit than pickle/unpickle - On Windows many types from :mod:`multiprocessing` need to be picklable so - that child processes can use them. However, one should generally avoid - sending shared objects to other processes using pipes or queues. Instead - you should arrange the program so that a process which needs access to a - shared resource created elsewhere can inherit it from an ancestor process. + When using the *spawn* or *forkserver* start methods many types + from :mod:`multiprocessing` need to be picklable so that child + processes can use them. However, one should generally avoid + sending shared objects to other processes using pipes or queues. + Instead you should arrange the program so that a process which + needs access to a shared resource created elsewhere can inherit it + from an ancestor process. Avoid terminating processes @@ -2320,15 +2408,17 @@ Joining processes that use queues Explicitly pass resources to child processes - On Unix a child process can make use of a shared resource created in a - parent process using a global resource. However, it is better to pass the - object as an argument to the constructor for the child process. + On Unix using the *fork* start method, a child process can make + use of a shared resource created in a parent process using a + global resource. However, it is better to pass the object as an + argument to the constructor for the child process. - Apart from making the code (potentially) compatible with Windows this also - ensures that as long as the child process is still alive the object will not - be garbage collected in the parent process. This might be important if some - resource is freed when the object is garbage collected in the parent - process. + Apart from making the code (potentially) compatible with Windows + and the other start methods this also ensures that as long as the + child process is still alive the object will not be garbage + collected in the parent process. This might be important if some + resource is freed when the object is garbage collected in the + parent process. So for instance :: @@ -2387,17 +2477,19 @@ Beware of replacing :data:`sys.stdin` with a "file like object" For more information, see :issue:`5155`, :issue:`5313` and :issue:`5331` -Windows -~~~~~~~ +The *spawn* and *forkserver* start methods +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Since Windows lacks :func:`os.fork` it has a few extra restrictions: +There are a few extra restriction which don't apply to the *fork* +start method. More picklability - Ensure that all arguments to :meth:`Process.__init__` are picklable. This - means, in particular, that bound or unbound methods cannot be used directly - as the ``target`` argument on Windows --- just define a function and use - that instead. + Ensure that all arguments to :meth:`Process.__init__` are + picklable. This means, in particular, that bound or unbound + methods cannot be used directly as the ``target`` (unless you use + the *fork* start method) --- just define a function and use that + instead. Also, if you subclass :class:`~multiprocessing.Process` then make sure that instances will be picklable when the :meth:`Process.start @@ -2419,7 +2511,8 @@ Safe importing of main module interpreter without causing unintended side effects (such a starting a new process). - For example, under Windows running the following module would fail with a + For example, using the *spawn* or *forkserver* start method + running the following module would fail with a :exc:`RuntimeError`:: from multiprocessing import Process @@ -2433,13 +2526,14 @@ Safe importing of main module Instead one should protect the "entry point" of the program by using ``if __name__ == '__main__':`` as follows:: - from multiprocessing import Process, freeze_support + from multiprocessing import Process, freeze_support, set_start_method def foo(): print('hello') if __name__ == '__main__': freeze_support() + set_start_method('spawn') p = Process(target=foo) p.start() @@ -2470,26 +2564,7 @@ Using :class:`~multiprocessing.pool.Pool`: :language: python3 -Synchronization types like locks, conditions and queues: - -.. literalinclude:: ../includes/mp_synchronize.py - :language: python3 - - An example showing how to use queues to feed tasks to a collection of worker processes and collect the results: .. literalinclude:: ../includes/mp_workers.py - - -An example of how a pool of worker processes can each run a -:class:`~http.server.SimpleHTTPRequestHandler` instance while sharing a single -listening socket. - -.. literalinclude:: ../includes/mp_webserver.py - - -Some simple benchmarks comparing :mod:`multiprocessing` with :mod:`threading`: - -.. literalinclude:: ../includes/mp_benchmarks.py - diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst index 1d1aa40..73b51c0 100644 --- a/Doc/library/nntplib.rst +++ b/Doc/library/nntplib.rst @@ -1,4 +1,3 @@ - :mod:`nntplib` --- NNTP protocol client ======================================= @@ -71,7 +70,7 @@ The module itself defines the following classes: reader-specific commands, such as ``group``. If you get unexpected :exc:`NNTPPermanentError`\ s, you might need to set *readermode*. :class:`NNTP` class supports the :keyword:`with` statement to - unconditionally consume :exc:`socket.error` exceptions and to close the NNTP + unconditionally consume :exc:`OSError` exceptions and to close the NNTP connection when done. Here is a sample on how using it: >>> from nntplib import NNTP diff --git a/Doc/library/operator.rst b/Doc/library/operator.rst index de7a542..d01d33a 100644 --- a/Doc/library/operator.rst +++ b/Doc/library/operator.rst @@ -11,6 +11,9 @@ import operator from operator import itemgetter, iadd +**Source code:** :source:`Lib/operator.py` + +-------------- The :mod:`operator` module exports a set of efficient functions corresponding to the intrinsic operators of Python. For example, ``operator.add(x, y)`` is @@ -235,6 +238,14 @@ their character equivalents. .. XXX: find a better, readable, example +.. function:: length_hint(obj, default=0) + + Return an estimated length for the object *o*. First trying to return its + actual length, then an estimate using :meth:`object.__length_hint__`, and + finally returning the default value. + + .. versionadded:: 3.4 + The :mod:`operator` module also defines tools for generalized attribute and item lookups. These are useful for making fast field extractors as arguments for :func:`map`, :func:`sorted`, :meth:`itertools.groupby`, or other functions that diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index 1d46bf2..a0f006c 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -42,7 +42,6 @@ the :mod:`glob` module.) * :mod:`posixpath` for UNIX-style paths * :mod:`ntpath` for Windows paths * :mod:`macpath` for old-style MacOS paths - * :mod:`os2emxpath` for OS/2 EMX paths .. function:: abspath(path) @@ -250,15 +249,14 @@ the :mod:`glob` module.) On Unix, this is determined by the device number and i-node number and raises an exception if a :func:`os.stat` call on either pathname fails. - On Windows, two files are the same if they resolve to the same final path - name using the Windows API call GetFinalPathNameByHandle. This function - raises an exception if handles cannot be obtained to either file. - Availability: Unix, Windows. .. versionchanged:: 3.2 Added Windows support. + .. versionchanged:: 3.4 + Windows now uses the same implementation as all other platforms. + .. function:: sameopenfile(fp1, fp2) @@ -277,7 +275,10 @@ the :mod:`glob` module.) :func:`stat`. This function implements the underlying comparison used by :func:`samefile` and :func:`sameopenfile`. - Availability: Unix. + Availability: Unix, Windows. + + .. versionchanged:: 3.4 + Added Windows support. .. function:: split(path) diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 8bbb2ec..82d05ed 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -54,7 +54,7 @@ Notes on the availability of these functions: The name of the operating system dependent module imported. The following names have currently been registered: ``'posix'``, ``'nt'``, ``'mac'``, - ``'os2'``, ``'ce'``, ``'java'``. + ``'ce'``, ``'java'``. .. seealso:: :attr:`sys.platform` has a finer granularity. :func:`os.uname` gives @@ -851,11 +851,11 @@ as internal buffering of data. For a description of the flag and mode values, see the C run-time documentation; flag constants (like :const:`O_RDONLY` and :const:`O_WRONLY`) are defined in - this module too (see :ref:`open-constants`). In particular, on Windows adding + the :mod:`os` module. In particular, on Windows adding :const:`O_BINARY` is needed to open files in binary mode. This function can support :ref:`paths relative to directory descriptors - <dir_fd>`. + <dir_fd>` with the *dir_fd* parameter. Availability: Unix, Windows. @@ -869,6 +869,65 @@ as internal buffering of data. .. versionadded:: 3.3 The *dir_fd* argument. +The following constants are options for the *flags* parameter to the +:func:`~os.open` function. They can be combined using the bitwise OR operator +``|``. Some of them are not available on all platforms. For descriptions of +their availability and use, consult the :manpage:`open(2)` manual page on Unix +or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. + + +.. data:: O_RDONLY + O_WRONLY + O_RDWR + O_APPEND + O_CREAT + O_EXCL + O_TRUNC + + These constants are available on Unix and Windows. + + +.. data:: O_DSYNC + O_RSYNC + O_SYNC + O_NDELAY + O_NONBLOCK + O_NOCTTY + O_SHLOCK + O_EXLOCK + O_CLOEXEC + + These constants are only available on Unix. + + .. versionchanged:: 3.3 + Add :data:`O_CLOEXEC` constant. + +.. data:: O_BINARY + O_NOINHERIT + O_SHORT_LIVED + O_TEMPORARY + O_RANDOM + O_SEQUENTIAL + O_TEXT + + These constants are only available on Windows. + + +.. data:: O_ASYNC + O_DIRECT + O_DIRECTORY + O_NOFOLLOW + O_NOATIME + O_PATH + O_TMPFILE + + These constants are GNU extensions and not present if they are not defined by + the C library. + + .. versionchanged:: 3.4 + Add :data:`O_TMPFILE` constant. It's only available on Linux Kernel 3.11 + or newer. + .. function:: openpty() @@ -1082,78 +1141,6 @@ as internal buffering of data. .. versionadded:: 3.3 -.. _open-constants: - -``open()`` flag constants -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The following constants are options for the *flags* parameter to the -:func:`~os.open` function. They can be combined using the bitwise OR operator -``|``. Some of them are not available on all platforms. For descriptions of -their availability and use, consult the :manpage:`open(2)` manual page on Unix -or `the MSDN <http://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windows. - - -.. data:: O_RDONLY - O_WRONLY - O_RDWR - O_APPEND - O_CREAT - O_EXCL - O_TRUNC - - These constants are available on Unix and Windows. - - -.. data:: O_DSYNC - O_RSYNC - O_SYNC - O_NDELAY - O_NONBLOCK - O_NOCTTY - O_SHLOCK - O_EXLOCK - O_CLOEXEC - - These constants are only available on Unix. - - .. versionchanged:: 3.3 - Add :data:`O_CLOEXEC` constant. - -.. data:: O_BINARY - O_NOINHERIT - O_SHORT_LIVED - O_TEMPORARY - O_RANDOM - O_SEQUENTIAL - O_TEXT - - These constants are only available on Windows. - - -.. data:: O_ASYNC - O_DIRECT - O_DIRECTORY - O_NOFOLLOW - O_NOATIME - - These constants are GNU extensions and not present if they are not defined by - the C library. - - -.. data:: RTLD_LAZY - RTLD_NOW - RTLD_GLOBAL - RTLD_LOCAL - RTLD_NODELETE - RTLD_NOLOAD - RTLD_DEEPBIND - - See the Unix manual page :manpage:`dlopen(3)`. - - .. versionadded:: 3.3 - - .. _terminal-size: Querying the size of a terminal @@ -3047,7 +3034,7 @@ information, consult your Unix manpages. .. versionadded:: 3.3 -The following scheduling policies are exposed if they are a supported by the +The following scheduling policies are exposed if they are supported by the operating system. .. data:: SCHED_OTHER @@ -3156,10 +3143,6 @@ operating system. Return the set of CPUs the process with PID *pid* (or the current process if zero) is restricted to. - .. seealso:: - :func:`multiprocessing.cpu_count` returns the number of CPUs in the - system. - .. _os-path: @@ -3197,6 +3180,13 @@ Miscellaneous System Information Availability: Unix. +.. function:: cpu_count() + + Return the number of CPUs in the system. Returns None if undetermined. + + .. versionadded:: 3.4 + + .. function:: getloadavg() Return the number of processes in the system run queue averaged over the last @@ -3294,6 +3284,19 @@ Higher-level operations on pathnames are defined in the :mod:`os.path` module. The file path of the null device. For example: ``'/dev/null'`` for POSIX, ``'nul'`` for Windows. Also available via :mod:`os.path`. +.. data:: RTLD_LAZY + RTLD_NOW + RTLD_GLOBAL + RTLD_LOCAL + RTLD_NODELETE + RTLD_NOLOAD + RTLD_DEEPBIND + + Flags for use with the :func:`~sys.setdlopenflags` and + :func:`~sys.getdlopenflags` functions. See the Unix manual page + :manpage:`dlopen(3)` for what the different flags mean. + + .. versionadded:: 3.3 .. _os-miscfunc: diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst index b4080d6..e248d6b 100644 --- a/Doc/library/poplib.rst +++ b/Doc/library/poplib.rst @@ -13,8 +13,11 @@ -------------- This module defines a class, :class:`POP3`, which encapsulates a connection to a -POP3 server and implements the protocol as defined in :rfc:`1725`. The -:class:`POP3` class supports both the minimal and optional command sets. +POP3 server and implements the protocol as defined in :rfc:`1939`. The +:class:`POP3` class supports both the minimal and optional command sets from +:rfc:`1939`. The :class:`POP3` class also supports the `STLS` command introduced +in :rfc:`2595` to enable encrypted communication on an already established connection. + Additionally, this module provides a class :class:`POP3_SSL`, which provides support for connecting to POP3 servers that use SSL as an underlying protocol layer. @@ -97,6 +100,14 @@ An :class:`POP3` instance has the following methods: Returns the greeting string sent by the POP3 server. +.. method:: POP3.capa() + + Query the server's capabilities as specified in :rfc:`2449`. + Returns a dictionary in the form ``{'name': ['param'...]}``. + + .. versionadded:: 3.4 + + .. method:: POP3.user(username) Send user command, response should indicate that a password is required. @@ -176,6 +187,18 @@ An :class:`POP3` instance has the following methods: the unique id for that message in the form ``'response mesgnum uid``, otherwise result is list ``(response, ['mesgnum uid', ...], octets)``. +.. method:: POP3.stls(context=None) + + Start a TLS session on the active connection as specified in :rfc:`2595`. + This is only allowed before user authentication + + *context* parameter is a :class:`ssl.SSLContext` object which allows + bundling SSL configuration options, certificates and private keys into + a single (potentially long-lived) structure. + + .. versionadded:: 3.4 + + Instances of :class:`POP3_SSL` have no additional methods. The interface of this subclass is identical to its parent. diff --git a/Doc/library/pprint.rst b/Doc/library/pprint.rst index 3a86331..8d57c5d 100644 --- a/Doc/library/pprint.rst +++ b/Doc/library/pprint.rst @@ -14,8 +14,8 @@ The :mod:`pprint` module provides a capability to "pretty-print" arbitrary Python data structures in a form which can be used as input to the interpreter. If the formatted structures include objects which are not fundamental Python types, the representation may not be loadable. This may be the case if objects -such as files, sockets, classes, or instances are included, as well as many -other built-in objects which are not representable as Python constants. +such as files, sockets or classes are included, as well as many other +objects which are not representable as Python literals. The formatted representation keeps objects on a single line if it can, and breaks them onto multiple lines if they don't fit within the allowed width. @@ -65,7 +65,7 @@ The :mod:`pprint` module defines one class: ('spam', ('eggs', ('lumberjack', ('knights', ('ni', ('dead', (...))))))) -The :class:`PrettyPrinter` class supports several derivative functions: +The :mod:`pprint` module also provides several shortcut functions: .. function:: pformat(object, indent=1, width=80, depth=None) @@ -193,101 +193,141 @@ Example ------- To demonstrate several uses of the :func:`pprint` function and its parameters, -let's fetch information about a project from PyPI:: +let's fetch information about a project from `PyPI <https://pypi.python.org>`_:: >>> import json >>> import pprint >>> from urllib.request import urlopen - >>> with urlopen('http://pypi.python.org/pypi/configparser/json') as url: + >>> with urlopen('http://pypi.python.org/pypi/Twisted/json') as url: ... http_info = url.info() ... raw_data = url.read().decode(http_info.get_content_charset()) >>> project_info = json.loads(raw_data) - >>> result = {'headers': http_info.items(), 'body': project_info} In its basic form, :func:`pprint` shows the whole object:: - >>> pprint.pprint(result) - {'body': {'info': {'_pypi_hidden': False, - '_pypi_ordering': 12, - 'classifiers': ['Development Status :: 4 - Beta', - 'Intended Audience :: Developers', - 'License :: OSI Approved :: MIT License', - 'Natural Language :: English', - 'Operating System :: OS Independent', - 'Programming Language :: Python', - 'Programming Language :: Python :: 2', - 'Programming Language :: Python :: 2.6', - 'Programming Language :: Python :: 2.7', - 'Topic :: Software Development :: Libraries', - 'Topic :: Software Development :: Libraries :: Python Modules'], - 'download_url': 'UNKNOWN', - 'home_page': 'http://docs.python.org/py3k/library/configparser.html', - 'keywords': 'configparser ini parsing conf cfg configuration file', - 'license': 'MIT', - 'name': 'configparser', - 'package_url': 'http://pypi.python.org/pypi/configparser', - 'platform': 'any', - 'release_url': 'http://pypi.python.org/pypi/configparser/3.2.0r3', - 'requires_python': None, - 'stable_version': None, - 'summary': 'This library brings the updated configparser from Python 3.2+ to Python 2.6-2.7.', - 'version': '3.2.0r3'}, - 'urls': [{'comment_text': '', - 'downloads': 47, - 'filename': 'configparser-3.2.0r3.tar.gz', - 'has_sig': False, - 'md5_digest': '8500fd87c61ac0de328fc996fce69b96', - 'packagetype': 'sdist', - 'python_version': 'source', - 'size': 32281, - 'upload_time': '2011-05-10T16:28:50', - 'url': 'http://pypi.python.org/packages/source/c/configparser/configparser-3.2.0r3.tar.gz'}]}, - 'headers': [('Date', 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', 'chunked'), - ('Content-Type', 'application/json; charset="UTF-8"')]} + >>> pprint.pprint(project_info) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': ['Programming Language :: Python :: 2.6', + 'Programming Language :: Python :: 2.7', + 'Programming Language :: Python :: 2 :: Only'], + 'description': 'An extensible framework for Python programming, ' + 'with special focus\r\n' + 'on event-based network programming and ' + 'multiprotocol integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous networking framework written in Python', + 'version': '12.3.0'}, + 'urls': [{'comment_text': '', + 'downloads': 71844, + 'filename': 'Twisted-12.3.0.tar.bz2', + 'has_sig': False, + 'md5_digest': '6e289825f3bf5591cfd670874cc0862d', + 'packagetype': 'sdist', + 'python_version': 'source', + 'size': 2615733, + 'upload_time': '2012-12-26T12:47:03', + 'url': 'https://pypi.python.org/packages/source/T/Twisted/Twisted-12.3.0.tar.bz2'}, + {'comment_text': '', + 'downloads': 5224, + 'filename': 'Twisted-12.3.0.win32-py2.7.msi', + 'has_sig': False, + 'md5_digest': '6b778f5201b622a5519a2aca1a2fe512', + 'packagetype': 'bdist_msi', + 'python_version': '2.7', + 'size': 2916352, + 'upload_time': '2012-12-26T12:48:15', + 'url': 'https://pypi.python.org/packages/2.7/T/Twisted/Twisted-12.3.0.win32-py2.7.msi'}]} The result can be limited to a certain *depth* (ellipsis is used for deeper contents):: - >>> pprint.pprint(result, depth=3) - {'body': {'info': {'_pypi_hidden': False, - '_pypi_ordering': 12, - 'classifiers': [...], - 'download_url': 'UNKNOWN', - 'home_page': 'http://docs.python.org/py3k/library/configparser.html', - 'keywords': 'configparser ini parsing conf cfg configuration file', - 'license': 'MIT', - 'name': 'configparser', - 'package_url': 'http://pypi.python.org/pypi/configparser', - 'platform': 'any', - 'release_url': 'http://pypi.python.org/pypi/configparser/3.2.0r3', - 'requires_python': None, - 'stable_version': None, - 'summary': 'This library brings the updated configparser from Python 3.2+ to Python 2.6-2.7.', - 'version': '3.2.0r3'}, - 'urls': [{...}]}, - 'headers': [('Date', 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', 'chunked'), - ('Content-Type', 'application/json; charset="UTF-8"')]} - -Additionally, maximum *width* can be suggested. If a long object cannot be -split, the specified width will be exceeded:: - - >>> pprint.pprint(result['headers'], width=30) - [('Date', - 'Sat, 14 May 2011 12:48:52 GMT'), - ('Server', - 'Apache/2.2.16 (Debian)'), - ('Content-Disposition', - 'inline'), - ('Connection', 'close'), - ('Transfer-Encoding', - 'chunked'), - ('Content-Type', - 'application/json; charset="UTF-8"')] + >>> pprint.pprint(project_info, depth=2) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': [...], + 'description': 'An extensible framework for Python programming, ' + 'with special focus\r\n' + 'on event-based network programming and ' + 'multiprotocol integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous networking framework written in Python', + 'version': '12.3.0'}, + 'urls': [{...}, {...}]} + +Additionally, maximum character *width* can be suggested. If a long object +cannot be split, the specified width will be exceeded:: + + >>> pprint.pprint(project_info, depth=2, width=50) + {'info': {'_pypi_hidden': False, + '_pypi_ordering': 125, + 'author': 'Glyph Lefkowitz', + 'author_email': 'glyph@twistedmatrix.com', + 'bugtrack_url': '', + 'cheesecake_code_kwalitee_id': None, + 'cheesecake_documentation_id': None, + 'cheesecake_installability_id': None, + 'classifiers': [...], + 'description': 'An extensible ' + 'framework for ' + 'Python programming, ' + 'with special ' + 'focus\r\n' + 'on event-based ' + 'network programming ' + 'and multiprotocol ' + 'integration.', + 'docs_url': '', + 'download_url': 'UNKNOWN', + 'home_page': 'http://twistedmatrix.com/', + 'keywords': '', + 'license': 'MIT', + 'maintainer': '', + 'maintainer_email': '', + 'name': 'Twisted', + 'package_url': 'http://pypi.python.org/pypi/Twisted', + 'platform': 'UNKNOWN', + 'release_url': 'http://pypi.python.org/pypi/Twisted/12.3.0', + 'requires_python': None, + 'stable_version': None, + 'summary': 'An asynchronous ' + 'networking framework ' + 'written in Python', + 'version': '12.3.0'}, + 'urls': [{...}, {...}]} diff --git a/Doc/library/pty.rst b/Doc/library/pty.rst index 2b9385b..90baec5 100644 --- a/Doc/library/pty.rst +++ b/Doc/library/pty.rst @@ -45,6 +45,9 @@ The :mod:`pty` module defines the following functions: a file descriptor. The defaults try to read 1024 bytes each time they are called. + .. versionchanged:: 3.4 + :func:`spawn` now returns the status value from :func:`os.waitpid` + on the child process. Example ------- diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index 07ddc25..bae8450 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -28,7 +28,7 @@ byte-code cache files in the directory containing the source code. .. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1) - Compile a source file to byte-code and write out the byte-code cache file. + Compile a source file to byte-code and write out the byte-code cache file. The source code is loaded from the file name *file*. The byte-code is written to *cfile*, which defaults to the :PEP:`3147` path, ending in ``.pyc`` (``.pyo`` if optimization is enabled in the current interpreter). @@ -41,6 +41,13 @@ byte-code cache files in the directory containing the source code. is raised. This function returns the path to byte-compiled file, i.e. whatever *cfile* value was used. + If the path that *cfile* becomes (either explicitly specified or computed) + is a symlink or non-regular file, :exc:`FileExistsError` will be raised. + This is to act as a warning that import will turn those paths into regular + files if it is allowed to write byte-compiled files to those paths. This is + a side-effect of import using file renaming to place the final byte-compiled + file into place to prevent concurrent file writing issues. + *optimize* controls the optimization level and is passed to the built-in :func:`compile` function. The default of ``-1`` selects the optimization level of the current interpreter. @@ -50,6 +57,13 @@ byte-code cache files in the directory containing the source code. default was *file* + ``'c'`` (``'o'`` if optimization was enabled). Also added the *optimize* parameter. + .. versionchanged:: 3.4 + Changed code to use :mod:`importlib` for the byte-code cache file writing. + This means file creation/writing semantics now match what :mod:`importlib` + does, e.g. permissions, write-and-move semantics, etc. Also added the + caveat that :exc:`FileExistsError` is raised if *cfile* is a symlink or + non-regular file. + .. function:: main(args=None) diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index 1134619..692310b 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -190,28 +190,32 @@ Example The following example demonstrates how to use the :mod:`readline` module's history reading and writing functions to automatically load and save a history -file named :file:`.pyhist` from the user's home directory. The code below would -normally be executed automatically during interactive sessions from the user's -:envvar:`PYTHONSTARTUP` file. :: +file named :file:`.python_history` from the user's home directory. The code +below would normally be executed automatically during interactive sessions +from the user's :envvar:`PYTHONSTARTUP` file. :: + import atexit import os import readline - histfile = os.path.join(os.path.expanduser("~"), ".pyhist") + + histfile = os.path.join(os.path.expanduser("~"), ".python_history") try: readline.read_history_file(histfile) except FileNotFoundError: pass - import atexit + atexit.register(readline.write_history_file, histfile) - del os, histfile + +This code is actually automatically run when Python is run in +:ref:`interactive mode <tut-interactive>` (see :ref:`rlcompleter-config`). The following example extends the :class:`code.InteractiveConsole` class to support history save/restore. :: - import code - import readline import atexit + import code import os + import readline class HistoryConsole(code.InteractiveConsole): def __init__(self, locals=None, filename="<console>", diff --git a/Doc/library/rlcompleter.rst b/Doc/library/rlcompleter.rst index 633088d..9ed01c7 100644 --- a/Doc/library/rlcompleter.rst +++ b/Doc/library/rlcompleter.rst @@ -27,18 +27,10 @@ Example:: readline.__name__ readline.parse_and_bind( >>> readline. -The :mod:`rlcompleter` module is designed for use with Python's interactive -mode. A user can add the following lines to his or her initialization file -(identified by the :envvar:`PYTHONSTARTUP` environment variable) to get -automatic :kbd:`Tab` completion:: - - try: - import readline - except ImportError: - print("Module readline not available.") - else: - import rlcompleter - readline.parse_and_bind("tab: complete") +The :mod:`rlcompleter` module is designed for use with Python's +:ref:`interactive mode <tut-interactive>`. Unless Python is run with the +:option:`-S` option, the module is automatically imported and configured +(see :ref:`rlcompleter-config`). On platforms without :mod:`readline`, the :class:`Completer` class defined by this module can still be used for custom purposes. diff --git a/Doc/library/select.rst b/Doc/library/select.rst index b1fd3a8..2b5225d 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -47,11 +47,14 @@ The module defines the following: to :const:`EPOLL_CLOEXEC`, which causes the epoll descriptor to be closed automatically when :func:`os.execve` is called. See section :ref:`epoll-objects` below for the methods supported by epolling objects. - + They also support the :keyword:`with` statement. .. versionchanged:: 3.3 Added the *flags* parameter. + .. versionchanged:: 3.4 + Support for the :keyword:`with` statement was added. + .. function:: poll() @@ -144,6 +147,27 @@ descriptors), ``/dev/poll`` is O(active file descriptors). object. +.. method:: devpoll.close() + + Close the file descriptor of the polling object. + + .. versionadded:: 3.4 + + +.. attribute:: devpoll.closed + + ``True`` if the polling object is closed. + + .. versionadded:: 3.4 + + +.. method:: devpoll.fileno() + + Return the file descriptor number of the polling object. + + .. versionadded:: 3.4 + + .. method:: devpoll.register(fd[, eventmask]) Register a file descriptor with the polling object. Future calls to the @@ -241,6 +265,11 @@ Edge and Level Trigger Polling (epoll) Objects Close the control file descriptor of the epoll object. +.. attribute:: epoll.closed + + ``True`` if the epoll object is closed. + + .. method:: epoll.fileno() Return the file descriptor number of the control fd. @@ -360,6 +389,11 @@ Kqueue Objects Close the control file descriptor of the kqueue object. +.. attribute:: kqueue.closed + + ``True`` if the kqueue object is closed. + + .. method:: kqueue.fileno() Return the file descriptor number of the control fd. diff --git a/Doc/library/shelve.rst b/Doc/library/shelve.rst index 9d7d504..b60a548 100644 --- a/Doc/library/shelve.rst +++ b/Doc/library/shelve.rst @@ -44,8 +44,11 @@ lots of shared sub-objects. The keys are ordinary strings. .. note:: Do not rely on the shelf being closed automatically; always call - :meth:`close` explicitly when you don't need it any more, or use a - :keyword:`with` statement with :func:`contextlib.closing`. + :meth:`~Shelf.close` explicitly when you don't need it any more, or + use :func:`shelve.open` as a context manager:: + + with shelve.open('spam') as db: + db['eggs'] = 'eggs' .. warning:: @@ -118,10 +121,15 @@ Restrictions The *keyencoding* parameter is the encoding used to encode keys before they are used with the underlying dict. - .. versionadded:: 3.2 - The *keyencoding* parameter; previously, keys were always encoded in + :class:`Shelf` objects can also be used as context managers. + + .. versionchanged:: 3.2 + Added the *keyencoding* parameter; previously, keys were always encoded in UTF-8. + .. versionchanged:: 3.4 + Added context manager support. + .. class:: BsdDbShelf(dict, protocol=None, writeback=False, keyencoding='utf-8') diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst index a1457d0..e4f348c 100644 --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -53,7 +53,7 @@ Directory and files operations *dst* and return *dst*. *src* and *dst* are path names given as strings. *dst* must be the complete target file name; look at :func:`shutil.copy` for a copy that accepts a target directory path. If *src* and *dst* - specify the same file, :exc:`Error` is raised. + specify the same file, :exc:`SameFileError` is raised. The destination location must be writable; otherwise, an :exc:`OSError` exception will be raised. If *dst* already exists, it will be replaced. @@ -69,6 +69,19 @@ Directory and files operations Added *follow_symlinks* argument. Now returns *dst*. + .. versionchanged:: 3.4 + Raise :exc:`SameFileError` instead of :exc:`Error`. Since the former is + a subclass of the latter, this change is backward compatible. + + +.. exception:: SameFileError + + This exception is raised if source and destination in :func:`copyfile` + are the same file. + + .. versionadded:: 3.4 + + .. function:: copymode(src, dst, *, follow_symlinks=True) Copy the permission bits from *src* to *dst*. The file contents, owner, and @@ -380,11 +393,10 @@ provided by this module. :: errors.extend(err.args[0]) try: copystat(src, dst) - except WindowsError: - # can't copy file access times on Windows - pass except OSError as why: - errors.extend((src, dst, str(why))) + # can't copy file access times on Windows + if why.winerror is None: + errors.extend((src, dst, str(why))) if errors: raise Error(errors) diff --git a/Doc/library/site.rst b/Doc/library/site.rst index 36b80c3..2175c3e 100644 --- a/Doc/library/site.rst +++ b/Doc/library/site.rst @@ -111,6 +111,23 @@ empty, and the path manipulations are skipped; however the import of :mod:`sitecustomize` and :mod:`usercustomize` is still attempted. +.. _rlcompleter-config: + +Readline configuration +---------------------- + +On systems that support :mod:`readline`, this module will also import and +configure the :mod:`rlcompleter` module, if Python is started in +:ref:`interactive mode <tut-interactive>` and without the :option:`-S` option. +The default behavior is enable tab-completion and to use +:file:`~/.python_history` as the history save file. To disable it, override +the :data:`sys.__interactivehook__` attribute in your :mod:`sitecustomize` +or :mod:`usercustomize` module or your :envvar:`PYTHONSTARTUP` file. + + +Module contents +--------------- + .. data:: PREFIXES A list of prefixes for site-packages directories. @@ -153,8 +170,7 @@ empty, and the path manipulations are skipped; however the import of Adds all the standard site-specific directories to the module search path. This function is called automatically when this module is imported, - unless the :program:`python` interpreter was started with the :option:`-S` - flag. + unless the Python interpreter was started with the :option:`-S` flag. .. versionchanged:: 3.3 This function used to be called unconditionnally. diff --git a/Doc/library/smtpd.rst b/Doc/library/smtpd.rst index 2ca71ff..2c2df8a 100644 --- a/Doc/library/smtpd.rst +++ b/Doc/library/smtpd.rst @@ -27,7 +27,8 @@ SMTPServer Objects ------------------ -.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432) +.. class:: SMTPServer(localaddr, remoteaddr, data_size_limit=33554432, + map=None) Create a new :class:`SMTPServer` object, which binds to local address *localaddr*. It will treat *remoteaddr* as an upstream SMTP relayer. It @@ -38,6 +39,8 @@ SMTPServer Objects accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no limit. + A dictionary can be specified in *map* to avoid using a global socket map. + .. method:: process_message(peer, mailfrom, rcpttos, data) Raise :exc:`NotImplementedError` exception. Override this in subclasses to @@ -53,6 +56,9 @@ SMTPServer Objects Override this in subclasses to use a custom :class:`SMTPChannel` for managing SMTP clients. + .. versionchanged:: 3.4 + The *map* argument was added. + DebuggingServer Objects ----------------------- @@ -90,11 +96,20 @@ MailmanProxy Objects SMTPChannel Objects ------------------- -.. class:: SMTPChannel(server, conn, addr) +.. class:: SMTPChannel(server, conn, addr, data_size_limit=33554432, + map=None)) Create a new :class:`SMTPChannel` object which manages the communication between the server and a single SMTP client. + *conn* and *addr* are as per the instance variables described below. + + *data_size_limit* specifies the maximum number of bytes that will be + accepted in a ``DATA`` command. A value of ``None`` or ``0`` means no + limit. + + A dictionary can be specified in *map* to avoid using a global socket map. + To use a custom SMTPChannel implementation you need to override the :attr:`SMTPServer.channel_class` of your :class:`SMTPServer`. diff --git a/Doc/library/smtplib.rst b/Doc/library/smtplib.rst index addc6be..a7d1538 100644 --- a/Doc/library/smtplib.rst +++ b/Doc/library/smtplib.rst @@ -110,8 +110,8 @@ A nice selection of exceptions is defined as well: .. exception:: SMTPException - The base exception class for all the other exceptions provided by this - module. + Subclass of :exc:`OSError` that is the base exception class for all + the other exceptions provided by this module. .. exception:: SMTPServerDisconnected diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index b442b7c..edd196a 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -107,8 +107,8 @@ created. Socket addresses are represented as follows: .. versionadded:: 3.3 -- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`) - support specific representations. +- Certain other address families (:const:`AF_BLUETOOTH`, :const:`AF_PACKET`, + :const:`AF_CAN`) support specific representations. .. XXX document them! @@ -257,6 +257,16 @@ The module :mod:`socket` exports the following constants and functions: .. versionadded:: 3.3 +.. data:: CAN_BCM + CAN_BCM_* + + CAN_BCM, in the CAN protocol family, is the broadcast manager (BCM) protocol. + Broadcast manager constants, documented in the Linux documentation, are also + defined in the socket module. + + Availability: Linux >= 2.6.25. + + .. versionadded:: 3.4 .. data:: AF_RDS PF_RDS @@ -283,6 +293,11 @@ The module :mod:`socket` exports the following constants and functions: TIPC related constants, matching the ones exported by the C socket API. See the TIPC documentation for more information. +.. data:: AF_LINK + + Availability: BSD, OSX. + + .. versionadded:: 3.4 .. data:: has_ipv6 @@ -452,13 +467,16 @@ The module :mod:`socket` exports the following constants and functions: :const:`AF_INET6`, :const:`AF_UNIX`, :const:`AF_CAN` or :const:`AF_RDS`. The socket type should be :const:`SOCK_STREAM` (the default), :const:`SOCK_DGRAM`, :const:`SOCK_RAW` or perhaps one of the other ``SOCK_`` - constants. The protocol number is usually zero and may be omitted in that - case or :const:`CAN_RAW` in case the address family is :const:`AF_CAN`. + constants. The protocol number is usually zero and may be omitted or in the + case where the address family is :const:`AF_CAN` the protocol should be one + of :const:`CAN_RAW` or :const:`CAN_BCM`. .. versionchanged:: 3.3 The AF_CAN family was added. The AF_RDS family was added. + .. versionchanged:: 3.4 + The CAN_BCM protocol was added. .. function:: socketpair([family[, type[, proto]]]) @@ -1331,7 +1349,16 @@ the interface:: s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF) The last example shows how to use the socket interface to communicate to a CAN -network. This example might require special priviledge:: +network using the raw socket protocol. To use CAN with the broadcast +manager protocol instead, open a socket with:: + + socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM) + +After binding (:const:`CAN_RAW`) or connecting (:const:`CAN_BCM`) the socket, you +can use the :meth:`socket.send`, and the :meth:`socket.recv` operations (and +their counterparts) on the socket object as usual. + +This example might require special priviledge:: import socket import struct diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 08e3a2e..529dc94 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -159,7 +159,7 @@ Module functions and constants first blank for the column name: the column name would simply be "x". -.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements]) +.. function:: connect(database[, timeout, detect_types, isolation_level, check_same_thread, factory, cached_statements, uri]) Opens a connection to the SQLite database file *database*. You can use ``":memory:"`` to open a database connection to a database that resides in RAM @@ -195,6 +195,18 @@ Module functions and constants for the connection, you can set the *cached_statements* parameter. The currently implemented default is to cache 100 statements. + If *uri* is true, *database* is interpreted as a URI. This allows you + to specify options. For example, to open a database in read-only mode + you can use:: + + db = sqlite3.connect('file:path/to/database?mode=ro', uri=True) + + More information about this feature, including a list of recognized options, can + be found in the `SQLite URI documentation <http://www.sqlite.org/uri.html>`_. + + .. versionchanged:: 3.4 + Added the *uri* parameter. + .. function:: register_converter(typename, callable) diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst index abb95c3..983c144 100644 --- a/Doc/library/ssl.rst +++ b/Doc/library/ssl.rst @@ -26,7 +26,8 @@ probably additional platforms, as long as OpenSSL is installed on that platform. Some behavior may be platform dependent, since calls are made to the operating system socket APIs. The installed version of OpenSSL may also - cause variations in behavior. + cause variations in behavior. For example, TLSv1.1 and TLSv1.2 come with + openssl version 1.0.1. This section documents the objects and functions in the ``ssl`` module; for more general information about TLS, SSL, and certificates, the reader is referred to @@ -177,14 +178,16 @@ instead. .. table:: - ======================== ========= ========= ========== ========= - *client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** - ------------------------ --------- --------- ---------- --------- - *SSLv2* yes no yes no - *SSLv3* no yes yes no - *SSLv23* yes no yes no - *TLSv1* no no yes yes - ======================== ========= ========= ========== ========= + ======================== ========= ========= ========== ========= =========== =========== + *client* / **server** **SSLv2** **SSLv3** **SSLv23** **TLSv1** **TLSv1.1** **TLSv1.2** + ------------------------ --------- --------- ---------- --------- ----------- ----------- + *SSLv2* yes no yes no no no + *SSLv3* no yes yes no no no + *SSLv23* yes no yes no no no + *TLSv1* no no yes yes no no + *TLSv1.1* no no yes no yes no + *TLSv1.2* no no yes no no yes + ======================== ========= ========= ========== ========= =========== =========== .. note:: @@ -340,6 +343,37 @@ Certificate handling Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of bytes for that same certificate. +.. function:: get_default_verify_paths() + + Returns a named tuple with paths to OpenSSL's default cafile and capath. + The paths are the same as used by + :meth:`SSLContext.set_default_verify_paths`. The return value is a + :term:`named tuple` ``DefaultVerifyPaths``: + + * :attr:`cafile` - resolved path to cafile or None if the file doesn't exist, + * :attr:`capath` - resolved path to capath or None if the directory doesn't exist, + * :attr:`openssl_cafile_env` - OpenSSL's environment key that points to a cafile, + * :attr:`openssl_cafile` - hard coded path to a cafile, + * :attr:`openssl_capath_env` - OpenSSL's environment key that points to a capath, + * :attr:`openssl_capath` - hard coded path to a capath directory + + .. versionadded:: 3.4 + +.. function:: enum_cert_store(store_name, cert_type='certificate') + + Retrieve certificates from Windows' system cert store. *store_name* may be + one of ``CA``, ``ROOT`` or ``MY``. Windows may provide additional cert + stores, too. *cert_type* is either ``certificate`` for X.509 certificates + or ``crl`` for X.509 certificate revocation lists. + + The function returns a list of (bytes, encoding_type) tuples. The + encoding_type flag can be interpreted with :const:`X509_ASN_ENCODING` or + :const:`PKCS_7_ASN_ENCODING`. + + Availability: Windows. + + .. versionadded:: 3.4 + Constants ^^^^^^^^^ @@ -401,9 +435,25 @@ Constants .. data:: PROTOCOL_TLSv1 - Selects TLS version 1 as the channel encryption protocol. This is the most + Selects TLS version 1.0 as the channel encryption protocol. + +.. data:: PROTOCOL_TLSv1_1 + + + Selects TLS version 1.1 as the channel encryption protocol. + Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + +.. data:: PROTOCOL_TLSv1_2 + + + Selects TLS version 1.2 as the channel encryption protocol. This is the most modern version, and probably the best choice for maximum protection, if both sides can speak it. + Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 .. data:: OP_ALL @@ -437,6 +487,22 @@ Constants .. versionadded:: 3.2 +.. data:: OP_NO_TLSv1_1 + + Prevents a TLSv1.1 connection. This option is only applicable in conjunction + with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.1 as + the protocol version. Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + +.. data:: OP_NO_TLSv1_2 + + Prevents a TLSv1.2 connection. This option is only applicable in conjunction + with :const:`PROTOCOL_SSLv23`. It prevents the peers from choosing TLSv1.2 as + the protocol version. Available only with openssl version 1.0.1+. + + .. versionadded:: 3.4 + .. data:: OP_CIPHER_SERVER_PREFERENCE Use the server's cipher ordering preference, rather than the client's. @@ -533,6 +599,28 @@ Constants .. versionadded:: 3.2 +.. data:: ALERT_DESCRIPTION_HANDSHAKE_FAILURE + ALERT_DESCRIPTION_INTERNAL_ERROR + ALERT_DESCRIPTION_* + + Alert Descriptions from :rfc:`5246` and others. The `IANA TLS Alert Registry + <http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6>`_ + contains this list and references to the RFCs where their meaning is defined. + + Used as the return value of the callback function in + :meth:`SSLContext.set_servername_callback`. + + .. versionadded:: 3.4 + +.. data:: X509_ASN_ENCODING + PKCS_7_ASN_ENCODING + + Encoding flags for :func:`enum_cert_store`. + + Availability: Windows. + + .. versionadded:: 3.4 + SSL Sockets ----------- @@ -703,6 +791,19 @@ to speed up repeated connections from the same clients. :class:`SSLContext` objects have the following methods and attributes: +.. method:: SSLContext.cert_store_stats() + + Get statistics about quantities of loaded X.509 certificates, count of + X.509 certificates flagged as CA certificates and certificate revocation + lists as dictionary. + + Example for a context with one CA cert and one other cert:: + + >>> context.cert_store_stats() + {'crl': 0, 'x509_ca': 1, 'x509': 2} + + .. versionadded:: 3.4 + .. method:: SSLContext.load_cert_chain(certfile, keyfile=None, password=None) Load a private key and the corresponding certificate. The *certfile* @@ -749,6 +850,17 @@ to speed up repeated connections from the same clients. following an `OpenSSL specific layout <http://www.openssl.org/docs/ssl/SSL_CTX_load_verify_locations.html>`_. +.. method:: SSLContext.get_ca_certs(binary_form=False) + + Get a list of loaded "certification authority" (CA) certificates. If the + ``binary_form`` parameter is :const:`False` each list + entry is a dict like the output of :meth:`SSLSocket.getpeercert`. Otherwise + the method returns a list of DER-encoded certificates. The returned list + does not contain certificates from *capath* unless a certificate was + requested and loaded by a SSL connection. + + .. versionadded:: 3.4 + .. method:: SSLContext.set_default_verify_paths() Load a set of default "certification authority" (CA) certificates from @@ -786,6 +898,56 @@ to speed up repeated connections from the same clients. .. versionadded:: 3.3 +.. method:: SSLContext.set_servername_callback(server_name_callback) + + Register a callback function that will be called after the TLS Client Hello + handshake message has been received by the SSL/TLS server when the TLS client + specifies a server name indication. The server name indication mechanism + is specified in :rfc:`6066` section 3 - Server Name Indication. + + Only one callback can be set per ``SSLContext``. If *server_name_callback* + is ``None`` then the callback is disabled. Calling this function a + subsequent time will disable the previously registered callback. + + The callback function, *server_name_callback*, will be called with three + arguments; the first being the :class:`ssl.SSLSocket`, the second is a string + that represents the server name that the client is intending to communicate + (or :const:`None` if the TLS Client Hello does not contain a server name) + and the third argument is the original :class:`SSLContext`. The server name + argument is the IDNA decoded server name. + + A typical use of this callback is to change the :class:`ssl.SSLSocket`'s + :attr:`SSLSocket.context` attribute to a new object of type + :class:`SSLContext` representing a certificate chain that matches the server + name. + + 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.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 + will not contain return meaningful values nor can they be called safely. + + The *server_name_callback* function must return ``None`` to allow the + TLS negotiation to continue. If a TLS failure is required, a constant + :const:`ALERT_DESCRIPTION_* <ALERT_DESCRIPTION_INTERNAL_ERROR>` can be + returned. Other return values will result in a TLS fatal error with + :const:`ALERT_DESCRIPTION_INTERNAL_ERROR`. + + If there is a IDNA decoding error on the server name, the TLS connection + will terminate with an :const:`ALERT_DESCRIPTION_INTERNAL_ERROR` fatal TLS + alert message to the client. + + If an exception is raised from the *server_name_callback* function the TLS + connection will terminate with a fatal TLS alert message + :const:`ALERT_DESCRIPTION_HANDSHAKE_FAILURE`. + + This method will raise :exc:`NotImplementedError` if the OpenSSL library + had OPENSSL_NO_TLSEXT defined when it was built. + + .. versionadded:: 3.4 + .. method:: SSLContext.load_dh_params(dhfile) Load the key generation parameters for Diffie-Helman (DH) key exchange. @@ -1319,3 +1481,12 @@ use the ``openssl ciphers`` command on your system. `RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc4366>`_ Blake-Wilson et. al. + + `RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2 <http://www.ietf.org/rfc/rfc5246>`_ + T. Dierks et. al. + + `RFC 6066: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc/rfc6066>`_ + D. Eastlake + + `IANA TLS: Transport Layer Security (TLS) Parameters <http://www.iana.org/assignments/tls-parameters/tls-parameters.xml>`_ + IANA diff --git a/Doc/library/stat.rst b/Doc/library/stat.rst index 02513df..a021fe2 100644 --- a/Doc/library/stat.rst +++ b/Doc/library/stat.rst @@ -6,7 +6,8 @@ os.lstat() and os.fstat(). .. sectionauthor:: Skip Montanaro <skip@automatrix.com> -**Source code:** :source:`Lib/stat.py` +**Source code:** :source:`Modules/_stat.c` + :source:`Lib/stat.py` -------------- @@ -15,6 +16,9 @@ results of :func:`os.stat`, :func:`os.fstat` and :func:`os.lstat` (if they exist). For complete details about the :c:func:`stat`, :c:func:`fstat` and :c:func:`lstat` calls, consult the documentation for your system. +.. versionchanged:: 3.4 + The stat module is backed by a C implementation. + The :mod:`stat` module defines the following functions to test for specific file types: @@ -53,6 +57,24 @@ types: Return non-zero if the mode is from a socket. +.. function:: S_ISDOOR(mode) + + Return non-zero if the mode is from a door. + + .. versionadded:: 3.4 + +.. function:: S_ISPORT(mode) + + Return non-zero if the mode is from an event port. + + .. versionadded:: 3.4 + +.. function:: S_ISWHT(mode) + + Return non-zero if the mode is from a whiteout. + + .. versionadded:: 3.4 + Two additional functions are defined for more general manipulation of the file's mode: @@ -113,6 +135,10 @@ readable string: .. versionadded:: 3.3 + .. versionchanged:: 3.4 + The function supports :data:`S_IFDOOR`, :data:`S_IFPORT` and + :data:`S_IFWHT`. + All the variables below are simply symbolic indexes into the 10-tuple returned by :func:`os.stat`, :func:`os.fstat` or :func:`os.lstat`. @@ -210,6 +236,29 @@ Use of the functions above is more portable than use of the first set of flags: FIFO. +.. data:: S_IFDOOR + + Door. + + .. versionadded:: 3.4 + +.. data:: S_IFPORT + + Event port. + + .. versionadded:: 3.4 + +.. data:: S_IFWHT + + Whiteout. + + .. versionadded:: 3.4 + +.. note:: + + :data:`S_IFDOOR`, :data:`S_IFPORT` or :data:`S_IFWHT` are defined as + 0 when the platform does not have support for the file types. + The following flags can also be used in the *mode* argument of :func:`os.chmod`: .. data:: S_ISUID diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index 994506c..f2ea361 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -66,6 +66,19 @@ The module defines the following exception and functions: format (``len(buffer[offset:])`` must be at least ``calcsize(fmt)``). +.. function:: iter_unpack(fmt, buffer) + + Iteratively unpack from the buffer *buffer* according to the format + string *fmt*. This function returns an iterator which will read + equally-sized chunks from the buffer until all its contents have been + consumed. The buffer's size in bytes must be a multiple of the amount + of data required by the format, as reflected by :func:`calcsize`. + + Each iteration yields a tuple as specified by the format string. + + .. versionadded:: 3.4 + + .. function:: calcsize(fmt) Return the size of the struct (and hence of the bytes object produced by @@ -388,6 +401,13 @@ The :mod:`struct` module also defines the following type: (``len(buffer[offset:])`` must be at least :attr:`self.size`). + .. method:: iter_unpack(buffer) + + Identical to the :func:`iter_unpack` function, using the compiled format. + (``len(buffer)`` must be a multiple of :attr:`self.size`). + + .. versionadded:: 3.4 + .. attribute:: format The format string used to construct this Struct object. diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index f115634..208edd5 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -116,7 +116,7 @@ use cases, the underlying :class:`Popen` interface can be used directly. *timeout* was added. -.. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None) +.. function:: check_output(args, *, input=None, stdin=None, stderr=None, shell=False, universal_newlines=False, timeout=None) Run command with arguments and return its output. @@ -129,15 +129,21 @@ use cases, the underlying :class:`Popen` interface can be used directly. in :ref:`frequently-used-arguments` (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the :class:`Popen` constructor - this functions passes all - supplied arguments other than *timeout* directly through to that interface. - In addition, *stdout* is not permitted as an argument, as it is used - internally to collect the output from the subprocess. + supplied arguments other than *input* and *timeout* directly through to + that interface. In addition, *stdout* is not permitted as an argument, as + it is used internally to collect the output from the subprocess. The *timeout* argument is passed to :meth:`Popen.wait`. If the timeout expires, the child process will be killed and then waited for again. The :exc:`TimeoutExpired` exception will be re-raised after the child process has terminated. + The *input* argument is passed to :meth:`Popen.communicate` and thus to the + subprocess's stdin. If used it must be a byte sequence, or a string if + ``universal_newlines=True``. When used, the internal :class:`Popen` object + is automatically created with ``stdin=PIPE``, and the *stdin* argument may + not be used as well. + Examples:: >>> subprocess.check_output(["echo", "Hello World!"]) @@ -146,6 +152,10 @@ use cases, the underlying :class:`Popen` interface can be used directly. >>> subprocess.check_output(["echo", "Hello World!"], universal_newlines=True) 'Hello World!\n' + >>> subprocess.check_output(["sed", "-e", "s/foo/bar/"], + ... input=b"when in the course of fooman events\n") + b'when in the course of barman events\n' + >>> subprocess.check_output("exit 1", shell=True) Traceback (most recent call last): ... @@ -167,10 +177,6 @@ use cases, the underlying :class:`Popen` interface can be used directly. ... shell=True) 'ls: non_existent_file: No such file or directory\n' - .. versionadded:: 3.1 - - .. - .. warning:: Invoking the system shell with ``shell=True`` can be a security hazard @@ -183,9 +189,13 @@ use cases, the underlying :class:`Popen` interface can be used directly. read in the current process, the child process may block if it generates enough output to the pipe to fill up the OS pipe buffer. + .. versionadded:: 3.1 + .. versionchanged:: 3.3 *timeout* was added. + .. versionchanged:: 3.4 + *input* was added. .. data:: DEVNULL @@ -834,8 +844,6 @@ The :mod:`subprocess` module exposes the following constants. The new process has a new console, instead of inheriting its parent's console (the default). - This flag is always set when :class:`Popen` is created with ``shell=True``. - .. data:: CREATE_NEW_PROCESS_GROUP A :class:`Popen` ``creationflags`` parameter to specify that a new process diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index bc1d9fe..341764a 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -380,6 +380,21 @@ always available. .. versionadded:: 3.1 +.. function:: getallocatedblocks() + + Return the number of memory blocks currently allocated by the interpreter, + regardless of their size. This function is mainly useful for tracking + and debugging memory leaks. Because of the interpreter's internal + caches, the result can vary from call to call; you may have to call + :func:`_clear_type_cache()` and :func:`gc.collect()` to get more + predictable results. + + If a Python build or implementation cannot reasonably compute this + information, :func:`getallocatedblocks()` is allowed to return 0 instead. + + .. versionadded:: 3.4 + + .. function:: getcheckinterval() Return the interpreter's "check interval"; see :func:`setcheckinterval`. @@ -396,9 +411,10 @@ always available. .. function:: getdlopenflags() - Return the current value of the flags that are used for :c:func:`dlopen` calls. - The flag constants are defined in the :mod:`ctypes` and :mod:`DLFCN` modules. - Availability: Unix. + Return the current value of the flags that are used for + :c:func:`dlopen` calls. Symbolic names for the flag values can be + found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. + :data:`os.RTLD_LAZY`). Availability: Unix. .. function:: getfilesystemencoding() @@ -664,6 +680,16 @@ always available. .. versionadded:: 3.1 +.. data:: __interactivehook__ + + When present, this function is automatically called (with no arguments) + when the interpreter is launched in :ref:`interactive mode <tut-interactive>`. + This is done after the :envvar:`PYTHONSTARTUP` file is read, so that you + can set this hook there. + + .. versionadded:: 3.4 + + .. function:: intern(string) Enter *string* in the table of "interned" strings and return the interned string @@ -811,8 +837,6 @@ always available. Windows ``'win32'`` Windows/Cygwin ``'cygwin'`` Mac OS X ``'darwin'`` - OS/2 ``'os2'`` - OS/2 EMX ``'os2emx'`` ================ =========================== .. versionchanged:: 3.3 @@ -883,7 +907,7 @@ always available. the interpreter loads extension modules. Among other things, this will enable a lazy resolving of symbols when importing a module, if called as ``sys.setdlopenflags(0)``. To share symbols across extension modules, call as - ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag modules + ``sys.setdlopenflags(os.RTLD_GLOBAL)``. Symbolic names for the flag values can be found in the :mod:`os` module (``RTLD_xxx`` constants, e.g. :data:`os.RTLD_LAZY`). @@ -1093,7 +1117,6 @@ always available. | :const:`name` | Name of the thread implementation: | | | | | | * ``'nt'``: Windows threads | - | | * ``'os2'``: OS/2 threads | | | * ``'pthread'``: POSIX threads | | | * ``'solaris'``: Solaris threads | +------------------+---------------------------------------------------------+ diff --git a/Doc/library/sysconfig.rst b/Doc/library/sysconfig.rst index c47dcce..535ac54 100644 --- a/Doc/library/sysconfig.rst +++ b/Doc/library/sysconfig.rst @@ -83,8 +83,6 @@ Python currently supports seven schemes: located under the user home directory. - *nt*: scheme for NT platforms like Windows. - *nt_user*: scheme for NT platforms, when the *user* option is used. -- *os2*: scheme for OS/2 platforms. -- *os2_home*: scheme for OS/2 patforms, when the *user* option is used. Each scheme is itself composed of a series of paths and each path has a unique identifier. Python currently uses eight paths: diff --git a/Doc/library/textwrap.rst b/Doc/library/textwrap.rst index c625254..6ac1e77 100644 --- a/Doc/library/textwrap.rst +++ b/Doc/library/textwrap.rst @@ -10,11 +10,11 @@ -------------- -The :mod:`textwrap` module provides two convenience functions, :func:`wrap` and -:func:`fill`, as well as :class:`TextWrapper`, the class that does all the work, -and two utility functions, :func:`dedent` and :func:`indent`. If you're just wrapping or filling one -or two text strings, the convenience functions should be good enough; -otherwise, you should use an instance of :class:`TextWrapper` for efficiency. +The :mod:`textwrap` module provides some convenience functions, +as well as :class:`TextWrapper`, the class that does all the work. +If you're just wrapping or filling one or two text strings, the convenience +functions should be good enough; otherwise, you should use an instance of +:class:`TextWrapper` for efficiency. .. function:: wrap(text, width=70, **kwargs) @@ -39,19 +39,24 @@ otherwise, you should use an instance of :class:`TextWrapper` for efficiency. In particular, :func:`fill` accepts exactly the same keyword arguments as :func:`wrap`. -Both :func:`wrap` and :func:`fill` work by creating a :class:`TextWrapper` -instance and calling a single method on it. That instance is not reused, so for -applications that wrap/fill many text strings, it will be more efficient for you -to create your own :class:`TextWrapper` object. -Text is preferably wrapped on whitespaces and right after the hyphens in -hyphenated words; only then will long words be broken if necessary, unless -:attr:`TextWrapper.break_long_words` is set to false. +.. function:: shorten(text, width=70, *, placeholder=" [...]") + + Collapse and truncate the given text to fit in the given width. + + The text first has its whitespace collapsed. If it then fits in + the *width*, it is returned unchanged. Otherwise, as many words + as possible are joined and then the *placeholder* is appended:: + + >>> textwrap.shorten("Hello world!", width=12) + 'Hello world!' + >>> textwrap.shorten("Hello world!", width=11) + 'Hello [...]' + >>> textwrap.shorten("Hello world", width=10, placeholder="...") + 'Hello...' + + .. versionadded:: 3.4 -Two additional utility function, :func:`dedent` and :func:`indent`, are -provided to remove indentation from strings that have unwanted whitespace -to the left of the text and to add an arbitrary prefix to selected lines -in a block of text. .. function:: dedent(text) @@ -102,6 +107,16 @@ in a block of text. + world +:func:`wrap`, :func:`fill` and :func:`shorten` work by creating a +:class:`TextWrapper` instance and calling a single method on it. That +instance is not reused, so for applications that process many text +strings, it may be more efficient to create your own +:class:`TextWrapper` object. + +Text is preferably wrapped on whitespaces and right after the hyphens in +hyphenated words; only then will long words be broken if necessary, unless +:attr:`TextWrapper.break_long_words` is set to false. + .. class:: TextWrapper(**kwargs) The :class:`TextWrapper` constructor accepts a number of optional keyword @@ -235,7 +250,7 @@ in a block of text. was to always allow breaking hyphenated words. - :class:`TextWrapper` also provides two public methods, analogous to the + :class:`TextWrapper` also provides some public methods, analogous to the module-level convenience functions: .. method:: wrap(text) @@ -252,3 +267,14 @@ in a block of text. Wraps the single paragraph in *text*, and returns a single string containing the wrapped paragraph. + + .. function:: shorten(text, *, placeholder=" [...]") + + Collapse and truncate the given text to fit in :attr:`width` + characters. + + The text first has its whitespace collapsed. If it then fits in + :attr:`width`, it is returned as-is. Otherwise, as many words + as possible are joined and then the *placeholder* is appended. + + .. versionadded:: 3.4 diff --git a/Doc/library/timeit.rst b/Doc/library/timeit.rst index a487917..0cc1586 100644 --- a/Doc/library/timeit.rst +++ b/Doc/library/timeit.rst @@ -151,7 +151,7 @@ The module defines three convenience functions and a public class: t = Timer(...) # outside the try/except try: t.timeit(...) # or t.repeat(...) - except: + except Exception: t.print_exc() The advantage over the standard traceback is that source lines in the diff --git a/Doc/library/tkinter.rst b/Doc/library/tkinter.rst index 83a5375..377694f 100644 --- a/Doc/library/tkinter.rst +++ b/Doc/library/tkinter.rst @@ -750,32 +750,6 @@ Entry widget indexes (index, view index, etc.) displayed. You can use these :mod:`tkinter` functions to access these special points in text widgets: -.. function:: AtEnd() - refers to the last position in the text - - .. deprecated:: 3.3 - -.. function:: AtInsert() - refers to the point where the text cursor is - - .. deprecated:: 3.3 - -.. function:: AtSelFirst() - indicates the beginning point of the selected text - - .. deprecated:: 3.3 - -.. function:: AtSelLast() - denotes the last point of the selected text and finally - - .. deprecated:: 3.3 - -.. function:: At(x[, y]) - refers to the character at pixel location *x*, *y* (with *y* not used in the - case of a text entry widget, which contains a single line of text). - - .. deprecated:: 3.3 - Text widget indexes The index notation for Text widgets is very rich and is best described in the Tk man pages. diff --git a/Doc/library/traceback.rst b/Doc/library/traceback.rst index 32e5733..0533bea 100644 --- a/Doc/library/traceback.rst +++ b/Doc/library/traceback.rst @@ -146,7 +146,7 @@ module. :: source = input(">>> ") try: exec(source, envdir) - except: + except Exception: print("Exception in user code:") print("-"*60) traceback.print_exc(file=sys.stdout) diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 695480f..c4f57e4 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -107,9 +107,35 @@ Standard names are defined for the following types: C".) -.. data:: ModuleType +.. class:: ModuleType(name, doc=None) - The type of modules. + The type of :term:`modules <module>`. Constructor takes the name of the + module to be created and optionally its :term:`docstring`. + + .. attribute:: __doc__ + + The :term:`docstring` of the module. Defaults to ``None``. + + .. attribute:: __loader__ + + The :term:`loader` which loaded the module. Defaults to ``None``. + + .. versionchanged:: 3.4 + Defaults to ``None``. Previously the attribute was optional. + + .. attribute:: __name__ + + The name of the module. + + .. attribute:: __package__ + + Which :term:`package` a module belongs to. If the module is top-level + (i.e. not a part of any specific package) then the attribute should be set + to ``''``, else it should be set to the name of the package (which can be + :attr:`__name__` if the module is a package itself). Defaults to ``None``. + + .. versionchanged:: 3.4 + Defaults to ``None``. Previously the attribute was optional. .. data:: TracebackType @@ -212,6 +238,8 @@ Standard names are defined for the following types: keys = sorted(self.__dict__) items = ("{}={!r}".format(k, self.__dict__[k]) for k in keys) return "{}({})".format(type(self).__name__, ", ".join(items)) + def __eq__(self, other): + return self.__dict__ == other.__dict__ ``SimpleNamespace`` may be useful as a replacement for ``class NS: pass``. However, for a structured record type use :func:`~collections.namedtuple` diff --git a/Doc/library/unicodedata.rst b/Doc/library/unicodedata.rst index ad70dd9..26eced6 100644 --- a/Doc/library/unicodedata.rst +++ b/Doc/library/unicodedata.rst @@ -15,8 +15,8 @@ This module provides access to the Unicode Character Database (UCD) which defines character properties for all Unicode characters. The data contained in -this database is compiled from the `UCD version 6.1.0 -<http://www.unicode.org/Public/6.1.0/ucd>`_. +this database is compiled from the `UCD version 6.2.0 +<http://www.unicode.org/Public/6.2.0/ucd>`_. The module uses the same names and symbols as defined by Unicode Standard Annex #44, `"Unicode Character Database" @@ -166,6 +166,6 @@ Examples: .. rubric:: Footnotes -.. [#] http://www.unicode.org/Public/6.1.0/ucd/NameAliases.txt +.. [#] http://www.unicode.org/Public/6.2.0/ucd/NameAliases.txt -.. [#] http://www.unicode.org/Public/6.1.0/ucd/NamedSequences.txt +.. [#] http://www.unicode.org/Public/6.2.0/ucd/NamedSequences.txt diff --git a/Doc/library/unittest.mock-examples.rst b/Doc/library/unittest.mock-examples.rst index d7d697d..444c208 100644 --- a/Doc/library/unittest.mock-examples.rst +++ b/Doc/library/unittest.mock-examples.rst @@ -277,6 +277,20 @@ instantiate the class in those tests. ... AttributeError: object has no attribute 'old_method' +Using a specification also enables a smarter matching of calls made to the +mock, regardless of whether some parameters were passed as positional or +named arguments:: + + >>> def f(a, b, c): pass + ... + >>> mock = Mock(spec=f) + >>> mock(1, 2, 3) + <Mock name='mock()' id='140161580456576'> + >>> mock.assert_called_with(a=1, b=2, c=3) + +If you want this smarter matching to also work with method calls on the mock, +you can use :ref:`auto-speccing <auto-speccing>`. + If you want a stronger form of specification that prevents the setting of arbitrary attributes as well as the getting of them then you can use `spec_set` instead of `spec`. diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst index 6f3f693..4a7d647 100644 --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -264,7 +264,6 @@ the `new_callable` argument to `patch`. <Mock name='mock.method()' id='...'> >>> mock.method.assert_called_with(1, 2, 3, test='wow') - .. method:: assert_called_once_with(*args, **kwargs) Assert that the mock was called exactly once and with the specified @@ -685,6 +684,27 @@ have to create a dictionary and unpack it using `**`: ... KeyError +A callable mock which was created with a *spec* (or a *spec_set*) will +introspect the specification object's signature when matching calls to +the mock. Therefore, it can match the actual call's arguments regardless +of whether they were passed positionally or by name:: + + >>> def f(a, b, c): pass + ... + >>> mock = Mock(spec=f) + >>> mock(1, 2, c=3) + <Mock name='mock()' id='140161580456576'> + >>> mock.assert_called_with(1, 2, 3) + >>> mock.assert_called_with(a=1, b=2, c=3) + +This applies to :meth:`~Mock.assert_called_with`, +:meth:`~Mock.assert_called_once_with`, :meth:`~Mock.assert_has_calls` and +:meth:`~Mock.assert_any_call`. When :ref:`auto-speccing`, it will also +apply to method calls on the mock object. + + .. versionchanged:: 3.4 + Added signature introspection on specced and autospecced mock objects. + .. class:: PropertyMock(*args, **kwargs) @@ -1969,8 +1989,12 @@ mock_open default) then a `MagicMock` will be created for you, with the API limited to methods or attributes available on standard file handles. - `read_data` is a string for the `read` method of the file handle to return. - This is an empty string by default. + `read_data` is a string for the `read`, `readline`, and `readlines` methods + of the file handle to return. Calls to those methods will take data from + `read_data` until it is depleted. The mock of these methods is pretty + simplistic. If you need more control over the data that you are feeding to + the tested code you will need to customize this mock for yourself. + `read_data` is an empty string by default. Using `open` as a context manager is a great way to ensure your file handles are closed properly and is becoming common:: diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 0c00a26..66e427a 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -563,6 +563,68 @@ Skipped tests will not have :meth:`setUp` or :meth:`tearDown` run around them. Skipped classes will not have :meth:`setUpClass` or :meth:`tearDownClass` run. +.. _subtests: + +Distinguishing test iterations using subtests +--------------------------------------------- + +.. versionadded:: 3.4 + +When some of your tests differ only by a some very small differences, for +instance some parameters, unittest allows you to distinguish them inside +the body of a test method using the :meth:`~TestCase.subTest` context manager. + +For example, the following test:: + + class NumbersTest(unittest.TestCase): + + def test_even(self): + """ + Test that numbers between 0 and 5 are all even. + """ + for i in range(0, 6): + with self.subTest(i=i): + self.assertEqual(i % 2, 0) + +will produce the following output:: + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=1) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=3) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) (i=5) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + +Without using a subtest, execution would stop after the first failure, +and the error would be less easy to diagnose because the value of ``i`` +wouldn't be displayed:: + + ====================================================================== + FAIL: test_even (__main__.NumbersTest) + ---------------------------------------------------------------------- + Traceback (most recent call last): + File "subtests.py", line 32, in test_even + self.assertEqual(i % 2, 0) + AssertionError: 1 != 0 + + .. _unittest-contents: Classes and functions @@ -676,6 +738,21 @@ Test cases .. versionadded:: 3.1 + .. method:: subTest(msg=None, **params) + + Return a context manager which executes the enclosed code block as a + subtest. *msg* and *params* are optional, arbitrary values which are + displayed whenever a subtest fails, allowing you to identify them + clearly. + + A test case can contain any number of subtest declarations, and + they can be arbitrarily nested. + + See :ref:`subtests` for more information. + + .. versionadded:: 3.4 + + .. method:: debug() Run the test without collecting the result. This allows exceptions raised @@ -1500,7 +1577,9 @@ Loading and running tests directory must be specified separately. If importing a module fails, for example due to a syntax error, then this - will be recorded as a single error and discovery will continue. + will be recorded as a single error and discovery will continue. If the + import failure is due to :exc:`SkipTest` being raised, it will be recorded + as a skip instead of an error. If a test package name (directory with :file:`__init__.py`) matches the pattern then the package will be checked for a ``load_tests`` @@ -1519,6 +1598,15 @@ Loading and running tests .. versionadded:: 3.2 + .. versionchanged:: 3.4 + Modules that raise :exc:`SkipTest` on import are recorded as skips, + not errors. + + .. versionchanged:: 3.4 + Paths are sorted before being imported to ensure execution order for a + given test suite is the same even if the underlying file system's ordering + is not dependent on file name like in ext3/4. + The following attributes of a :class:`TestLoader` can be configured either by subclassing or assignment on an instance: @@ -1729,6 +1817,22 @@ Loading and running tests :attr:`unexpectedSuccesses` attribute. + .. method:: addSubTest(test, subtest, outcome) + + Called when a subtest finishes. *test* is the test case + corresponding to the test method. *subtest* is a custom + :class:`TestCase` instance describing the subtest. + + If *outcome* is :const:`None`, the subtest succeeded. Otherwise, + it failed with an exception where *outcome* is a tuple of the form + returned by :func:`sys.exc_info`: ``(type, value, traceback)``. + + The default implementation does nothing when the outcome is a + success, and records subtest failures as normal failures. + + .. versionadded:: 3.4 + + .. class:: TextTestResult(stream, descriptions, verbosity) A concrete implementation of :class:`TestResult` used by the @@ -1838,6 +1942,10 @@ Loading and running tests The *verbosity*, *failfast*, *catchbreak*, *buffer* and *warnings* parameters were added. + .. versionchanged:: 3.4 + The *defaultTest* parameter was changed to also accept an iterable of + test names. + load_tests Protocol ################### diff --git a/Doc/library/urllib.error.rst b/Doc/library/urllib.error.rst index 9c3fe91..7bd04b1 100644 --- a/Doc/library/urllib.error.rst +++ b/Doc/library/urllib.error.rst @@ -45,6 +45,13 @@ The following exceptions are raised by :mod:`urllib.error` as appropriate: This is usually a string explaining the reason for this error. + .. attribute:: headers + + The HTTP response headers for the HTTP request that cause the + :exc:`HTTPError`. + + .. versionadded:: 3.4 + .. exception:: ContentTooShortError(msg, content) This exception is raised when the :func:`urlretrieve` function detects that diff --git a/Doc/library/urllib.request.rst b/Doc/library/urllib.request.rst index 9f3e12e..91673f4 100644 --- a/Doc/library/urllib.request.rst +++ b/Doc/library/urllib.request.rst @@ -356,6 +356,11 @@ The following classes are provided: Open local files. +.. class:: DataHandler() + + Open data URLs. + + .. versionadded:: 3.4 .. class:: FTPHandler() @@ -391,6 +396,12 @@ request. The original URL passed to the constructor. + .. versionchanged:: 3.4 + + Request.full_url is a property with setter, getter and a deleter. Getting + :attr:`~Request.full_url` returns the original request URL with the + fragment, if it was present. + .. attribute:: Request.type The URI scheme. @@ -413,6 +424,10 @@ request. The entity body for the request, or None if not specified. + .. versionchanged:: 3.4 + Changing value of :attr:`Request.data` now deletes "Content-Length" + header if it was previously set or calculated. + .. attribute:: Request.unverifiable boolean, indicates whether the request is unverifiable as defined @@ -461,65 +476,29 @@ request. unredirected). -.. method:: Request.get_full_url() - - Return the URL given in the constructor. - - -.. method:: Request.set_proxy(host, type) - - Prepare the request by connecting to a proxy server. The *host* and *type* will - replace those of the instance, and the instance's selector will be the original - URL given in the constructor. - - -.. method:: Request.add_data(data) - - Set the :class:`Request` data to *data*. This is ignored by all handlers except - HTTP handlers --- and there it should be a byte string, and will change the - request to be ``POST`` rather than ``GET``. Deprecated in 3.3, use - :attr:`Request.data`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.has_data() - - Return whether the instance has a non-\ ``None`` data. Deprecated in 3.3, - use :attr:`Request.data`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.get_data() - - Return the instance's data. Deprecated in 3.3, use :attr:`Request.data`. +.. method:: Request.remove_header(header) - .. deprecated-removed:: 3.3 3.4 + Remove named header from the request instance (both from regular and + unredirected headers). + .. versionadded:: 3.4 -.. method:: Request.get_type() - - Return the type of the URL --- also known as the scheme. Deprecated in 3.3, - use :attr:`Request.type`. - - .. deprecated-removed:: 3.3 3.4 +.. method:: Request.get_full_url() -.. method:: Request.get_host() + Return the URL given in the constructor. - Return the host to which a connection will be made. Deprecated in 3.3, use - :attr:`Request.host`. + .. versionchanged:: 3.4 - .. deprecated-removed:: 3.3 3.4 + Returns :attr:`Request.full_url` -.. method:: Request.get_selector() +.. method:: Request.set_proxy(host, type) - Return the selector --- the part of the URL that is sent to the server. - Deprecated in 3.3, use :attr:`Request.selector`. + Prepare the request by connecting to a proxy server. The *host* and *type* will + replace those of the instance, and the instance's selector will be the original + URL given in the constructor. - .. deprecated-removed:: 3.3 3.4 .. method:: Request.get_header(header_name, default=None) @@ -531,26 +510,10 @@ request. Return a list of tuples (header_name, header_value) of the Request headers. - -.. method:: Request.set_proxy(host, type) - -.. method:: Request.get_origin_req_host() - - Return the request-host of the origin transaction, as defined by - :rfc:`2965`. See the documentation for the :class:`Request` constructor. - Deprecated in 3.3, use :attr:`Request.origin_req_host`. - - .. deprecated-removed:: 3.3 3.4 - - -.. method:: Request.is_unverifiable() - - Return whether the request is unverifiable, as defined by RFC 2965. See the - documentation for the :class:`Request` constructor. Deprecated in 3.3, use - :attr:`Request.unverifiable`. - - .. deprecated-removed:: 3.3 3.4 - +.. versionchanged:: 3.4 + Request methods add_data, has_data, get_data, get_type, get_host, + get_selector, get_origin_req_host and is_unverifiable deprecated since 3.3 + have been removed. .. _opener-director-objects: @@ -982,6 +945,21 @@ FileHandler Objects hostname is given, an :exc:`URLError` is raised. +.. _data-handler-objects: + +DataHandler Objects +------------------- + +.. method:: DataHandler.data_open(req) + + Read a data URL. This kind of URL contains the content encoded in the URL + itself. The data URL syntax is specified in :rfc:`2397`. This implementation + ignores white spaces in base64 encoded data URLs so the URL may be wrapped + in whatever source file it comes from. But even though some browsers don't + mind about a missing padding at the end of a base64 encoded data URL, this + implementation will raise an :exc:`ValueError` in that case. + + .. _ftp-handler-objects: FTPHandler Objects @@ -1397,7 +1375,9 @@ some point in the future. pair: FTP; protocol * Currently, only the following protocols are supported: HTTP (versions 0.9 and - 1.0), FTP, and local files. + 1.0), FTP, local files, and data URLs. + + .. versionchanged:: 3.4 Added support for data URLs. * The caching feature of :func:`urlretrieve` has been disabled until someone finds the time to hack proper processing of Expiration time headers. diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 80c75c2..74effae 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -79,8 +79,8 @@ creation according to their needs, the :class:`EnvBuilder` class. * ``system_site_packages`` -- a Boolean value indicating that the system Python site-packages should be available to the environment (defaults to ``False``). - * ``clear`` -- a Boolean value which, if True, will delete any existing target - directory instead of raising an exception (defaults to ``False``). + * ``clear`` -- a Boolean value which, if True, will delete the contents of + any existing target directory, before creating the environment. * ``symlinks`` -- a Boolean value indicating whether to attempt to symlink the Python binary (and any necessary DLLs or other binaries, @@ -92,7 +92,6 @@ creation according to their needs, the :class:`EnvBuilder` class. upgraded in-place (defaults to ``False``). - Creators of third-party virtual environment tools will be free to use the provided ``EnvBuilder`` class as a base class. diff --git a/Doc/library/wave.rst b/Doc/library/wave.rst index afafb45..9d12455 100644 --- a/Doc/library/wave.rst +++ b/Doc/library/wave.rst @@ -19,26 +19,30 @@ The :mod:`wave` module defines the following function and exception: .. function:: open(file, mode=None) If *file* is a string, open the file by that name, otherwise treat it as a - seekable file-like object. *mode* can be any of + seekable file-like object. *mode* can be: - ``'r'``, ``'rb'`` + ``'rb'`` Read only mode. - ``'w'``, ``'wb'`` + ``'wb'`` Write only mode. Note that it does not allow read/write WAV files. - A *mode* of ``'r'`` or ``'rb'`` returns a :class:`Wave_read` object, while a - *mode* of ``'w'`` or ``'wb'`` returns a :class:`Wave_write` object. If - *mode* is omitted and a file-like object is passed as *file*, ``file.mode`` - is used as the default value for *mode* (the ``'b'`` flag is still added if - necessary). + A *mode* of ``'rb'`` returns a :class:`Wave_read` object, while a *mode* of + ``'wb'`` returns a :class:`Wave_write` object. If *mode* is omitted and a + file-like object is passed as *file*, ``file.mode`` is used as the default + value for *mode*. If you pass in a file-like object, the wave object will not close it when its :meth:`close` method is called; it is the caller's responsibility to close the file object. + The :func:`.open` function may be used in a :keyword:`with` statement. When + the :keyword:`with` block completes, the :meth:`Wave_read.close() + <wave.Wave_read.close>` or :meth:`Wave_write.close() + <wave.Wave_write.close()>` method is called. + .. function:: openfp(file, mode) @@ -98,8 +102,9 @@ Wave_read objects, as returned by :func:`.open`, have the following methods: .. method:: Wave_read.getparams() - Returns a tuple ``(nchannels, sampwidth, framerate, nframes, comptype, - compname)``, equivalent to output of the :meth:`get\*` methods. + Returns a :func:`~collections.namedtuple` ``(nchannels, sampwidth, + framerate, nframes, comptype, compname)``, equivalent to output of the + :meth:`get\*` methods. .. method:: Wave_read.readframes(n) diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst index 224f442..818a6fa 100644 --- a/Doc/library/weakref.rst +++ b/Doc/library/weakref.rst @@ -51,10 +51,15 @@ garbage collection. :class:`WeakSet` implements the :class:`set` interface, but keeps weak references to its elements, just like a :class:`WeakKeyDictionary` does. -Most programs should find that using one of these weak container types is all -they need -- it's not usually necessary to create your own weak references -directly. The low-level machinery used by the weak dictionary implementations -is exposed by the :mod:`weakref` module for the benefit of advanced uses. +:class:`finalize` provides a straight forward way to register a +cleanup function to be called when an object is garbage collected. +This is simpler to use than setting up a callback function on a raw +weak reference. + +Most programs should find that using one of these weak container types +or :class:`finalize` is all they need -- it's not usually necessary to +create your own weak references directly. The low-level machinery is +exposed by the :mod:`weakref` module for the benefit of advanced uses. Not all objects can be weakly referenced; those objects which can include class instances, functions written in Python (but not in C), instance methods, sets, @@ -111,6 +116,24 @@ Extension types can easily be made to support weak references; see This is a subclassable type rather than a factory function. + .. attribute:: __callback__ + + This read-only attribute returns the callback currently associated to the + weakref. If there is no callback or if the referent of the weakref is + no longer alive then this attribute will have value ``None``. + + .. note:: + + Like :meth:`__del__` methods, weak reference callbacks can be + called during interpreter shutdown when module globals have been + overwritten with :const:`None`. This can make writing robust + weak reference callbacks a challenge. Callbacks registered + using :class:`finalize` do not have to worry about this issue + because they will not be run after module teardown has begun. + + .. versionchanged:: 3.4 + Added the :attr:`__callback__` attribute. + .. function:: proxy(object[, callback]) @@ -192,6 +215,95 @@ These method have the same issues as the and :meth:`keyrefs` method of discarded when no strong reference to it exists any more. +.. class:: WeakMethod(method) + + A custom :class:`ref` subclass which simulates a weak reference to a bound + method (i.e., a method defined on a class and looked up on an instance). + Since a bound method is ephemeral, a standard weak reference cannot keep + hold of it. :class:`WeakMethod` has special code to recreate the bound + method until either the object or the original function dies:: + + >>> class C: + ... def method(self): + ... print("method called!") + ... + >>> c = C() + >>> r = weakref.ref(c.method) + >>> r() + >>> r = weakref.WeakMethod(c.method) + >>> r() + <bound method C.method of <__main__.C object at 0x7fc859830220>> + >>> r()() + method called! + >>> del c + >>> gc.collect() + 0 + >>> r() + >>> + + .. versionadded:: 3.4 + +.. class:: finalize(obj, func, *args, **kwargs) + + Return a callable finalizer object which will be called when *obj* + is garbage collected. A finalizer is *alive* until it is called + (either explicitly or at garbage collection), and after that it is + *dead*. Calling a live finalizer returns the result of evaluating + ``func(*arg, **kwargs)``, whereas calling a dead finalizer returns + :const:`None`. + + Exceptions raised by finalizer callbacks during garbage collection + will be shown on the standard error output, but cannot be + propagated. They are handled in the same way as exceptions raised + from an object's :meth:`__del__` method or a weak reference's + callback. + + When the program exits, each remaining live finalizer is called + unless its :attr:`atexit` attribute has been set to false. They + are called in reverse order of creation. + + A finalizer will never invoke its callback during the later part of + the interpreter shutdown when module globals are liable to have + been replaced by :const:`None`. + + .. method:: __call__() + + If *self* is alive then mark it as dead and return the result of + calling ``func(*args, **kwargs)``. If *self* is dead then return + :const:`None`. + + .. method:: detach() + + If *self* is alive then mark it as dead and return the tuple + ``(obj, func, args, kwargs)``. If *self* is dead then return + :const:`None`. + + .. method:: peek() + + If *self* is alive then return the tuple ``(obj, func, args, + kwargs)``. If *self* is dead then return :const:`None`. + + .. attribute:: alive + + Property which is true if the finalizer is alive, false otherwise. + + .. attribute:: atexit + + A writable boolean property which by default is true. When the + program exits, it calls all remaining live finalizers for which + :attr:`.atexit` is true. They are called in reverse order of + creation. + + .. note:: + + It is important to ensure that *func*, *args* and *kwargs* do + not own any references to *obj*, either directly or indirectly, + since otherwise *obj* will never be garbage collected. In + particular, *func* should not be a bound method of *obj*. + + .. versionadded:: 3.4 + + .. data:: ReferenceType The type object for weak references objects. @@ -232,8 +344,9 @@ These method have the same issues as the and :meth:`keyrefs` method of Weak Reference Objects ---------------------- -Weak reference objects have no attributes or methods, but do allow the referent -to be obtained, if it still exists, by calling it: +Weak reference objects have no methods and no attributes besides +:attr:`ref.__callback__`. A weak reference object allows the referent to be +obtained, if it still exists, by calling it: >>> import weakref >>> class Object: @@ -326,3 +439,125 @@ objects can still be retrieved by ID if they do. def id2obj(oid): return _id2obj_dict[oid] + +.. _finalize-examples: + +Finalizer Objects +----------------- + +Often one uses :class:`finalize` to register a callback without +bothering to keep the returned finalizer object. For instance + + >>> import weakref + >>> class Object: + ... pass + ... + >>> kenny = Object() + >>> weakref.finalize(kenny, print, "You killed Kenny!") #doctest:+ELLIPSIS + <finalize object at ...; for 'Object' at ...> + >>> del kenny + You killed Kenny! + +The finalizer can be called directly as well. However the finalizer +will invoke the callback at most once. + + >>> def callback(x, y, z): + ... print("CALLBACK") + ... return x + y + z + ... + >>> obj = Object() + >>> f = weakref.finalize(obj, callback, 1, 2, z=3) + >>> assert f.alive + >>> assert f() == 6 + CALLBACK + >>> assert not f.alive + >>> f() # callback not called because finalizer dead + >>> del obj # callback not called because finalizer dead + +You can unregister a finalizer using its :meth:`~finalize.detach` +method. This kills the finalizer and returns the arguments passed to +the constructor when it was created. + + >>> obj = Object() + >>> f = weakref.finalize(obj, callback, 1, 2, z=3) + >>> f.detach() #doctest:+ELLIPSIS + (<__main__.Object object ...>, <function callback ...>, (1, 2), {'z': 3}) + >>> newobj, func, args, kwargs = _ + >>> assert not f.alive + >>> assert newobj is obj + >>> assert func(*args, **kwargs) == 6 + CALLBACK + +Unless you set the :attr:`~finalize.atexit` attribute to +:const:`False`, a finalizer will be called when the program exit if it +is still alive. For instance + + >>> obj = Object() + >>> weakref.finalize(obj, print, "obj dead or exiting") #doctest:+ELLIPSIS + <finalize object at ...; for 'Object' at ...> + >>> exit() #doctest:+SKIP + obj dead or exiting + + +Comparing finalizers with :meth:`__del__` methods +------------------------------------------------- + +Suppose we want to create a class whose instances represent temporary +directories. The directories should be deleted with their contents +when the first of the following events occurs: + +* the object is garbage collected, +* the object's :meth:`remove` method is called, or +* the program exits. + +We might try to implement the class using a :meth:`__del__` method as +follows:: + + class TempDir: + def __init__(self): + self.name = tempfile.mkdtemp() + + def remove(self): + if self.name is not None: + shutil.rmtree(self.name) + self.name = None + + @property + def removed(self): + return self.name is None + + def __del__(self): + self.remove() + +This solution has a serious problem: the :meth:`__del__` method may be +called at shutdown after the :mod:`shutil` module has been cleaned up, +in which case :attr:`shutil.rmtree` will have been replaced by :const:`None`. +This will cause the :meth:`__del__` method to fail and the directory +will not be removed. + +Using finalizers we can avoid this problem:: + + class TempDir: + def __init__(self): + self.name = tempfile.mkdtemp() + self._finalizer = weakref.finalize(self, shutil.rmtree, self.name) + + def remove(self): + self._finalizer() + + @property + def removed(self): + return not self._finalizer.alive + +Defined like this, even if a :class:`TempDir` object is part of a +reference cycle, that reference cycle can still be garbage collected. +If the object never gets garbage collected the finalizer will still be +called at exit. + +.. note:: + + If you create a finalizer object in a daemonic thread just as the + the program exits then there is the possibility that the finalizer + does not get called at exit. However, in a daemonic thread + :func:`atexit.register`, ``try: ... finally: ...`` and ``with: ...`` + do not guarantee that cleanup occurs either. diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index d0b59ef..8563971 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -105,6 +105,38 @@ Children are nested, and we can access specific child nodes by index:: >>> root[0][1].text '2008' +Incremental parsing +^^^^^^^^^^^^^^^^^^^ + +It's possible to parse XML incrementally (i.e. not the whole document at once). +The most powerful tool for doing this is :class:`IncrementalParser`. It does +not require a blocking read to obtain the XML data, and is instead fed with +data incrementally with :meth:`IncrementalParser.data_received` calls. To get +the parsed XML elements, call :meth:`IncrementalParser.events`. Here's an +example:: + + >>> incparser = ET.IncrementalParser(['start', 'end']) + >>> incparser.data_received('<mytag>sometext') + >>> list(incparser.events()) + [('start', <Element 'mytag' at 0x7fba3f2a8688>)] + >>> incparser.data_received(' more text</mytag>') + >>> for event, elem in incparser.events(): + ... print(event) + ... print(elem.tag, 'text=', elem.text) + ... + end + mytag text= sometext more text + +The obvious use case is applications that operate in an asynchronous fashion +where the XML data is being received from a socket or read incrementally from +some storage device. In such cases, blocking reads are unacceptable. + +Because it's so flexible, :class:`IncrementalParser` can be inconvenient +to use for simpler use-cases. If you don't mind your application blocking on +reading XML data but would still like to have incremental parsing capabilities, +take a look at :func:`iterparse`. It can be useful when you're reading a large +XML document and don't want to hold it wholly in memory. + Finding interesting elements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -379,7 +411,7 @@ Functions Parses an XML section into an element tree incrementally, and reports what's going on to the user. *source* is a filename or :term:`file object` - containing XML data. *events* is a list of events to report back. The + containing XML data. *events* is a sequence of events to report back. The supported events are the strings ``"start"``, ``"end"``, ``"start-ns"`` and ``"end-ns"`` (the "ns" events are used to get detailed namespace information). If *events* is omitted, only ``"end"`` events are reported. @@ -388,6 +420,11 @@ Functions :class:`TreeBuilder` as a target. Returns an :term:`iterator` providing ``(event, elem)`` pairs. + Note that while :func:`iterparse` builds the tree incrementally, it issues + blocking reads on *source* (or the file it names). As such, it's unsuitable + for asynchronous applications where blocking reads can't be made. For fully + asynchronous parsing, see :class:`IncrementalParser`. + .. note:: :func:`iterparse` only guarantees that it has seen the ">" @@ -398,7 +435,6 @@ Functions If you need a fully populated element, look for "end" events instead. - .. function:: parse(source, parser=None) Parses an XML section into an element tree. *source* is a filename or file @@ -438,29 +474,39 @@ Functions arguments. Returns an element instance. -.. function:: tostring(element, encoding="us-ascii", method="xml") +.. function:: tostring(element, encoding="us-ascii", method="xml", *, \ + short_empty_elements=True) Generates a string representation of an XML element, including all subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to generate a Unicode string (otherwise, a bytestring is generated). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`. Returns an (optionally) encoded string containing the XML data. + .. versionadded:: 3.4 + The *short_empty_elements* parameter. -.. function:: tostringlist(element, encoding="us-ascii", method="xml") + +.. function:: tostringlist(element, encoding="us-ascii", method="xml", *, \ + short_empty_elements=True) Generates a string representation of an XML element, including all subelements. *element* is an :class:`Element` instance. *encoding* [1]_ is the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to generate a Unicode string (otherwise, a bytestring is generated). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + *short_empty_elements* has the same meaning as in :meth:`ElementTree.write`. Returns a list of (optionally) encoded strings containing the XML data. It does not guarantee any specific sequence, except that ``"".join(tostringlist(element)) == tostring(element)``. .. versionadded:: 3.2 + .. versionadded:: 3.4 + The *short_empty_elements* parameter. + .. function:: XML(text, parser=None) @@ -752,7 +798,8 @@ ElementTree Objects .. method:: write(file, encoding="us-ascii", xml_declaration=None, \ - default_namespace=None, method="xml") + default_namespace=None, method="xml", *, \ + short_empty_elements=True) Writes the element tree to a file, as XML. *file* is a file name, or a :term:`file object` opened for writing. *encoding* [1]_ is the output @@ -763,6 +810,10 @@ ElementTree Objects *default_namespace* sets the default XML namespace (for "xmlns"). *method* is either ``"xml"``, ``"html"`` or ``"text"`` (default is ``"xml"``). + The keyword-only *short_empty_elements* parameter controls the formatting + of elements that contain no content. If *True* (the default), they are + emitted as a single self-closed tag, otherwise they are emitted as a pair + of start/end tags. The output is either a string (:class:`str`) or binary (:class:`bytes`). This is controlled by the *encoding* argument. If *encoding* is @@ -771,6 +822,9 @@ ElementTree Objects :term:`file object`; make sure you do not try to write a string to a binary stream and vice versa. + .. versionadded:: 3.4 + The *short_empty_elements* parameter. + This is the XML file that is going to be manipulated:: @@ -816,6 +870,49 @@ QName Objects :class:`QName` instances are opaque. +IncrementalParser Objects +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: IncrementalParser(events=None, parser=None) + + An incremental, event-driven parser suitable for non-blocking applications. + *events* is a sequence of events to report back. The supported events are + the strings ``"start"``, ``"end"``, ``"start-ns"`` and ``"end-ns"`` (the "ns" + events are used to get detailed namespace information). If *events* is + omitted, only ``"end"`` events are reported. *parser* is an optional + parser instance. If not given, the standard :class:`XMLParser` parser is + used. *parser* can only use the default :class:`TreeBuilder` as a target. + + .. method:: data_received(data) + + Feed the given bytes data to the incremental parser. + + .. method:: eof_received() + + Signal the incremental parser that the data stream is terminated. + + .. method:: events() + + Iterate over the events which have been encountered in the data fed + to the parser. This method yields ``(event, elem)`` pairs, where + *event* is a string representing the type of event (e.g. ``"end"``) + and *elem* is the encountered :class:`Element` object. Events + provided in a previous call to :meth:`events` will not be yielded + again. + + .. note:: + + :class:`IncrementalParser` only guarantees that it has seen the ">" + character of a starting tag when it emits a "start" event, so the + attributes are defined, but the contents of the text and tail attributes + are undefined at that point. The same applies to the element children; + they may or may not be present. + + If you need a fully populated element, look for "end" events instead. + + .. versionadded:: 3.4 + + .. _elementtree-treebuilder-objects: TreeBuilder Objects diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index 75e8fd5..7122120 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -144,7 +144,7 @@ ZipFile Objects and should be :const:`ZIP_STORED`, :const:`ZIP_DEFLATED`, :const:`ZIP_BZIP2` or :const:`ZIP_LZMA`; unrecognized values will cause :exc:`RuntimeError` to be raised. If :const:`ZIP_DEFLATED`, - :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` is specified but the corresponded module + :const:`ZIP_BZIP2` or :const:`ZIP_LZMA` is specified but the corresponding module (:mod:`zlib`, :mod:`bz2` or :mod:`lzma`) is not available, :exc:`RuntimeError` is also raised. The default is :const:`ZIP_STORED`. If *allowZip64* is ``True`` zipfile will create ZIP files that use the ZIP64 extensions when @@ -265,10 +265,8 @@ ZipFile Objects Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of *path*, e.g. members that have absolute filenames starting with ``"/"`` or filenames with two - dots ``".."``. - - .. versionchanged:: 3.3.1 - The zipfile module attempts to prevent that. See :meth:`extract` note. + dots ``".."``. This module attempts to prevent that. + See :meth:`extract` note. .. method:: ZipFile.printdir() |