Mailman 3 October 2014 - Python-checkins

cpython (3.4): Closes #22771: "verbose" is unused; deprecate it.
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/335ff0c6d879 changeset: 93317:335ff0c6d879 branch: 3.4 parent: 93312:53048571de47 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:54:06 2014 +0100 summary: Closes #22771: "verbose" is unused; deprecate it. files: Doc/library/shutil.rst | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -458,7 +458,7 @@ *logger* must be an object compatible with :pep:`282`, usually an instance of :class:`logging.Logger`. - The *verbose* argument is currently unused. + The *verbose* argument is unused and deprecated. .. function:: get_archive_formats() -- Repository URL: https://hg.python.org/cpython

1 0

cpython (merge 3.4 -> default): merge with 3.4
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/548e57e58086 changeset: 93318:548e57e58086 parent: 93313:187a14b58a4c parent: 93317:335ff0c6d879 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:54:10 2014 +0100 summary: merge with 3.4 files: Doc/library/shutil.rst | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -491,7 +491,7 @@ *logger* must be an object compatible with :pep:`282`, usually an instance of :class:`logging.Logger`. - The *verbose* argument is currently unused. + The *verbose* argument is unused and deprecated. .. versionchanged:: 3.5 Added support for the *xztar* format. -- Repository URL: https://hg.python.org/cpython

1 0

cpython (2.7): #22613: document Cmd.cmdqueue (thanks Jacques Ducasse)
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/60c6dc1b316f changeset: 93314:60c6dc1b316f branch: 2.7 parent: 93305:0f6dd5365370 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:25:38 2014 +0100 summary: #22613: document Cmd.cmdqueue (thanks Jacques Ducasse) files: Doc/library/cmd.rst | 9 ++++++++- 1 files changed, 8 insertions(+), 1 deletions(-) diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -151,9 +151,9 @@ Hook method executed once when :meth:`cmdloop` is about to return. This method is a stub in :class:`Cmd`; it exists to be overridden by subclasses. + Instances of :class:`Cmd` subclasses have some public instance variables: - .. attribute:: Cmd.prompt The prompt issued to solicit input. @@ -169,6 +169,13 @@ The last nonempty command prefix seen. +.. attribute:: Cmd.cmdqueue + + A list of queued input lines. The cmdqueue list is checked in + :meth:`cmdloop` when new input is needed; if it is nonempty, its elements + will be processed in order, as if entered at the prompt. + + .. attribute:: Cmd.intro A string to issue as an intro or banner. May be overridden by giving the -- Repository URL: https://hg.python.org/cpython

1 0

cpython (2.7): #22613: minor other fixes in library docs (thanks Jacques Ducasse)
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/d3fd218ef2cf changeset: 93315:d3fd218ef2cf branch: 2.7 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:25:48 2014 +0100 summary: #22613: minor other fixes in library docs (thanks Jacques Ducasse) files: Doc/library/ctypes.rst | 7 +------ Doc/library/pydoc.rst | 7 +++++++ Doc/library/tempfile.rst | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1909,7 +1909,7 @@ .. function:: find_msvcrt() :module: ctypes.util - Windows only: return the filename of the VC runtype library used by Python, + Windows only: return the filename of the VC runtime library used by Python, and by the extension modules. If the name of the library cannot be determined, ``None`` is returned. @@ -2446,11 +2446,6 @@ and so on). Later assignments to the :attr:`_fields_` class variable will raise an AttributeError. - Structure and union subclass constructors accept both positional and named - arguments. Positional arguments are used to initialize the fields in the - same order as they appear in the :attr:`_fields_` definition, named - arguments are used to initialize the fields with the corresponding name. - It is possible to defined sub-subclasses of structure types, they inherit the fields of the base class plus the :attr:`_fields_` defined in the sub-subclass, if any. diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -22,6 +22,13 @@ modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files. +For modules, classes, functions and methods, the displayed documentation is +derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object, +and recursively of its documentable members. If there is no docstring, +:mod:`pydoc` tries to obtain a description from the block of comment lines just +above the definition of the class, function or method in the source file, or at +the top of the module (see :func:`inspect.getcomments`). + The built-in function :func:`help` invokes the online help system in the interactive interpreter, which uses :mod:`pydoc` to generate its documentation as text on the console. The same text documentation can also be viewed from diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -185,7 +185,7 @@ >>> os.path.exists(f.name) False -The module uses two global variables that tell it how to construct a +The module uses a global variable that tell it how to construct a temporary name. They are initialized at the first call to any of the functions above. The caller may change them, but this is discouraged; use the appropriate function arguments, instead. -- Repository URL: https://hg.python.org/cpython

1 0

cpython (2.7): #22613: fix several factual errors in builtin docs (thanks Jacques Ducasse)
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/9e57654dfdcc changeset: 93316:9e57654dfdcc branch: 2.7 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 09:41:46 2014 +0100 summary: #22613: fix several factual errors in builtin docs (thanks Jacques Ducasse) files: Doc/library/functions.rst | 5 ++++- Doc/library/stdtypes.rst | 8 +++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -218,7 +218,7 @@ The optional arguments *flags* and *dont_inherit* control which future statements (see :pep:`236`) affect the compilation of *source*. If neither is present (or both are zero) the code is compiled with those future - statements that are in effect in the code that is calling compile. If the + statements that are in effect in the code that is calling :func:`compile`. If the *flags* argument is given and *dont_inherit* is not (or is zero) then the future statements specified by the *flags* argument are used in addition to those that would be used anyway. If *dont_inherit* is a non-zero integer then @@ -233,6 +233,9 @@ This function raises :exc:`SyntaxError` if the compiled source is invalid, and :exc:`TypeError` if the source contains null bytes. + If you want to parse Python code into its AST representation, see + :func:`ast.parse`. + .. note:: When compiling a string with multi-line code in ``'single'`` or diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -433,8 +433,7 @@ operations and higher than the comparisons; the unary operation ``~`` has the same priority as the other unary numeric operations (``+`` and ``-``). -This table lists the bitwise operations sorted in ascending priority -(operations in the same box have the same priority): +This table lists the bitwise operations sorted in ascending priority: +------------+--------------------------------+----------+ | Operation | Result | Notes | @@ -722,9 +721,8 @@ ``*`` operations have the same priority as the corresponding numeric operations. [3]_ Additional methods are provided for :ref:`typesseq-mutable`. -This table lists the sequence operations sorted in ascending priority -(operations in the same box have the same priority). In the table, *s* and *t* -are sequences of the same type; *n*, *i* and *j* are integers: +This table lists the sequence operations sorted in ascending priority. +In the table, *s* and *t* are sequences of the same type; *n*, *i* and *j* are integers: +------------------+--------------------------------+----------+ | Operation | Result | Notes | -- Repository URL: https://hg.python.org/cpython

1 0

cpython (3.4): #22613: explain what "buffer" is in the struct documentation (thanks Jacques
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/5faee3db42a7 changeset: 93307:5faee3db42a7 branch: 3.4 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 09:46:41 2014 +0100 summary: #22613: explain what "buffer" is in the struct documentation (thanks Jacques Ducasse) files: Doc/library/struct.rst | 10 +++++++++- 1 files changed, 9 insertions(+), 1 deletions(-) diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -24,6 +24,14 @@ or omit implicit pad bytes, use ``standard`` size and alignment instead of ``native`` size and alignment: see :ref:`struct-alignment` for details. +Several :mod:`struct` functions (and methods of :class:`Struct`) take a *buffer* +argument. This refers to objects that implement the :ref:`bufferobjects` and +provide either a readable or read-writable buffer. The most common types used +for that purpose are :class:`bytes` and :class:`bytearray`, but many other types +that can be viewed as an array of bytes implement the buffer protocol, so that +they can be read/filled without additional copying from a :class:`bytes` object. + + Functions and Exceptions ------------------------ @@ -47,7 +55,7 @@ Pack the values *v1*, *v2*, ... according to the format string *fmt* and write the packed bytes into the writable buffer *buffer* starting at - position *offset*. Note that *offset* is a required argument. + position *offset*. Note that *offset* is a required argument. .. function:: unpack(fmt, buffer) -- Repository URL: https://hg.python.org/cpython

1 0

cpython (3.4): #22613: fix several factual errors in builtin docs (thanks Jacques Ducasse)
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/f72271f05ea4 changeset: 93306:f72271f05ea4 branch: 3.4 parent: 93303:253b97bf87d4 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 09:41:46 2014 +0100 summary: #22613: fix several factual errors in builtin docs (thanks Jacques Ducasse) files: Doc/library/exceptions.rst | 3 ++- Doc/library/functions.rst | 7 +++++-- Doc/library/stdtypes.rst | 21 ++++++++++----------- 3 files changed, 17 insertions(+), 14 deletions(-) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -34,7 +34,8 @@ information on defining exceptions is available in the Python Tutorial under :ref:`tut-userexceptions`. -When raising (or re-raising) an exception in an :keyword:`except` clause +When raising (or re-raising) an exception in an :keyword:`except` or +:keyword:`finally` clause :attr:`__context__` is automatically set to the last exception caught; if the new exception is not handled the traceback that is eventually displayed will include the originating exception(s) and the final exception. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -210,7 +210,7 @@ The optional arguments *flags* and *dont_inherit* control which future statements (see :pep:`236`) affect the compilation of *source*. If neither is present (or both are zero) the code is compiled with those future - statements that are in effect in the code that is calling compile. If the + statements that are in effect in the code that is calling :func:`compile`. If the *flags* argument is given and *dont_inherit* is not (or is zero) then the future statements specified by the *flags* argument are used in addition to those that would be used anyway. If *dont_inherit* is a non-zero integer then @@ -231,6 +231,9 @@ This function raises :exc:`SyntaxError` if the compiled source is invalid, and :exc:`TypeError` if the source contains null bytes. + If you want to parse Python code into its AST representation, see + :func:`ast.parse`. + .. note:: When compiling a string with multi-line code in ``'single'`` or @@ -539,7 +542,7 @@ effect as calling :func:`str(value) <str>`. A call to ``format(value, format_spec)`` is translated to - ``type(value).__format__(format_spec)`` which bypasses the instance + ``type(value).__format__(value, format_spec)`` which bypasses the instance dictionary when searching for the value's :meth:`__format__` method. A :exc:`TypeError` exception is raised if the method search reaches :mod:`object` and the *format_spec* is non-empty, or if either the diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -269,8 +269,8 @@ :func:`complex` can be used to produce numbers of a specific type. All numeric types (except complex) support the following operations, sorted by -ascending priority (operations in the same box have the same priority; all -numeric operations have a higher priority than comparison operations): +ascending priority (all numeric operations have a higher priority than +comparison operations): +---------------------+---------------------------------+---------+--------------------+ | Operation | Result | Notes | Full documentation | @@ -404,8 +404,7 @@ operations and higher than the comparisons; the unary operation ``~`` has the same priority as the other unary numeric operations (``+`` and ``-``). -This table lists the bitwise operations sorted in ascending priority -(operations in the same box have the same priority): +This table lists the bitwise operations sorted in ascending priority: +------------+--------------------------------+----------+ | Operation | Result | Notes | @@ -444,7 +443,7 @@ ----------------------------------- The int type implements the :class:`numbers.Integral` :term:`abstract base -class`. In addition, it provides one more method: +class`. In addition, it provides a few more methods: .. method:: int.bit_length() @@ -820,10 +819,10 @@ provided to make it easier to correctly implement these operations on custom sequence types. -This table lists the sequence operations sorted in ascending priority -(operations in the same box have the same priority). In the table, *s* and *t* -are sequences of the same type, *n*, *i*, *j* and *k* are integers and *x* is -an arbitrary object that meets any type and value restrictions imposed by *s*. +This table lists the sequence operations sorted in ascending priority. In the +table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are +integers and *x* is an arbitrary object that meets any type and value +restrictions imposed by *s*. The ``in`` and ``not in`` operations have the same priorities as the comparison operations. The ``+`` (concatenation) and ``*`` (repetition) @@ -4006,8 +4005,8 @@ The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows - context management code (such as ``contextlib.nested``) to easily detect whether - or not an :meth:`__exit__` method has actually failed. + context management code to easily detect whether or not an :meth:`__exit__` + method has actually failed. Python defines several context managers to support easy thread synchronisation, prompt closure of files or other objects, and simpler manipulation of the active -- Repository URL: https://hg.python.org/cpython

1 0

cpython (3.4): #22613: remaining corrections in extending/reference docs (thanks Jacques
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/53048571de47 changeset: 93312:53048571de47 branch: 3.4 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:38:49 2014 +0100 summary: #22613: remaining corrections in extending/reference docs (thanks Jacques Ducasse) files: Doc/c-api/arg.rst | 9 +- Doc/extending/extending.rst | 7 +- Doc/reference/datamodel.rst | 12 ++- Doc/reference/executionmodel.rst | 5 +- Doc/reference/expressions.rst | 4 +- Doc/reference/lexical_analysis.rst | 38 +++++++------- Doc/reference/simple_stmts.rst | 11 +-- Doc/reference/toplevel_components.rst | 12 +---- 8 files changed, 44 insertions(+), 54 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -429,10 +429,11 @@ Function used to deconstruct the argument lists of "old-style" functions --- these are functions which use the :const:`METH_OLDARGS` parameter parsing - method. This is not recommended for use in parameter parsing in new code, and - most code in the standard interpreter has been modified to no longer use this - for that purpose. It does remain a convenient way to decompose other tuples, - however, and may continue to be used for that purpose. + method, which has been removed in Python 3. This is not recommended for use + in parameter parsing in new code, and most code in the standard interpreter + has been modified to no longer use this for that purpose. It does remain a + convenient way to decompose other tuples, however, and may continue to be + used for that purpose. .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -857,11 +857,8 @@ from the objects in the cycle, even though there are no further references to the cycle itself. -The cycle detector is able to detect garbage cycles and can reclaim them so long -as there are no finalizers implemented in Python (:meth:`__del__` methods). -When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module). -The :mod:`gc` module also exposes a way to run the detector (the +The cycle detector is able to detect garbage cycles and can reclaim them. +The :mod:`gc` module exposes a way to run the detector (the :func:`~gc.collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle detector is considered an optional component; though it is included by default, diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1133,8 +1133,10 @@ reference to the object on the stack frame that raised an unhandled exception in interactive mode (the traceback stored in ``sys.last_traceback`` keeps the stack frame alive). The first situation - can only be remedied by explicitly breaking the cycles; the latter two - situations can be resolved by storing ``None`` in ``sys.last_traceback``. + can only be remedied by explicitly breaking the cycles; the second can be + resolved by freeing the reference to the traceback object when it is no + longer useful, and the third can be resolved by storing ``None`` in + ``sys.last_traceback``. Circular references which are garbage are detected and cleaned up when the cyclic garbage collector is enabled (it's on by default). Refer to the documentation for the :mod:`gc` module for more information about this @@ -1556,9 +1558,9 @@ .. data:: object.__slots__ This class variable can be assigned a string, iterable, or sequence of - strings with variable names used by instances. If defined in a - class, *__slots__* reserves space for the declared variables and prevents the - automatic creation of *__dict__* and *__weakref__* for each instance. + strings with variable names used by instances. *__slots__* reserves space + for the declared variables and prevents the automatic creation of *__dict__* + and *__weakref__* for each instance. Notes on using *__slots__* diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -111,8 +111,9 @@ namespace. Names are resolved in the top-level namespace by searching the global namespace, i.e. the namespace of the module containing the code block, and the builtins namespace, the namespace of the module :mod:`builtins`. The -global namespace is searched first. If the name is not found there, the builtins -namespace is searched. The global statement must precede all uses of the name. +global namespace is searched first. If the name is not found there, the +builtins namespace is searched. The :keyword:`global` statement must precede +all uses of the name. .. XXX document "nonlocal" semantics here diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -619,8 +619,8 @@ single: stop (slice object attribute) single: step (slice object attribute) -The semantics for a slicing are as follows. The primary must evaluate to a -mapping object, and it is indexed (using the same :meth:`__getitem__` method as +The semantics for a slicing are as follows. The primary is indexed (using the +same :meth:`__getitem__` method as normal subscription) with a key that is constructed from the slice list, as follows. If the slice list contains at least one comma, the key is a tuple containing the conversion of the slice items; otherwise, the conversion of the diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -443,7 +443,7 @@ may only contain ASCII characters; bytes with a numeric value of 128 or greater must be expressed with escapes. -As of Python 3.3 it is possible again to prefix unicode strings with a +As of Python 3.3 it is possible again to prefix string literals with a ``u`` prefix to simplify maintenance of dual 2.x and 3.x codebases. Both string and bytes literals may optionally be prefixed with a letter ``'r'`` @@ -453,24 +453,24 @@ unicode literals behave differently than Python 3.x's the ``'ur'`` syntax is not supported. - .. versionadded:: 3.3 - The ``'rb'`` prefix of raw bytes literals has been added as a synonym - of ``'br'``. +.. versionadded:: 3.3 + The ``'rb'`` prefix of raw bytes literals has been added as a synonym + of ``'br'``. - .. versionadded:: 3.3 - Support for the unicode legacy literal (``u'value'``) was reintroduced - to simplify the maintenance of dual Python 2.x and 3.x codebases. - See :pep:`414` for more information. +.. versionadded:: 3.3 + Support for the unicode legacy literal (``u'value'``) was reintroduced + to simplify the maintenance of dual Python 2.x and 3.x codebases. + See :pep:`414` for more information. -In triple-quoted strings, unescaped newlines and quotes are allowed (and are -retained), except that three unescaped quotes in a row terminate the string. (A -"quote" is the character used to open the string, i.e. either ``'`` or ``"``.) +In triple-quoted literals, unescaped newlines and quotes are allowed (and are +retained), except that three unescaped quotes in a row terminate the literal. (A +"quote" is the character used to open the literal, i.e. either ``'`` or ``"``.) .. index:: physical line, escape sequence, Standard C, C -Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in strings are -interpreted according to rules similar to those used by Standard C. The -recognized escape sequences are: +Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and +bytes literals are interpreted according to rules similar to those used by +Standard C. The recognized escape sequences are: +-----------------+---------------------------------+-------+ | Escape Sequence | Meaning | Notes | @@ -547,20 +547,20 @@ .. index:: unrecognized escape sequence Unlike Standard C, all unrecognized escape sequences are left in the string -unchanged, i.e., *the backslash is left in the string*. (This behavior is +unchanged, i.e., *the backslash is left in the result*. (This behavior is useful when debugging: if an escape sequence is mistyped, the resulting output is more easily recognized as broken.) It is also important to note that the escape sequences only recognized in string literals fall into the category of unrecognized escapes for bytes literals. -Even in a raw string, string quotes can be escaped with a backslash, but the -backslash remains in the string; for example, ``r"\""`` is a valid string +Even in a raw literal, quotes can be escaped with a backslash, but the +backslash remains in the result; for example, ``r"\""`` is a valid string literal consisting of two characters: a backslash and a double quote; ``r"\"`` is not a valid string literal (even a raw string cannot end in an odd number of -backslashes). Specifically, *a raw string cannot end in a single backslash* +backslashes). Specifically, *a raw literal cannot end in a single backslash* (since the backslash would escape the following quote character). Note also that a single backslash followed by a newline is interpreted as those two -characters as part of the string, *not* as a line continuation. +characters as part of the literal, *not* as a line continuation. .. _string-catenation: diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -548,8 +548,8 @@ RuntimeError: Something bad happened A similar mechanism works implicitly if an exception is raised inside an -exception handler: the previous exception is then attached as the new -exception's :attr:`__context__` attribute:: +exception handler or a :keyword:`finally` clause: the previous exception is then +attached as the new exception's :attr:`__context__` attribute:: >>> try: ... print(1 / 0) @@ -731,10 +731,9 @@ to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). -The :keyword:`from` form with ``*`` may only occur in a module scope. The wild -card form of import --- ``from module import *`` --- is only allowed at the -module level. Attempting to use it in class or function definitions will raise -a :exc:`SyntaxError`. +The wild card form of import --- ``from module import *`` --- is only allowed at +the module level. Attempting to use it in class or function definitions will +raise a :exc:`SyntaxError`. .. index:: single: relative; import diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst --- a/Doc/reference/toplevel_components.rst +++ b/Doc/reference/toplevel_components.rst @@ -97,20 +97,10 @@ ================ .. index:: single: input - .. index:: builtin: eval -There are two forms of expression input. Both ignore leading whitespace. The +:func:`eval` is used for expression input. It ignores leading whitespace. The string argument to :func:`eval` must have the following form: .. productionlist:: eval_input: `expression_list` NEWLINE* - -.. index:: - object: file - single: input; raw - single: readline() (file method) - -Note: to read 'raw' input line without interpretation, you can use the -:meth:`readline` method of file objects, including ``sys.stdin``. - -- Repository URL: https://hg.python.org/cpython

1 0

cpython (merge 3.4 -> default): merge with 3.4
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/187a14b58a4c changeset: 93313:187a14b58a4c parent: 93304:0e8411d268a0 parent: 93312:53048571de47 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:39:29 2014 +0100 summary: merge with 3.4 files: Doc/c-api/arg.rst | 9 +- Doc/extending/extending.rst | 7 +- Doc/library/cmd.rst | 9 +++- Doc/library/collections.abc.rst | 2 +- Doc/library/collections.rst | 5 +- Doc/library/ctypes.rst | 7 +-- Doc/library/exceptions.rst | 3 +- Doc/library/functions.rst | 7 +- Doc/library/inspect.rst | 23 +++++--- Doc/library/pydoc.rst | 7 ++ Doc/library/reprlib.rst | 1 - Doc/library/runpy.rst | 3 - Doc/library/shutil.rst | 16 +++++- Doc/library/stdtypes.rst | 21 +++---- Doc/library/struct.rst | 10 +++- Doc/library/tempfile.rst | 2 +- Doc/library/tracemalloc.rst | 28 +++++----- Doc/library/unittest.mock.rst | 15 +++-- Doc/reference/datamodel.rst | 12 ++- Doc/reference/executionmodel.rst | 5 +- Doc/reference/expressions.rst | 4 +- Doc/reference/lexical_analysis.rst | 38 +++++++------- Doc/reference/simple_stmts.rst | 11 +-- Doc/reference/toplevel_components.rst | 12 +---- 24 files changed, 140 insertions(+), 117 deletions(-) diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -429,10 +429,11 @@ Function used to deconstruct the argument lists of "old-style" functions --- these are functions which use the :const:`METH_OLDARGS` parameter parsing - method. This is not recommended for use in parameter parsing in new code, and - most code in the standard interpreter has been modified to no longer use this - for that purpose. It does remain a convenient way to decompose other tuples, - however, and may continue to be used for that purpose. + method, which has been removed in Python 3. This is not recommended for use + in parameter parsing in new code, and most code in the standard interpreter + has been modified to no longer use this for that purpose. It does remain a + convenient way to decompose other tuples, however, and may continue to be + used for that purpose. .. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...) diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst --- a/Doc/extending/extending.rst +++ b/Doc/extending/extending.rst @@ -867,11 +867,8 @@ from the objects in the cycle, even though there are no further references to the cycle itself. -The cycle detector is able to detect garbage cycles and can reclaim them so long -as there are no finalizers implemented in Python (:meth:`__del__` methods). -When there are such finalizers, the detector exposes the cycles through the -:mod:`gc` module (specifically, the :attr:`~gc.garbage` variable in that module). -The :mod:`gc` module also exposes a way to run the detector (the +The cycle detector is able to detect garbage cycles and can reclaim them. +The :mod:`gc` module exposes a way to run the detector (the :func:`~gc.collect` function), as well as configuration interfaces and the ability to disable the detector at runtime. The cycle detector is considered an optional component; though it is included by default, diff --git a/Doc/library/cmd.rst b/Doc/library/cmd.rst --- a/Doc/library/cmd.rst +++ b/Doc/library/cmd.rst @@ -148,9 +148,9 @@ Hook method executed once when :meth:`cmdloop` is about to return. This method is a stub in :class:`Cmd`; it exists to be overridden by subclasses. + Instances of :class:`Cmd` subclasses have some public instance variables: - .. attribute:: Cmd.prompt The prompt issued to solicit input. @@ -166,6 +166,13 @@ The last nonempty command prefix seen. +.. attribute:: Cmd.cmdqueue + + A list of queued input lines. The cmdqueue list is checked in + :meth:`cmdloop` when new input is needed; if it is nonempty, its elements + will be processed in order, as if entered at the prompt. + + .. attribute:: Cmd.intro A string to issue as an intro or banner. May be overridden by giving the diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -134,7 +134,7 @@ Several of the ABCs are also useful as mixins that make it easier to develop classes supporting container APIs. For example, to write a class supporting -the full :class:`Set` API, it only necessary to supply the three underlying +the full :class:`Set` API, it is only necessary to supply the three underlying abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. The ABC supplies the remaining methods such as :meth:`__and__` and :meth:`isdisjoint`:: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -908,7 +908,7 @@ >>> janes_account = default_account._replace(owner='Jane') Enumerated constants can be implemented with named tuples, but it is simpler -and more efficient to use a simple :class:`~enum.Enum` : +and more efficient to use a simple :class:`~enum.Enum`: >>> Status = namedtuple('Status', 'open pending closed')._make(range(3)) >>> Status.open, Status.pending, Status.closed @@ -917,6 +917,9 @@ >>> class Status(Enum): ... open, pending, closed = range(3) + +.. seealso:: + * `Recipe for named tuple abstract base class with a metaclass mix-in <http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-clas…>`_ by Jan Kaliszewski. Besides providing an :term:`abstract base class` for diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1833,7 +1833,7 @@ .. function:: find_msvcrt() :module: ctypes.util - Windows only: return the filename of the VC runtype library used by Python, + Windows only: return the filename of the VC runtime library used by Python, and by the extension modules. If the name of the library cannot be determined, ``None`` is returned. @@ -2335,11 +2335,6 @@ and so on). Later assignments to the :attr:`_fields_` class variable will raise an AttributeError. - Structure and union subclass constructors accept both positional and named - arguments. Positional arguments are used to initialize the fields in the - same order as they appear in the :attr:`_fields_` definition, named - arguments are used to initialize the fields with the corresponding name. - It is possible to defined sub-subclasses of structure types, they inherit the fields of the base class plus the :attr:`_fields_` defined in the sub-subclass, if any. diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -34,7 +34,8 @@ information on defining exceptions is available in the Python Tutorial under :ref:`tut-userexceptions`. -When raising (or re-raising) an exception in an :keyword:`except` clause +When raising (or re-raising) an exception in an :keyword:`except` or +:keyword:`finally` clause :attr:`__context__` is automatically set to the last exception caught; if the new exception is not handled the traceback that is eventually displayed will include the originating exception(s) and the final exception. diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -211,7 +211,7 @@ The optional arguments *flags* and *dont_inherit* control which future statements (see :pep:`236`) affect the compilation of *source*. If neither is present (or both are zero) the code is compiled with those future - statements that are in effect in the code that is calling compile. If the + statements that are in effect in the code that is calling :func:`compile`. If the *flags* argument is given and *dont_inherit* is not (or is zero) then the future statements specified by the *flags* argument are used in addition to those that would be used anyway. If *dont_inherit* is a non-zero integer then @@ -232,6 +232,9 @@ This function raises :exc:`SyntaxError` if the compiled source is invalid, and :exc:`TypeError` if the source contains null bytes. + If you want to parse Python code into its AST representation, see + :func:`ast.parse`. + .. note:: When compiling a string with multi-line code in ``'single'`` or @@ -540,7 +543,7 @@ effect as calling :func:`str(value) <str>`. A call to ``format(value, format_spec)`` is translated to - ``type(value).__format__(format_spec)`` which bypasses the instance + ``type(value).__format__(value, format_spec)`` which bypasses the instance dictionary when searching for the value's :meth:`__format__` method. A :exc:`TypeError` exception is raised if the method search reaches :mod:`object` and the *format_spec* is non-empty, or if either the diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -786,17 +786,20 @@ :func:`getargspec` or :func:`getfullargspec`. The first seven arguments are (``args``, ``varargs``, ``varkw``, - ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). The - other five arguments are the corresponding optional formatting functions - that are called to turn names and values into strings. The last argument - is an optional function to format the sequence of arguments. For example:: + ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). - >>> from inspect import formatargspec, getfullargspec - >>> def f(a: int, b: float): - ... pass - ... - >>> formatargspec(*getfullargspec(f)) - '(a: int, b: float)' + The other six arguments are functions that are called to turn argument names, + ``*`` argument name, ``**`` argument name, default values, return annotation + and individual annotations into strings, respectively. + + For example: + + >>> from inspect import formatargspec, getfullargspec + >>> def f(a: int, b: float): + ... pass + ... + >>> formatargspec(*getfullargspec(f)) + '(a: int, b: float)' .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue]) diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -20,6 +20,13 @@ modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files. +For modules, classes, functions and methods, the displayed documentation is +derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object, +and recursively of its documentable members. If there is no docstring, +:mod:`pydoc` tries to obtain a description from the block of comment lines just +above the definition of the class, function or method in the source file, or at +the top of the module (see :func:`inspect.getcomments`). + The built-in function :func:`help` invokes the online help system in the interactive interpreter, which uses :mod:`pydoc` to generate its documentation as text on the console. The same text documentation can also be viewed from diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst --- a/Doc/library/reprlib.rst +++ b/Doc/library/reprlib.rst @@ -156,4 +156,3 @@ aRepr = MyRepr() print(aRepr.repr(sys.stdin)) # prints '<stdin>' - diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -127,9 +127,6 @@ supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and ``__package__`` will all be set to :const:`None`. - ``__spec__`` will be set to :const:`None` if the supplied path is a - direct path to a script (as source or as precompiled bytecode). - If the supplied path is a reference to a valid sys.path entry, then ``__spec__`` will be set appropriately for the imported ``__main__`` module (that is, ``__spec__.name`` will always be ``__main__``). diff --git a/Doc/library/shutil.rst b/Doc/library/shutil.rst --- a/Doc/library/shutil.rst +++ b/Doc/library/shutil.rst @@ -482,12 +482,17 @@ *root_dir* and *base_dir* both default to the current directory. + If *dry_run* is true, no archive is created, but the operations that would be + executed are logged to *logger*. + *owner* and *group* are used when creating a tar archive. By default, uses the current owner and group. *logger* must be an object compatible with :pep:`282`, usually an instance of :class:`logging.Logger`. + The *verbose* argument is currently unused. + .. versionchanged:: 3.5 Added support for the *xztar* format. @@ -511,14 +516,19 @@ .. function:: register_archive_format(name, function, [extra_args, [description]]) - Register an archiver for the format *name*. *function* is a callable that - will be used to invoke the archiver. + Register an archiver for the format *name*. + + *function* is the callable that will be used to unpack archives. The callable + will receive the *base_name* of the file to create, followed by the + *base_dir* (which defaults to :data:`os.curdir`) to start archiving from. + Further arguments are passed as keyword arguments: *owner*, *group*, + *dry_run* and *logger* (as passed in :func:`make_archive`). If given, *extra_args* is a sequence of ``(name, value)`` pairs that will be used as extra keywords arguments when the archiver callable is used. *description* is used by :func:`get_archive_formats` which returns the - list of archivers. Defaults to an empty list. + list of archivers. Defaults to an empty string. .. function:: unregister_archive_format(name) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -269,8 +269,8 @@ :func:`complex` can be used to produce numbers of a specific type. All numeric types (except complex) support the following operations, sorted by -ascending priority (operations in the same box have the same priority; all -numeric operations have a higher priority than comparison operations): +ascending priority (all numeric operations have a higher priority than +comparison operations): +---------------------+---------------------------------+---------+--------------------+ | Operation | Result | Notes | Full documentation | @@ -404,8 +404,7 @@ operations and higher than the comparisons; the unary operation ``~`` has the same priority as the other unary numeric operations (``+`` and ``-``). -This table lists the bitwise operations sorted in ascending priority -(operations in the same box have the same priority): +This table lists the bitwise operations sorted in ascending priority: +------------+--------------------------------+----------+ | Operation | Result | Notes | @@ -444,7 +443,7 @@ ----------------------------------- The int type implements the :class:`numbers.Integral` :term:`abstract base -class`. In addition, it provides one more method: +class`. In addition, it provides a few more methods: .. method:: int.bit_length() @@ -820,10 +819,10 @@ provided to make it easier to correctly implement these operations on custom sequence types. -This table lists the sequence operations sorted in ascending priority -(operations in the same box have the same priority). In the table, *s* and *t* -are sequences of the same type, *n*, *i*, *j* and *k* are integers and *x* is -an arbitrary object that meets any type and value restrictions imposed by *s*. +This table lists the sequence operations sorted in ascending priority. In the +table, *s* and *t* are sequences of the same type, *n*, *i*, *j* and *k* are +integers and *x* is an arbitrary object that meets any type and value +restrictions imposed by *s*. The ``in`` and ``not in`` operations have the same priorities as the comparison operations. The ``+`` (concatenation) and ``*`` (repetition) @@ -4006,8 +4005,8 @@ The exception passed in should never be reraised explicitly - instead, this method should return a false value to indicate that the method completed successfully and does not want to suppress the raised exception. This allows - context management code (such as ``contextlib.nested``) to easily detect whether - or not an :meth:`__exit__` method has actually failed. + context management code to easily detect whether or not an :meth:`__exit__` + method has actually failed. Python defines several context managers to support easy thread synchronisation, prompt closure of files or other objects, and simpler manipulation of the active diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -24,6 +24,14 @@ or omit implicit pad bytes, use ``standard`` size and alignment instead of ``native`` size and alignment: see :ref:`struct-alignment` for details. +Several :mod:`struct` functions (and methods of :class:`Struct`) take a *buffer* +argument. This refers to objects that implement the :ref:`bufferobjects` and +provide either a readable or read-writable buffer. The most common types used +for that purpose are :class:`bytes` and :class:`bytearray`, but many other types +that can be viewed as an array of bytes implement the buffer protocol, so that +they can be read/filled without additional copying from a :class:`bytes` object. + + Functions and Exceptions ------------------------ @@ -47,7 +55,7 @@ Pack the values *v1*, *v2*, ... according to the format string *fmt* and write the packed bytes into the writable buffer *buffer* starting at - position *offset*. Note that *offset* is a required argument. + position *offset*. Note that *offset* is a required argument. .. function:: unpack(fmt, buffer) diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -199,7 +199,7 @@ >>> os.path.exists(f.name) False -The module uses two global variables that tell it how to construct a +The module uses a global variable that tell it how to construct a temporary name. They are initialized at the first call to any of the functions above. The caller may change them, but this is discouraged; use the appropriate function arguments, instead. diff --git a/Doc/library/tracemalloc.rst b/Doc/library/tracemalloc.rst --- a/Doc/library/tracemalloc.rst +++ b/Doc/library/tracemalloc.rst @@ -27,10 +27,10 @@ Examples -======== +-------- Display the top 10 ------------------- +^^^^^^^^^^^^^^^^^^ Display the 10 files allocating the most memory:: @@ -70,7 +70,7 @@ Compute differences -------------------- +^^^^^^^^^^^^^^^^^^^ Take two snapshots and display the differences:: @@ -114,7 +114,7 @@ Get the traceback of a memory block ------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Code to display the traceback of the biggest memory block:: @@ -179,7 +179,7 @@ Pretty top ----------- +^^^^^^^^^^ Code to display the 10 lines allocating the most memory with a pretty output, ignoring ``<frozen importlib._bootstrap>`` and ``<unknown>`` files:: @@ -249,10 +249,10 @@ API -=== +--- Functions ---------- +^^^^^^^^^ .. function:: clear_traces() @@ -356,7 +356,7 @@ Filter ------- +^^^^^^ .. class:: Filter(inclusive: bool, filename_pattern: str, lineno: int=None, all_frames: bool=False) @@ -404,7 +404,7 @@ Frame ------ +^^^^^ .. class:: Frame @@ -422,7 +422,7 @@ Snapshot --------- +^^^^^^^^ .. class:: Snapshot @@ -508,7 +508,7 @@ Statistic ---------- +^^^^^^^^^ .. class:: Statistic @@ -533,7 +533,7 @@ StatisticDiff -------------- +^^^^^^^^^^^^^ .. class:: StatisticDiff @@ -572,7 +572,7 @@ Trace ------ +^^^^^ .. class:: Trace @@ -592,7 +592,7 @@ Traceback ---------- +^^^^^^^^^ .. class:: Traceback diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -481,7 +481,7 @@ .. attribute:: side_effect This can either be a function to be called when the mock is called, - or an exception (class or instance) to be raised. + an iterable or an exception (class or instance) to be raised. If you pass in a function it will be called with same arguments as the mock and unless the function returns the :data:`DEFAULT` singleton the @@ -489,6 +489,11 @@ function returns :data:`DEFAULT` then the mock will return its normal value (from the :attr:`return_value`). + If you pass in an iterable, it is used to retrieve an iterator which + must yield a value on every call. This value can either be an exception + instance to be raised, or a value to be returned from the call to the + mock (:data:`DEFAULT` handling is identical to the function case). + An example of a mock that raises an exception (to test exception handling of an API): @@ -506,11 +511,7 @@ >>> mock(), mock(), mock() (3, 2, 1) - The :attr:`side_effect` function is called with the same arguments as the - mock (so it is wise for it to take arbitrary args and keyword - arguments) and whatever it returns is used as the return value for - the call. The exception is if :attr:`side_effect` returns :data:`DEFAULT`, - in which case the normal :attr:`return_value` is used. + Using a callable: >>> mock = Mock(return_value=3) >>> def side_effect(*args, **kwargs): @@ -1031,7 +1032,7 @@ used. A more powerful form of *spec* is *autospec*. If you set ``autospec=True`` - then the mock with be created with a spec from the object being replaced. + then the mock will be created with a spec from the object being replaced. All attributes of the mock will also have the spec of the corresponding attribute of the object being replaced. Methods and functions being mocked will have their arguments checked and will raise a :exc:`TypeError` if they are diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1133,8 +1133,10 @@ reference to the object on the stack frame that raised an unhandled exception in interactive mode (the traceback stored in ``sys.last_traceback`` keeps the stack frame alive). The first situation - can only be remedied by explicitly breaking the cycles; the latter two - situations can be resolved by storing ``None`` in ``sys.last_traceback``. + can only be remedied by explicitly breaking the cycles; the second can be + resolved by freeing the reference to the traceback object when it is no + longer useful, and the third can be resolved by storing ``None`` in + ``sys.last_traceback``. Circular references which are garbage are detected and cleaned up when the cyclic garbage collector is enabled (it's on by default). Refer to the documentation for the :mod:`gc` module for more information about this @@ -1556,9 +1558,9 @@ .. data:: object.__slots__ This class variable can be assigned a string, iterable, or sequence of - strings with variable names used by instances. If defined in a - class, *__slots__* reserves space for the declared variables and prevents the - automatic creation of *__dict__* and *__weakref__* for each instance. + strings with variable names used by instances. *__slots__* reserves space + for the declared variables and prevents the automatic creation of *__dict__* + and *__weakref__* for each instance. Notes on using *__slots__* diff --git a/Doc/reference/executionmodel.rst b/Doc/reference/executionmodel.rst --- a/Doc/reference/executionmodel.rst +++ b/Doc/reference/executionmodel.rst @@ -111,8 +111,9 @@ namespace. Names are resolved in the top-level namespace by searching the global namespace, i.e. the namespace of the module containing the code block, and the builtins namespace, the namespace of the module :mod:`builtins`. The -global namespace is searched first. If the name is not found there, the builtins -namespace is searched. The global statement must precede all uses of the name. +global namespace is searched first. If the name is not found there, the +builtins namespace is searched. The :keyword:`global` statement must precede +all uses of the name. .. XXX document "nonlocal" semantics here diff --git a/Doc/reference/expressions.rst b/Doc/reference/expressions.rst --- a/Doc/reference/expressions.rst +++ b/Doc/reference/expressions.rst @@ -619,8 +619,8 @@ single: stop (slice object attribute) single: step (slice object attribute) -The semantics for a slicing are as follows. The primary must evaluate to a -mapping object, and it is indexed (using the same :meth:`__getitem__` method as +The semantics for a slicing are as follows. The primary is indexed (using the +same :meth:`__getitem__` method as normal subscription) with a key that is constructed from the slice list, as follows. If the slice list contains at least one comma, the key is a tuple containing the conversion of the slice items; otherwise, the conversion of the diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -443,7 +443,7 @@ may only contain ASCII characters; bytes with a numeric value of 128 or greater must be expressed with escapes. -As of Python 3.3 it is possible again to prefix unicode strings with a +As of Python 3.3 it is possible again to prefix string literals with a ``u`` prefix to simplify maintenance of dual 2.x and 3.x codebases. Both string and bytes literals may optionally be prefixed with a letter ``'r'`` @@ -453,24 +453,24 @@ unicode literals behave differently than Python 3.x's the ``'ur'`` syntax is not supported. - .. versionadded:: 3.3 - The ``'rb'`` prefix of raw bytes literals has been added as a synonym - of ``'br'``. +.. versionadded:: 3.3 + The ``'rb'`` prefix of raw bytes literals has been added as a synonym + of ``'br'``. - .. versionadded:: 3.3 - Support for the unicode legacy literal (``u'value'``) was reintroduced - to simplify the maintenance of dual Python 2.x and 3.x codebases. - See :pep:`414` for more information. +.. versionadded:: 3.3 + Support for the unicode legacy literal (``u'value'``) was reintroduced + to simplify the maintenance of dual Python 2.x and 3.x codebases. + See :pep:`414` for more information. -In triple-quoted strings, unescaped newlines and quotes are allowed (and are -retained), except that three unescaped quotes in a row terminate the string. (A -"quote" is the character used to open the string, i.e. either ``'`` or ``"``.) +In triple-quoted literals, unescaped newlines and quotes are allowed (and are +retained), except that three unescaped quotes in a row terminate the literal. (A +"quote" is the character used to open the literal, i.e. either ``'`` or ``"``.) .. index:: physical line, escape sequence, Standard C, C -Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in strings are -interpreted according to rules similar to those used by Standard C. The -recognized escape sequences are: +Unless an ``'r'`` or ``'R'`` prefix is present, escape sequences in string and +bytes literals are interpreted according to rules similar to those used by +Standard C. The recognized escape sequences are: +-----------------+---------------------------------+-------+ | Escape Sequence | Meaning | Notes | @@ -547,20 +547,20 @@ .. index:: unrecognized escape sequence Unlike Standard C, all unrecognized escape sequences are left in the string -unchanged, i.e., *the backslash is left in the string*. (This behavior is +unchanged, i.e., *the backslash is left in the result*. (This behavior is useful when debugging: if an escape sequence is mistyped, the resulting output is more easily recognized as broken.) It is also important to note that the escape sequences only recognized in string literals fall into the category of unrecognized escapes for bytes literals. -Even in a raw string, string quotes can be escaped with a backslash, but the -backslash remains in the string; for example, ``r"\""`` is a valid string +Even in a raw literal, quotes can be escaped with a backslash, but the +backslash remains in the result; for example, ``r"\""`` is a valid string literal consisting of two characters: a backslash and a double quote; ``r"\"`` is not a valid string literal (even a raw string cannot end in an odd number of -backslashes). Specifically, *a raw string cannot end in a single backslash* +backslashes). Specifically, *a raw literal cannot end in a single backslash* (since the backslash would escape the following quote character). Note also that a single backslash followed by a newline is interpreted as those two -characters as part of the string, *not* as a line continuation. +characters as part of the literal, *not* as a line continuation. .. _string-catenation: diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -548,8 +548,8 @@ RuntimeError: Something bad happened A similar mechanism works implicitly if an exception is raised inside an -exception handler: the previous exception is then attached as the new -exception's :attr:`__context__` attribute:: +exception handler or a :keyword:`finally` clause: the previous exception is then +attached as the new exception's :attr:`__context__` attribute:: >>> try: ... print(1 / 0) @@ -731,10 +731,9 @@ to avoid accidentally exporting items that are not part of the API (such as library modules which were imported and used within the module). -The :keyword:`from` form with ``*`` may only occur in a module scope. The wild -card form of import --- ``from module import *`` --- is only allowed at the -module level. Attempting to use it in class or function definitions will raise -a :exc:`SyntaxError`. +The wild card form of import --- ``from module import *`` --- is only allowed at +the module level. Attempting to use it in class or function definitions will +raise a :exc:`SyntaxError`. .. index:: single: relative; import diff --git a/Doc/reference/toplevel_components.rst b/Doc/reference/toplevel_components.rst --- a/Doc/reference/toplevel_components.rst +++ b/Doc/reference/toplevel_components.rst @@ -97,20 +97,10 @@ ================ .. index:: single: input - .. index:: builtin: eval -There are two forms of expression input. Both ignore leading whitespace. The +:func:`eval` is used for expression input. It ignores leading whitespace. The string argument to :func:`eval` must have the following form: .. productionlist:: eval_input: `expression_list` NEWLINE* - -.. index:: - object: file - single: input; raw - single: readline() (file method) - -Note: to read 'raw' input line without interpretation, you can use the -:meth:`readline` method of file objects, including ``sys.stdin``. - -- Repository URL: https://hg.python.org/cpython

1 0

cpython (3.4): #22613: minor other fixes in library docs (thanks Jacques Ducasse)
by georg.brandl Oct. 31, 2014

Oct. 31, 2014

https://hg.python.org/cpython/rev/4089047475c5 changeset: 93311:4089047475c5 branch: 3.4 user: Georg Brandl <georg(a)python.org> date: Fri Oct 31 10:25:48 2014 +0100 summary: #22613: minor other fixes in library docs (thanks Jacques Ducasse) files: Doc/library/collections.abc.rst | 2 +- Doc/library/collections.rst | 5 +++- Doc/library/ctypes.rst | 7 +----- Doc/library/inspect.rst | 23 +++++++++++--------- Doc/library/pydoc.rst | 7 ++++++ Doc/library/reprlib.rst | 1 - Doc/library/runpy.rst | 3 -- Doc/library/tempfile.rst | 2 +- Doc/library/unittest.mock.rst | 15 +++++++------ 9 files changed, 35 insertions(+), 30 deletions(-) diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst +++ b/Doc/library/collections.abc.rst @@ -134,7 +134,7 @@ Several of the ABCs are also useful as mixins that make it easier to develop classes supporting container APIs. For example, to write a class supporting -the full :class:`Set` API, it only necessary to supply the three underlying +the full :class:`Set` API, it is only necessary to supply the three underlying abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. The ABC supplies the remaining methods such as :meth:`__and__` and :meth:`isdisjoint`:: diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -908,7 +908,7 @@ >>> janes_account = default_account._replace(owner='Jane') Enumerated constants can be implemented with named tuples, but it is simpler -and more efficient to use a simple :class:`~enum.Enum` : +and more efficient to use a simple :class:`~enum.Enum`: >>> Status = namedtuple('Status', 'open pending closed')._make(range(3)) >>> Status.open, Status.pending, Status.closed @@ -917,6 +917,9 @@ >>> class Status(Enum): ... open, pending, closed = range(3) + +.. seealso:: + * `Recipe for named tuple abstract base class with a metaclass mix-in <http://code.activestate.com/recipes/577629-namedtupleabc-abstract-base-clas…>`_ by Jan Kaliszewski. Besides providing an :term:`abstract base class` for diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -1833,7 +1833,7 @@ .. function:: find_msvcrt() :module: ctypes.util - Windows only: return the filename of the VC runtype library used by Python, + Windows only: return the filename of the VC runtime library used by Python, and by the extension modules. If the name of the library cannot be determined, ``None`` is returned. @@ -2335,11 +2335,6 @@ and so on). Later assignments to the :attr:`_fields_` class variable will raise an AttributeError. - Structure and union subclass constructors accept both positional and named - arguments. Positional arguments are used to initialize the fields in the - same order as they appear in the :attr:`_fields_` definition, named - arguments are used to initialize the fields with the corresponding name. - It is possible to defined sub-subclasses of structure types, they inherit the fields of the base class plus the :attr:`_fields_` defined in the sub-subclass, if any. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -750,17 +750,20 @@ :func:`getargspec` or :func:`getfullargspec`. The first seven arguments are (``args``, ``varargs``, ``varkw``, - ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). The - other five arguments are the corresponding optional formatting functions - that are called to turn names and values into strings. The last argument - is an optional function to format the sequence of arguments. For example:: + ``defaults``, ``kwonlyargs``, ``kwonlydefaults``, ``annotations``). - >>> from inspect import formatargspec, getfullargspec - >>> def f(a: int, b: float): - ... pass - ... - >>> formatargspec(*getfullargspec(f)) - '(a: int, b: float)' + The other six arguments are functions that are called to turn argument names, + ``*`` argument name, ``**`` argument name, default values, return annotation + and individual annotations into strings, respectively. + + For example: + + >>> from inspect import formatargspec, getfullargspec + >>> def f(a: int, b: float): + ... pass + ... + >>> formatargspec(*getfullargspec(f)) + '(a: int, b: float)' .. function:: formatargvalues(args[, varargs, varkw, locals, formatarg, formatvarargs, formatvarkw, formatvalue]) diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -20,6 +20,13 @@ modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files. +For modules, classes, functions and methods, the displayed documentation is +derived from the docstring (i.e. the :attr:`__doc__` attribute) of the object, +and recursively of its documentable members. If there is no docstring, +:mod:`pydoc` tries to obtain a description from the block of comment lines just +above the definition of the class, function or method in the source file, or at +the top of the module (see :func:`inspect.getcomments`). + The built-in function :func:`help` invokes the online help system in the interactive interpreter, which uses :mod:`pydoc` to generate its documentation as text on the console. The same text documentation can also be viewed from diff --git a/Doc/library/reprlib.rst b/Doc/library/reprlib.rst --- a/Doc/library/reprlib.rst +++ b/Doc/library/reprlib.rst @@ -156,4 +156,3 @@ aRepr = MyRepr() print(aRepr.repr(sys.stdin)) # prints '<stdin>' - diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -127,9 +127,6 @@ supplied path, and ``__spec__``, ``__cached__``, ``__loader__`` and ``__package__`` will all be set to :const:`None`. - ``__spec__`` will be set to :const:`None` if the supplied path is a - direct path to a script (as source or as precompiled bytecode). - If the supplied path is a reference to a valid sys.path entry, then ``__spec__`` will be set appropriately for the imported ``__main__`` module (that is, ``__spec__.name`` will always be ``__main__``). diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -192,7 +192,7 @@ >>> os.path.exists(f.name) False -The module uses two global variables that tell it how to construct a +The module uses a global variable that tell it how to construct a temporary name. They are initialized at the first call to any of the functions above. The caller may change them, but this is discouraged; use the appropriate function arguments, instead. diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst --- a/Doc/library/unittest.mock.rst +++ b/Doc/library/unittest.mock.rst @@ -461,7 +461,7 @@ .. attribute:: side_effect This can either be a function to be called when the mock is called, - or an exception (class or instance) to be raised. + an iterable or an exception (class or instance) to be raised. If you pass in a function it will be called with same arguments as the mock and unless the function returns the :data:`DEFAULT` singleton the @@ -469,6 +469,11 @@ function returns :data:`DEFAULT` then the mock will return its normal value (from the :attr:`return_value`). + If you pass in an iterable, it is used to retrieve an iterator which + must yield a value on every call. This value can either be an exception + instance to be raised, or a value to be returned from the call to the + mock (:data:`DEFAULT` handling is identical to the function case). + An example of a mock that raises an exception (to test exception handling of an API): @@ -486,11 +491,7 @@ >>> mock(), mock(), mock() (3, 2, 1) - The :attr:`side_effect` function is called with the same arguments as the - mock (so it is wise for it to take arbitrary args and keyword - arguments) and whatever it returns is used as the return value for - the call. The exception is if :attr:`side_effect` returns :data:`DEFAULT`, - in which case the normal :attr:`return_value` is used. + Using a callable: >>> mock = Mock(return_value=3) >>> def side_effect(*args, **kwargs): @@ -1011,7 +1012,7 @@ used. A more powerful form of *spec* is *autospec*. If you set ``autospec=True`` - then the mock with be created with a spec from the object being replaced. + then the mock will be created with a spec from the object being replaced. All attributes of the mock will also have the spec of the corresponding attribute of the object being replaced. Methods and functions being mocked will have their arguments checked and will raise a :exc:`TypeError` if they are -- Repository URL: https://hg.python.org/cpython

1 0