diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/c-api/buffer.rst | 8 | ||||
| -rw-r--r-- | Doc/c-api/typeobj.rst | 10 | ||||
| -rw-r--r-- | Doc/extending/newtypes.rst | 6 | ||||
| -rw-r--r-- | Doc/includes/typestruct.h | 16 | ||||
| -rw-r--r-- | Doc/library/_thread.rst | 3 | ||||
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 2 | ||||
| -rw-r--r-- | Doc/library/asyncio-subprocess.rst | 8 | ||||
| -rw-r--r-- | Doc/library/asyncio.rst | 7 | ||||
| -rw-r--r-- | Doc/library/collections.rst | 6 | ||||
| -rw-r--r-- | Doc/library/dis.rst | 4 | ||||
| -rw-r--r-- | Doc/library/html.parser.rst | 2 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 15 | ||||
| -rw-r--r-- | Doc/library/ipaddress.rst | 2 | ||||
| -rw-r--r-- | Doc/library/os.path.rst | 17 | ||||
| -rw-r--r-- | Doc/library/tempfile.rst | 155 | ||||
| -rw-r--r-- | Doc/library/threading.rst | 3 | ||||
| -rw-r--r-- | Doc/library/typing.rst | 97 | ||||
| -rw-r--r-- | Doc/library/unittest.rst | 4 | ||||
| -rw-r--r-- | Doc/library/xml.etree.elementtree.rst | 30 | ||||
| -rw-r--r-- | Doc/tutorial/datastructures.rst | 22 | ||||
| -rw-r--r-- | Doc/using/mac.rst | 5 |
21 files changed, 240 insertions, 182 deletions
diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index 6cb474e80e..46c19d3ca3 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -133,15 +133,15 @@ a buffer, see :c:func:`PyObject_GetBuffer`. called on non-NULL :c:member:`~Py_buffer.format` values. Important exception: If a consumer requests a buffer without the - :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_Buffer.format` will + :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will be set to *NULL*, but :c:member:`~Py_buffer.itemsize` still has the value for the original format. - If :c:member:`~Py_Buffer.shape` is present, the equality + If :c:member:`~Py_buffer.shape` is present, the equality ``product(shape) * itemsize == len`` still holds and the consumer can use :c:member:`~Py_buffer.itemsize` to navigate the buffer. - If :c:member:`~Py_Buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE` + If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE` or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``. @@ -156,7 +156,7 @@ a buffer, see :c:func:`PyObject_GetBuffer`. .. c:member:: int ndim The number of dimensions the memory represents as an n-dimensional array. - If it is 0, :c:member:`~Py_Buffer.buf` points to a single item representing + If it is 0, :c:member:`~Py_buffer.buf` points to a single item representing a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides` and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ed83e82d72..b5113aaef1 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -94,7 +94,7 @@ type objects) *must* have the :attr:`ob_size` field. This field is not inherited by subtypes. -.. c:member:: char* PyTypeObject.tp_name +.. c:member:: const char* PyTypeObject.tp_name Pointer to a NUL-terminated string containing the name of the type. For types that are accessible as module globals, the string should be the full module @@ -372,7 +372,7 @@ type objects) *must* have the :attr:`ob_size` field. inherited individually. -.. c:member:: long PyTypeObject.tp_flags +.. c:member:: unsigned long PyTypeObject.tp_flags This field is a bit mask of various flags. Some flags indicate variant semantics for certain situations; others are used to indicate that certain @@ -472,7 +472,7 @@ type objects) *must* have the :attr:`ob_size` field. .. versionadded:: 3.4 -.. c:member:: char* PyTypeObject.tp_doc +.. c:member:: const char* PyTypeObject.tp_doc An optional pointer to a NUL-terminated C string giving the docstring for this type object. This is exposed as the :attr:`__doc__` attribute on the type and @@ -619,7 +619,7 @@ type objects) *must* have the :attr:`ob_size` field. +----------------+------------+ -.. c:member:: long PyTypeObject.tp_weaklistoffset +.. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset If the instances of this type are weakly referenceable, this field is greater than zero and contains the offset in the instance structure of the weak @@ -786,7 +786,7 @@ type objects) *must* have the :attr:`ob_size` field. .. XXX explain. -.. c:member:: long PyTypeObject.tp_dictoffset +.. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset If the instances of this type have a dictionary containing instance variables, this field is non-zero and contains the offset in the instances of the type of diff --git a/Doc/extending/newtypes.rst b/Doc/extending/newtypes.rst index b7e35f45d1..f60e208e86 100644 --- a/Doc/extending/newtypes.rst +++ b/Doc/extending/newtypes.rst @@ -893,20 +893,20 @@ fields in the right order! It's often easiest to find an example that includes all the fields you need (even if they're initialized to ``0``) and then change the values to suit your new type. :: - char *tp_name; /* For printing */ + const char *tp_name; /* For printing */ The name of the type - as mentioned in the last section, this will appear in various places, almost entirely for diagnostic purposes. Try to choose something that will be helpful in such a situation! :: - int tp_basicsize, tp_itemsize; /* For allocation */ + Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ These fields tell the runtime how much memory to allocate when new objects of this type are created. Python has some built-in support for variable length structures (think: strings, lists) which is where the :c:member:`~PyTypeObject.tp_itemsize` field comes in. This will be dealt with later. :: - char *tp_doc; + const char *tp_doc; Here you can put a string (or its address) that you want returned when the Python script references ``obj.__doc__`` to retrieve the doc string. diff --git a/Doc/includes/typestruct.h b/Doc/includes/typestruct.h index 5c9f8f5d9f..9f47899a19 100644 --- a/Doc/includes/typestruct.h +++ b/Doc/includes/typestruct.h @@ -1,7 +1,7 @@ typedef struct _typeobject { PyObject_VAR_HEAD - char *tp_name; /* For printing, in format "<module>.<name>" */ - int tp_basicsize, tp_itemsize; /* For allocation */ + const char *tp_name; /* For printing, in format "<module>.<name>" */ + Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */ /* Methods to implement standard operations */ @@ -9,7 +9,8 @@ typedef struct _typeobject { printfunc tp_print; getattrfunc tp_getattr; setattrfunc tp_setattr; - PyAsyncMethods *tp_as_async; + PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2) + or tp_reserved (Python 3) */ reprfunc tp_repr; /* Method suites for standard classes */ @@ -30,9 +31,9 @@ typedef struct _typeobject { PyBufferProcs *tp_as_buffer; /* Flags to define presence of optional/expanded features */ - long tp_flags; + unsigned long tp_flags; - char *tp_doc; /* Documentation string */ + const char *tp_doc; /* Documentation string */ /* call function for all accessible objects */ traverseproc tp_traverse; @@ -44,7 +45,7 @@ typedef struct _typeobject { richcmpfunc tp_richcompare; /* weak reference enabler */ - long tp_weaklistoffset; + Py_ssize_t tp_weaklistoffset; /* Iterators */ getiterfunc tp_iter; @@ -58,7 +59,7 @@ typedef struct _typeobject { PyObject *tp_dict; descrgetfunc tp_descr_get; descrsetfunc tp_descr_set; - long tp_dictoffset; + Py_ssize_t tp_dictoffset; initproc tp_init; allocfunc tp_alloc; newfunc tp_new; @@ -69,7 +70,6 @@ typedef struct _typeobject { PyObject *tp_cache; PyObject *tp_subclasses; PyObject *tp_weaklist; - destructor tp_del; /* Type attribute cache version tag. Added in version 2.6 */ diff --git a/Doc/library/_thread.rst b/Doc/library/_thread.rst index a787e2fd4b..7122861c45 100644 --- a/Doc/library/_thread.rst +++ b/Doc/library/_thread.rst @@ -93,7 +93,8 @@ It defines the following constants and functions: Return the thread stack size used when creating new threads. The optional *size* argument specifies the stack size to be used for subsequently created threads, and must be 0 (use platform or configured default) or a positive - integer value of at least 32,768 (32 KiB). If changing the thread stack size is + integer value of at least 32,768 (32 KiB). If *size* is not specified, + 0 is used. If changing the thread stack size is unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB is currently the minimum supported stack size value to guarantee sufficient diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 7d7caa8d15..146c8c9102 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -6,7 +6,7 @@ Base Event Loop =============== The event loop is the central execution device provided by :mod:`asyncio`. -It provides multiple facilities, amongst which: +It provides multiple facilities, including: * Registering, executing and cancelling delayed calls (timeouts). diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 3c9e3cbdb5..c0704cde2c 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -303,7 +303,7 @@ Process .. _asyncio-subprocess-threads: Subprocess and threads -====================== +---------------------- asyncio supports running subprocesses from different threads, but there are limits: @@ -322,10 +322,10 @@ The :class:`asyncio.subprocess.Process` class is not thread safe. Subprocess examples -=================== +------------------- Subprocess using transport and protocol ---------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Example of a subprocess protocol using to get the output of a subprocess and to wait for the subprocess exit. The subprocess is created by the @@ -381,7 +381,7 @@ wait for the subprocess exit. The subprocess is created by the Subprocess using streams ------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^ Example using the :class:`~asyncio.subprocess.Process` class to control the subprocess and the :class:`StreamReader` class to read from the standard diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst index b292ae91e6..9b4d65e5da 100644 --- a/Doc/library/asyncio.rst +++ b/Doc/library/asyncio.rst @@ -4,6 +4,13 @@ .. module:: asyncio :synopsis: Asynchronous I/O, event loop, coroutines and tasks. +.. note:: + + The asyncio package has been included in the standard library on a + :term:`provisional basis <provisional package>`. Backwards incompatible + changes (up to and including removal of the module) may occur if deemed + necessary by the core developers. + .. versionadded:: 3.4 **Source code:** :source:`Lib/asyncio/` diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index f2befe7c08..60e8fe83ef 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -842,10 +842,10 @@ field names, the method and attribute names start with an underscore. .. method:: somenamedtuple._asdict() Return a new :class:`OrderedDict` which maps field names to their corresponding - values. Note, this method is no longer needed now that the same effect can - be achieved by using the built-in :func:`vars` function:: + values:: - >>> vars(p) + >>> p = Point(x=11, y=22) + >>> p._asdict() OrderedDict([('x', 11), ('y', 22)]) .. versionchanged:: 3.1 diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 7a214edcc7..1bcb3a4a07 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -946,8 +946,8 @@ the more significant byte last. Creates a new function object, sets its *__closure__* slot, and pushes it on the stack. TOS is the :term:`qualified name` of the function, TOS1 is the code associated with the function, and TOS2 is the tuple containing cells for - the closure's free variables. The function also has *argc* default - parameters, which are found below the cells. + the closure's free variables. *argc* is interpreted as in ``MAKE_FUNCTION``; + the annotations and defaults are also in the same order below TOS2. .. opcode:: BUILD_SLICE (argc) diff --git a/Doc/library/html.parser.rst b/Doc/library/html.parser.rst index b84c60b708..824995eddc 100644 --- a/Doc/library/html.parser.rst +++ b/Doc/library/html.parser.rst @@ -185,7 +185,7 @@ implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`): The content of Internet Explorer conditional comments (condcoms) will also be sent to this method, so, for ``<!--[if IE 9]>IE9-specific content<![endif]-->``, - this method will receive ``'[if IE 9]>IE-specific content<![endif]'``. + this method will receive ``'[if IE 9]>IE9-specific content<![endif]'``. .. method:: HTMLParser.handle_decl(decl) diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 3b62e7f5b9..d2247e844f 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -178,6 +178,10 @@ attributes: +-----------+-----------------+---------------------------+ | | gi_code | code | +-----------+-----------------+---------------------------+ +| | gi_yieldfrom | object being iterated by | +| | | ``yield from``, or | +| | | ``None`` | ++-----------+-----------------+---------------------------+ | coroutine | __name__ | name | +-----------+-----------------+---------------------------+ | | __qualname__ | qualified name | @@ -191,10 +195,6 @@ attributes: +-----------+-----------------+---------------------------+ | | cr_code | code | +-----------+-----------------+---------------------------+ -| | gi_yieldfrom | object being iterated by | -| | | ``yield from``, or | -| | | ``None`` | -+-----------+-----------------+---------------------------+ | builtin | __doc__ | documentation string | +-----------+-----------------+---------------------------+ | | __name__ | original name of this | @@ -209,9 +209,10 @@ attributes: .. versionchanged:: 3.5 - Add ``__qualname__`` attribute to generators. The ``__name__`` attribute of - generators is now set from the function name, instead of the code name, and - it can now be modified. + Add ``__qualname__`` and ``gi_yieldfrom`` attributes to generators. + + The ``__name__`` attribute of generators is now set from the function + name, instead of the code name, and it can now be modified. .. function:: getmembers(object[, predicate]) diff --git a/Doc/library/ipaddress.rst b/Doc/library/ipaddress.rst index 7b594408c8..90fcc748e7 100644 --- a/Doc/library/ipaddress.rst +++ b/Doc/library/ipaddress.rst @@ -575,7 +575,7 @@ so to avoid duplication they are only documented for :class:`IPv4Network`. single-address network, with the network address being *address* and the mask being ``/128``. - 3. An integer packed into a :class:`bytes` object of length 16, bit-endian. + 3. An integer packed into a :class:`bytes` object of length 16, big-endian. The interpretation is similar to an integer *address*. 4. A two-tuple of an address description and a netmask, where the address diff --git a/Doc/library/os.path.rst b/Doc/library/os.path.rst index e4fe44ed94..a3fe73c152 100644 --- a/Doc/library/os.path.rst +++ b/Doc/library/os.path.rst @@ -82,8 +82,21 @@ the :mod:`glob` module.) Return the longest path prefix (taken character-by-character) that is a prefix of all paths in *list*. If *list* is empty, return the empty string - (``''``). Note that this may return invalid paths because it works a - character at a time. To obtain a valid path, see :func:`commonpath`. + (``''``). + + .. note:: + + This function may return invalid paths because it works a + character at a time. To obtain a valid path, see + :func:`commonpath`. + + :: + + >>> os.path.commonprefix(['/usr/lib', '/usr/local/lib']) + '/usr/l' + + >>> os.path.commonpath(['/usr/lib', '/usr/local/lib']) + '/usr' .. function:: dirname(path) diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst index 0387fb1420..83f994170a 100644 --- a/Doc/library/tempfile.rst +++ b/Doc/library/tempfile.rst @@ -16,16 +16,18 @@ -------------- -This module generates temporary files and directories. It works on all -supported platforms. It provides three new functions, -:func:`NamedTemporaryFile`, :func:`mkstemp`, and :func:`mkdtemp`, which should -eliminate all remaining need to use the insecure :func:`mktemp` function. -Temporary file names created by this module no longer contain the process ID; -instead a string of six random characters is used. - -Also, all the user-callable functions now take additional arguments which -allow direct control over the location and name of temporary files. It is -no longer necessary to use the global *tempdir* variable. +This module creates temporary files and directories. It works on all +supported platforms. :class:`TemporaryFile`, :class:`NamedTemporaryFile`, +:class:`TemporaryDirectory`, and :class:`SpooledTemporaryFile` are high-level +interfaces which provide automatic cleanup and can be used as +context managers. :func:`mkstemp` and +:func:`mkdtemp` are lower-level functions which require manual cleanup. + +All the user-callable functions and constructors take additional arguments which +allow direct control over the location and name of temporary files and +directories. Files names used by this module include a string of +random characters which allows those files to be securely created in +shared temporary directories. To maintain backward compatibility, the argument order is somewhat odd; it is recommended to use keyword arguments for clarity. @@ -34,28 +36,33 @@ The module defines the following user-callable items: .. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None) Return a :term:`file-like object` that can be used as a temporary storage area. - The file is created using :func:`mkstemp`. It will be destroyed as soon + The file is created securely, using the same rules as :func:`mkstemp`. It will be destroyed as soon as it is closed (including an implicit close when the object is garbage - collected). Under Unix, the directory entry for the file is removed + collected). Under Unix, the directory entry for the file is either not created at all or is removed immediately after the file is created. Other platforms do not support this; your code should not rely on a temporary file created using this function having or not having a visible name in the file system. + The resulting object can be used as a context manager (see + :ref:`tempfile-examples`). On completion of the context or + destruction of the file object the temporary file will be removed + from the filesystem. + The *mode* parameter defaults to ``'w+b'`` so that the file created can be read and written without being closed. Binary mode is used so that it behaves consistently on all platforms without regard for the data that is stored. *buffering*, *encoding* and *newline* are interpreted as for :func:`open`. - The *dir*, *prefix* and *suffix* parameters are passed to :func:`mkstemp`. + The *dir*, *prefix* and *suffix* parameters have the same meaning + as with :func:`mkstemp`. The returned object is a true file object on POSIX platforms. On other platforms, it is a file-like object whose :attr:`!file` attribute is the - underlying true file object. This file-like object can be used in a - :keyword:`with` statement, just like a normal file. + underlying true file object. The :py:data:`os.O_TMPFILE` flag is used if it is available and works - (Linux-specific, require Linux kernel 3.11 or later). + (Linux-specific, requires Linux kernel 3.11 or later). .. versionchanged:: 3.5 @@ -101,10 +108,9 @@ The module defines the following user-callable items: .. function:: TemporaryDirectory(suffix='', prefix='tmp', dir=None) - This function creates a temporary directory using :func:`mkdtemp` - (the supplied arguments are passed directly to the underlying function). + This function securely creates a temporary directory using the same rules as :func:`mkdtemp`. The resulting object can be used as a context manager (see - :ref:`context-managers`). On completion of the context or destruction + :ref:`tempfile-examples`). On completion of the context or destruction of the temporary directory object the newly created temporary directory and all its contents are removed from the filesystem. @@ -194,49 +200,14 @@ The module defines the following user-callable items: an appropriate default value to be used. -.. function:: mktemp(suffix='', prefix='tmp', dir=None) - - .. deprecated:: 2.3 - Use :func:`mkstemp` instead. - - Return an absolute pathname of a file that did not exist at the time the - call is made. The *prefix*, *suffix*, and *dir* arguments are the same - as for :func:`mkstemp`. - - .. warning:: - - Use of this function may introduce a security hole in your program. By - the time you get around to doing anything with the file name it returns, - someone else may have beaten you to the punch. :func:`mktemp` usage can - be replaced easily with :func:`NamedTemporaryFile`, passing it the - ``delete=False`` parameter:: - - >>> f = NamedTemporaryFile(delete=False) - >>> f.name - '/tmp/tmptjujjt' - >>> f.write(b"Hello World!\n") - 13 - >>> f.close() - >>> os.unlink(f.name) - >>> os.path.exists(f.name) - False - -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. - +.. function:: gettempdir() -.. data:: tempdir + Return the name of the directory used for temporary files. This + defines the default value for the *dir* argument to all functions + in this module. - When set to a value other than ``None``, this variable defines the - default value for the *dir* argument to all the functions defined in this - module. - - If ``tempdir`` is unset or ``None`` at any call to any of the above - functions, Python searches a standard list of directories and sets - *tempdir* to the first one which the calling user can create files in. - The list is: + Python searches a standard list of directories to find one which + the calling user can create files in. The list is: #. The directory named by the :envvar:`TMPDIR` environment variable. @@ -254,12 +225,8 @@ the appropriate function arguments, instead. #. As a last resort, the current working directory. - -.. function:: gettempdir() - - Return the directory currently selected to create temporary files in. If - :data:`tempdir` is not ``None``, this simply returns its contents; otherwise, - the search described above is performed, and the result returned. + The result of this search is cached, see the description of + :data:`tempdir` below. .. function:: gettempdirb() @@ -278,6 +245,23 @@ the appropriate function arguments, instead. .. versionadded:: 3.5 +The module uses a global variable to store the name of the directory +used for temporary files returned by :func:`gettempdir`. It can be +set directly to override the selection process, but this is discouraged. +All functions in this module take a *dir* argument which can be used +to specify the directory and this is the recommend approach. + +.. data:: tempdir + + When set to a value other than ``None``, this variable defines the + default value for the *dir* argument to all the functions defined in this + module. + + If ``tempdir`` is unset or ``None`` at any call to any of the above + functions except :func:`gettempprefix` it is initalized following the + algorithm described in :func:`gettempdir`. + +.. _tempfile-examples: Examples -------- @@ -311,3 +295,42 @@ Here are some examples of typical usage of the :mod:`tempfile` module:: >>> # directory and contents have been removed + +Deprecated functions and variables +---------------------------------- + +A historical way to create temporary files was to first generate a +file name with the :func:`mktemp` function and then create a file +using this name. Unfortunately this is not secure, because a different +process may create a file with this name in the time between the call +to :func:`mktemp` and the subsequent attempt to create the file by the +first process. The solution is to combine the two steps and create the +file immediately. This approach is used by :func:`mkstemp` and the +other functions described above. + +.. function:: mktemp(suffix='', prefix='tmp', dir=None) + + .. deprecated:: 2.3 + Use :func:`mkstemp` instead. + + Return an absolute pathname of a file that did not exist at the time the + call is made. The *prefix*, *suffix*, and *dir* arguments are the same + as for :func:`mkstemp`. + + .. warning:: + + Use of this function may introduce a security hole in your program. By + the time you get around to doing anything with the file name it returns, + someone else may have beaten you to the punch. :func:`mktemp` usage can + be replaced easily with :func:`NamedTemporaryFile`, passing it the + ``delete=False`` parameter:: + + >>> f = NamedTemporaryFile(delete=False) + >>> f.name + '/tmp/tmptjujjt' + >>> f.write(b"Hello World!\n") + 13 + >>> f.close() + >>> os.unlink(f.name) + >>> os.path.exists(f.name) + False diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 5269994781..c56d707342 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -89,7 +89,8 @@ This module defines the following functions: Return the thread stack size used when creating new threads. The optional *size* argument specifies the stack size to be used for subsequently created threads, and must be 0 (use platform or configured default) or a positive - integer value of at least 32,768 (32 KiB). If changing the thread stack size is + integer value of at least 32,768 (32 KiB). If *size* is not specified, + 0 is used. If changing the thread stack size is unsupported, a :exc:`RuntimeError` is raised. If the specified stack size is invalid, a :exc:`ValueError` is raised and the stack size is unmodified. 32 KiB is currently the minimum supported stack size value to guarantee sufficient diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst index 594933c2b0..e09b6472ad 100644 --- a/Doc/library/typing.rst +++ b/Doc/library/typing.rst @@ -20,8 +20,9 @@ The function below takes and returns a string and is annotated as follows:: def greeting(name: str) -> str: return 'Hello ' + name -In the function `greeting`, the argument `name` is expected to by of type `str` -and the return type `str`. Subtypes are accepted as arguments. +In the function ``greeting``, the argument ``name`` is expected to by of type +:class:`str` and the return type :class:`str`. Subtypes are accepted as +arguments. Type aliases ------------ @@ -49,8 +50,8 @@ For example:: It is possible to declare the return type of a callable without specifying the call signature by substituting a literal ellipsis -for the list of arguments in the type hint: `Callable[..., ReturnType]`. -`None` as a type hint is a special case and is replaced by `type(None)`. +for the list of arguments in the type hint: ``Callable[..., ReturnType]``. +``None`` as a type hint is a special case and is replaced by ``type(None)``. Generics -------- @@ -108,11 +109,12 @@ A user-defined class can be defined as a generic class. def log(self, message: str) -> None: self.logger.info('{}: {}'.format(self.name, message)) -`Generic[T]` as a base class defines that the class `LoggedVar` takes a single -type parameter `T` . This also makes `T` valid as a type within the class body. +``Generic[T]`` as a base class defines that the class ``LoggedVar`` takes a +single type parameter ``T`` . This also makes ``T`` valid as a type within the +class body. -The `Generic` base class uses a metaclass that defines `__getitem__` so that -`LoggedVar[t]` is valid as a type:: +The :class:`Generic` base class uses a metaclass that defines +:meth:`__getitem__` so that ``LoggedVar[t]`` is valid as a type:: from typing import Iterable @@ -132,7 +134,7 @@ be constrained:: class StrangePair(Generic[T, S]): ... -Each type variable argument to `Generic` must be distinct. +Each type variable argument to :class:`Generic` must be distinct. This is thus invalid:: from typing import TypeVar, Generic @@ -152,9 +154,9 @@ You can use multiple inheritance with `Generic`:: class LinkedList(Sized, Generic[T]): ... -Subclassing a generic class without specifying type parameters assumes `Any` -for each position. In the following example, `MyIterable` is not generic but -implicitly inherits from `Iterable[Any]`:: +Subclassing a generic class without specifying type parameters assumes +:class:`Any` for each position. In the following example, ``MyIterable`` is +not generic but implicitly inherits from ``Iterable[Any]``:: from typing import Iterable @@ -162,24 +164,24 @@ implicitly inherits from `Iterable[Any]`:: Generic metaclasses are not supported. -The `Any` type --------------- +The :class:`Any` type +--------------------- -A special kind of type is `Any`. Every type is a subtype of `Any`. -This is also true for the builtin type object. However, to the static type -checker these are completely different. +A special kind of type is :class:`Any`. Every type is a subtype of +:class:`Any`. This is also true for the builtin type object. However, to the +static type checker these are completely different. -When the type of a value is `object`, the type checker will reject almost all -operations on it, and assigning it to a variable (or using it as a return value) -of a more specialized type is a type error. On the other hand, when a value has -type `Any`, the type checker will allow all operations on it, and a value of -type `Any` can be assigned to a variable (or used as a return value) of a more -constrained type. +When the type of a value is :class:`object`, the type checker will reject +almost all operations on it, and assigning it to a variable (or using it as a +return value) of a more specialized type is a type error. On the other hand, +when a value has type :class:`Any`, the type checker will allow all operations +on it, and a value of type :class:`Any` can be assigned to a variable (or used +as a return value) of a more constrained type. Default argument values ----------------------- -Use a literal ellipsis `...` to declare an argument as having a default value:: +Use a literal ellipsis ``...`` to declare an argument as having a default value:: from typing import AnyStr @@ -195,9 +197,10 @@ The module defines the following classes, functions and decorators: Special type indicating an unconstrained type. - * Any object is an instance of `Any`. - * Any class is a subclass of `Any`. - * As a special case, `Any` and `object` are subclasses of each other. + * Any object is an instance of :class:`Any`. + * Any class is a subclass of :class:`Any`. + * As a special case, :class:`Any` and :class:`object` are subclasses of + each other. .. class:: TypeVar @@ -224,22 +227,22 @@ The module defines the following classes, functions and decorators: return x if len(x) >= len(y) else y The latter example's signature is essentially the overloading - of `(str, str) -> str` and `(bytes, bytes) -> bytes`. Also note - that if the arguments are instances of some subclass of `str`, - the return type is still plain `str`. + of ``(str, str) -> str`` and ``(bytes, bytes) -> bytes``. Also note + that if the arguments are instances of some subclass of :class:`str`, + the return type is still plain :class:`str`. - At runtime, `isinstance(x, T)` will raise `TypeError`. In general, - `isinstance` and `issublass` should not be used with types. + At runtime, ``isinstance(x, T)`` will raise :exc:`TypeError`. In general, + :func:`isinstance` and :func:`issublass` should not be used with types. Type variables may be marked covariant or contravariant by passing - `covariant=True` or `contravariant=True`. See :pep:`484` for more + ``covariant=True`` or ``contravariant=True``. See :pep:`484` for more details. By default type variables are invariant. .. class:: Union - Union type; `Union[X, Y]` means either X or Y. + Union type; ``Union[X, Y]`` means either X or Y. - To define a union, use e.g. `Union[int, str]`. Details: + To define a union, use e.g. ``Union[int, str]``. Details: * The arguments must be types and there must be at least one. @@ -259,37 +262,37 @@ The module defines the following classes, functions and decorators: Union[int, str] == Union[str, int] - * If `Any` is present it is the sole survivor, e.g.:: + * If :class:`Any` is present it is the sole survivor, e.g.:: Union[int, Any] == Any * You cannot subclass or instantiate a union. - * You cannot write `Union[X][Y]` + * You cannot write ``Union[X][Y]`` - * You can use `Optional[X]` as a shorthand for `Union[X, None]`. + * You can use ``Optional[X]`` as a shorthand for ``Union[X, None]``. .. class:: Optional Optional type. - `Optional[X]` is equivalent to `Union[X, type(None)]`. + ``Optional[X]`` is equivalent to ``Union[X, type(None)]``. .. class:: Tuple - Tuple type; `Tuple[X, Y]` is the is the type of a tuple of two items + Tuple type; ``Tuple[X, Y]`` is the is the type of a tuple of two items with the first item of type X and the second of type Y. - Example: `Tuple[T1, T2]` is a tuple of two elements corresponding - to type variables T1 and T2. `Tuple[int, float, str]` is a tuple + Example: ``Tuple[T1, T2]`` is a tuple of two elements corresponding + to type variables T1 and T2. ``Tuple[int, float, str]`` is a tuple of an int, a float and a string. To specify a variable-length tuple of homogeneous type, - use literal ellipsis, e.g. `Tuple[int, ...]`. + use literal ellipsis, e.g. ``Tuple[int, ...]``. .. class:: Callable - Callable type; `Callable[[int], str]` is a function of (int) -> str. + Callable type; ``Callable[[int], str]`` is a function of (int) -> str. The subscription syntax must always be used with exactly two values: the argument list and the return type. The argument list @@ -297,9 +300,9 @@ The module defines the following classes, functions and decorators: There is no syntax to indicate optional or keyword arguments, such function types are rarely used as callback types. - `Callable[..., ReturnType]` could be used to type hint a callable - taking any number of arguments and returning `ReturnType`. - A plain `Callable` is equivalent to `Callable[..., Any]`. + ``Callable[..., ReturnType]`` could be used to type hint a callable + taking any number of arguments and returning ``ReturnType``. + A plain :class:`Callable` is equivalent to ``Callable[..., Any]``. .. class:: Generic diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst index 508570314f..1153f834ea 100644 --- a/Doc/library/unittest.rst +++ b/Doc/library/unittest.rst @@ -278,8 +278,8 @@ The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in as positional arguments in that order. The following two command lines are equivalent:: - python -m unittest discover -s project_directory -p '*_test.py' - python -m unittest discover project_directory '*_test.py' + python -m unittest discover -s project_directory -p "*_test.py" + python -m unittest discover project_directory "*_test.py" As well as being a path it is possible to pass a package name, for example ``myproject.subpackage.test``, as the start directory. The package name you diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index eef1b58348..14e5c9932f 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -651,21 +651,29 @@ Element Objects .. attribute:: text + tail - The *text* attribute can be used to hold additional data associated with - the element. As the name implies this attribute is usually a string but - may be any application-specific object. If the element is created from - an XML file the attribute will contain any text found between the element - tags. + These attributes can be used to hold additional data associated with + the element. Their values are usually strings but may be any + application-specific object. If the element is created from + an XML file, the *text* attribute holds either the text between + the element's start tag and its first child or end tag, or ``None``, and + the *tail* attribute holds either the text between the element's + end tag and the next tag, or ``None``. For the XML data + .. code-block:: xml - .. attribute:: tail + <a><b>1<c>2<d/>3</c></b>4</a> - The *tail* attribute can be used to hold additional data associated with - the element. This attribute is usually a string but may be any - application-specific object. If the element is created from an XML file - the attribute will contain any text found after the element's end tag and - before the next tag. + the *a* element has ``None`` for both *text* and *tail* attributes, + the *b* element has *text* ``"1"`` and *tail* ``"4"``, + the *c* element has *text* ``"2"`` and *tail* ``None``, + and the *d* element has *text* ``None`` and *tail* ``"3"``. + + To collect the inner text of an element, see :meth:`itertext`, for + example ``"".join(element.itertext())``. + + Applications may store arbitrary objects in these attributes. .. attribute:: attrib diff --git a/Doc/tutorial/datastructures.rst b/Doc/tutorial/datastructures.rst index a2031ed867..0d51480177 100644 --- a/Doc/tutorial/datastructures.rst +++ b/Doc/tutorial/datastructures.rst @@ -612,18 +612,18 @@ returns a new sorted list while leaving the source unaltered. :: orange pear -To change a sequence you are iterating over while inside the loop (for -example to duplicate certain items), it is recommended that you first make -a copy. Looping over a sequence does not implicitly make a copy. The slice -notation makes this especially convenient:: - - >>> words = ['cat', 'window', 'defenestrate'] - >>> for w in words[:]: # Loop over a slice copy of the entire list. - ... if len(w) > 6: - ... words.insert(0, w) +It is sometimes tempting to change a list while you are looping over it; +however, it is often simpler and safer to create a new list instead. :: + + >>> import math + >>> raw_data = [56.2, float('NaN'), 51.7, 55.3, 52.5, float('NaN'), 47.8] + >>> filtered_data = [] + >>> for value in raw_data: + ... if not math.isnan(value): + ... filtered_data.append(value) ... - >>> words - ['defenestrate', 'cat', 'window', 'defenestrate'] + >>> filtered_data + [56.2, 51.7, 55.3, 52.5, 47.8] .. _tut-conditions: diff --git a/Doc/using/mac.rst b/Doc/using/mac.rst index ede864d7ad..ef091e5275 100644 --- a/Doc/using/mac.rst +++ b/Doc/using/mac.rst @@ -102,8 +102,9 @@ Configuration Python on OS X honors all standard Unix environment variables such as :envvar:`PYTHONPATH`, but setting these variables for programs started from the Finder is non-standard as the Finder does not read your :file:`.profile` or -:file:`.cshrc` at startup. You need to create a file :file:`~ -/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for details. +:file:`.cshrc` at startup. You need to create a file +:file:`~/.MacOSX/environment.plist`. See Apple's Technical Document QA1067 for +details. For more information on installation Python packages in MacPython, see section :ref:`mac-package-manager`. |