diff options
Diffstat (limited to 'Doc/library')
| -rw-r--r-- | Doc/library/builtins.rst | 2 | ||||
| -rw-r--r-- | Doc/library/curses.ascii.rst | 4 | ||||
| -rw-r--r-- | Doc/library/dbm.rst | 10 | ||||
| -rw-r--r-- | Doc/library/enum.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 12 | ||||
| -rw-r--r-- | Doc/library/functools.rst | 2 | ||||
| -rw-r--r-- | Doc/library/importlib.rst | 14 | ||||
| -rw-r--r-- | Doc/library/inspect.rst | 9 | ||||
| -rw-r--r-- | Doc/library/json.rst | 8 | ||||
| -rw-r--r-- | Doc/library/multiprocessing.rst | 9 | ||||
| -rw-r--r-- | Doc/library/os.rst | 11 | ||||
| -rw-r--r-- | Doc/library/re.rst | 2 | ||||
| -rw-r--r-- | Doc/library/readline.rst | 7 | ||||
| -rw-r--r-- | Doc/library/sqlite3.rst | 41 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 15 | ||||
| -rw-r--r-- | Doc/library/tarfile.rst | 14 | ||||
| -rw-r--r-- | Doc/library/zipfile.rst | 6 |
17 files changed, 100 insertions, 68 deletions
diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst index 4b589a5..8fb1fef 100644 --- a/Doc/library/builtins.rst +++ b/Doc/library/builtins.rst @@ -37,6 +37,6 @@ that wants to implement an :func:`open` function that wraps the built-in As an implementation detail, most modules have the name ``__builtins__`` made available as part of their globals. The value of ``__builtins__`` is normally -either this module or the value of this module's :attr:`__dict__` attribute. +either this module or the value of this module's :attr:`~object.__dict__` attribute. Since this is an implementation detail, it may not be used by alternate implementations of Python. diff --git a/Doc/library/curses.ascii.rst b/Doc/library/curses.ascii.rst index f3661d9..db3c827 100644 --- a/Doc/library/curses.ascii.rst +++ b/Doc/library/curses.ascii.rst @@ -115,12 +115,12 @@ C library: .. function:: isblank(c) - Checks for an ASCII whitespace character. + Checks for an ASCII whitespace character; space or horizontal tab. .. function:: iscntrl(c) - Checks for an ASCII control character (in the range 0x00 to 0x1f). + Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f). .. function:: isdigit(c) diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 6f64196..2a1db91 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -128,6 +128,9 @@ The individual submodules are described in the following sections. :platform: Unix :synopsis: GNU's reinterpretation of dbm. +**Source code:** :source:`Lib/dbm/gnu.py` + +-------------- This module is quite similar to the :mod:`dbm` module, but uses the GNU library ``gdbm`` instead to provide some additional functionality. Please note that the @@ -237,6 +240,9 @@ supported. :platform: Unix :synopsis: The standard "database" interface, based on ndbm. +**Source code:** :source:`Lib/dbm/ndbm.py` + +-------------- The :mod:`dbm.ndbm` module provides an interface to the Unix "(n)dbm" library. Dbm objects behave like mappings (dictionaries), except that keys and values are @@ -299,6 +305,8 @@ to locate the appropriate header file to simplify building this module. .. module:: dbm.dumb :synopsis: Portable implementation of the simple DBM interface. +**Source code:** :source:`Lib/dbm/dumb.py` + .. index:: single: databases .. note:: @@ -308,6 +316,8 @@ to locate the appropriate header file to simplify building this module. module is not written for speed and is not nearly as heavily used as the other database modules. +-------------- + The :mod:`dbm.dumb` module provides a persistent dictionary-like interface which is written entirely in Python. Unlike other modules such as :mod:`dbm.gnu` no external library is required. As with other persistent mappings, the keys and diff --git a/Doc/library/enum.rst b/Doc/library/enum.rst index 60467b4..a3d5afc 100644 --- a/Doc/library/enum.rst +++ b/Doc/library/enum.rst @@ -431,7 +431,7 @@ The solution is to specify the module name explicitly as follows:: the source, pickling will be disabled. The new pickle protocol 4 also, in some circumstances, relies on -:attr:`__qualname__` being set to the location where pickle will be able +:attr:`~definition.__qualname__` being set to the location where pickle will be able to find the class. For example, if the class was made available in class SomeData in the global scope:: diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index c3563f3..efa5bd3 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -304,7 +304,7 @@ are always available. They are listed here in alphabetical order. :func:`dir` reports their attributes. If the object does not provide :meth:`__dir__`, the function tries its best to - gather information from the object's :attr:`__dict__` attribute, if defined, and + gather information from the object's :attr:`~object.__dict__` attribute, if defined, and from its type object. The resulting list is not necessarily complete, and may be inaccurate when the object has a custom :func:`__getattr__`. @@ -1446,7 +1446,7 @@ are always available. They are listed here in alphabetical order. With three arguments, return a new type object. This is essentially a dynamic form of the :keyword:`class` statement. The *name* string is the - class name and becomes the :attr:`~class.__name__` attribute; the *bases* + class name and becomes the :attr:`~definition.__name__` attribute; the *bases* tuple itemizes the base classes and becomes the :attr:`~class.__bases__` attribute; and the *dict* dictionary is the namespace containing definitions for class body and is copied to a standard dictionary to become the @@ -1464,12 +1464,12 @@ are always available. They are listed here in alphabetical order. .. function:: vars([object]) Return the :attr:`~object.__dict__` attribute for a module, class, instance, - or any other object with a :attr:`__dict__` attribute. + or any other object with a :attr:`~object.__dict__` attribute. - Objects such as modules and instances have an updateable :attr:`__dict__` + Objects such as modules and instances have an updateable :attr:`~object.__dict__` attribute; however, other objects may have write restrictions on their - :attr:`__dict__` attributes (for example, classes use a - dictproxy to prevent direct dictionary updates). + :attr:`~object.__dict__` attributes (for example, classes use a + :class:`types.MappingProxyType` to prevent direct dictionary updates). Without an argument, :func:`vars` acts like :func:`locals`. Note, the locals dictionary is only useful for reads since updates to the locals diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index abdd66f..127e3fa 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -474,7 +474,7 @@ have three read-only attributes: :class:`partial` objects are like :class:`function` objects in that they are callable, weak referencable, and can have attributes. There are some important -differences. For instance, the :attr:`__name__` and :attr:`__doc__` attributes +differences. For instance, the :attr:`~definition.__name__` and :attr:`__doc__` attributes are not created automatically. Also, :class:`partial` objects defined in classes behave like static methods and do not transform into bound methods during instance attribute look-up. diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index 3302446..ff7cc91 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -211,6 +211,11 @@ Functions .. module:: importlib.abc :synopsis: Abstract base classes related to import +**Source code:** :source:`Lib/importlib/abc.py` + +-------------- + + The :mod:`importlib.abc` module contains all of the core abstract base classes used by :keyword:`import`. Some subclasses of the core abstract base classes are also provided to help in implementing the core ABCs. @@ -700,6 +705,10 @@ ABC hierarchy:: .. module:: importlib.machinery :synopsis: Importers and path hooks +**Source code:** :source:`Lib/importlib/machinery.py` + +-------------- + This module contains the various objects that help :keyword:`import` find and load modules. @@ -1082,6 +1091,11 @@ find and load modules. .. module:: importlib.util :synopsis: Utility code for importers + +**Source code:** :source:`Lib/importlib/util.py` + +-------------- + This module contains the various objects that help in the construction of an :term:`importer`. diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index b28d0f9..8e7ed19 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -374,8 +374,9 @@ attributes: are true. This, for example, is true of ``int.__add__``. An object passing this test - has a :attr:`__get__` attribute but not a :attr:`__set__` attribute, but - beyond that the set of attributes varies. :attr:`__name__` is usually + has a :meth:`~object.__get__` method but not a :meth:`~object.__set__` + method, but beyond that the set of attributes varies. A + :attr:`~definition.__name__` attribute is usually sensible, and :attr:`__doc__` often is. Methods implemented via descriptors that also pass one of the other tests @@ -388,11 +389,11 @@ attributes: Return true if the object is a data descriptor. - Data descriptors have both a :attr:`__get__` and a :attr:`__set__` attribute. + Data descriptors have both a :attr:`~object.__get__` and a :attr:`~object.__set__` method. Examples are properties (defined in Python), getsets, and members. The latter two are defined in C and there are more specific tests available for those types, which is robust across Python implementations. Typically, data - descriptors will also have :attr:`__name__` and :attr:`__doc__` attributes + descriptors will also have :attr:`~definition.__name__` and :attr:`__doc__` attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed. diff --git a/Doc/library/json.rst b/Doc/library/json.rst index 174e734..1e34cf3 100644 --- a/Doc/library/json.rst +++ b/Doc/library/json.rst @@ -629,13 +629,19 @@ when serializing instances of "exotic" numerical types such as :class:`decimal.Decimal`. .. highlight:: bash -.. module:: json.tool .. _json-commandline: Command Line Interface ---------------------- +.. module:: json.tool + :synopsis: A command line to validate and pretty-print JSON. + +**Source code:** :source:`Lib/json/tool.py` + +-------------- + The :mod:`json.tool` module provides a simple command line interface to validate and pretty-print JSON objects. diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index c5c092c..d20098f 100644 --- a/Doc/library/multiprocessing.rst +++ b/Doc/library/multiprocessing.rst @@ -1010,7 +1010,7 @@ Connection objects are usually created using :func:`Pipe` -- see also using :meth:`recv`. The object must be picklable. Very large pickles (approximately 32 MB+, - though it depends on the OS) may raise a ValueError exception. + though it depends on the OS) may raise a :exc:`ValueError` exception. .. method:: recv() @@ -2723,12 +2723,7 @@ start method. More picklability - Ensure that all arguments to :meth:`Process.__init__` are - picklable. This means, in particular, that bound or unbound - methods cannot be used directly as the ``target`` (unless you use - the *fork* start method) --- just define a function and use that - instead. - + Ensure that all arguments to :meth:`Process.__init__` are picklable. Also, if you subclass :class:`~multiprocessing.Process` then make sure that instances will be picklable when the :meth:`Process.start <multiprocessing.Process.start>` method is called. diff --git a/Doc/library/os.rst b/Doc/library/os.rst index 743efb6..e73d8ee 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -1195,7 +1195,11 @@ or `the MSDN <https://msdn.microsoft.com/en-us/library/z0kc8e3z.aspx>`_ on Windo .. function:: writev(fd, buffers) Write the contents of *buffers* to file descriptor *fd*. *buffers* must be a - sequence of :term:`bytes-like objects <bytes-like object>`. + sequence of :term:`bytes-like objects <bytes-like object>`. Buffers are + processed in array order. Entire contents of first buffer is written before + proceeding to second, and so on. The operating system may set a limit + (sysconf() value SC_IOV_MAX) on the number of buffers that can be used. + :func:`~os.writev` writes the contents of each object to the file descriptor and returns the total number of bytes written. @@ -2049,9 +2053,8 @@ features: Note that there is a nice correspondence between several attributes and methods of ``DirEntry`` and of :class:`pathlib.Path`. In - particular, the ``name`` and ``path`` attributes have the same - meaning, as do the ``is_dir()``, ``is_file()``, ``is_symlink()`` - and ``stat()`` methods. + particular, the ``name`` attribute has the same meaning, as do the + ``is_dir()``, ``is_file()``, ``is_symlink()`` and ``stat()`` methods. .. versionadded:: 3.5 diff --git a/Doc/library/re.rst b/Doc/library/re.rst index 18d5596..569b522 100644 --- a/Doc/library/re.rst +++ b/Doc/library/re.rst @@ -443,7 +443,7 @@ three digits in length. The ``'\u'`` and ``'\U'`` escape sequences have been added. .. deprecated-removed:: 3.5 3.6 - Unknown escapes consist of ``'\'`` and ASCII letter now raise a + Unknown escapes consisting of ``'\'`` and ASCII letter now raise a deprecation warning and will be forbidden in Python 3.6. diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst index e17e69c..4d3c099 100644 --- a/Doc/library/readline.rst +++ b/Doc/library/readline.rst @@ -104,7 +104,9 @@ The following functions operate on a history file: Append the last *nelements* items of history to a file. The default filename is :file:`~/.history`. The file must already exist. This calls - :c:func:`append_history` in the underlying library. + :c:func:`append_history` in the underlying library. This function + only exists if Python was compiled for a version of the library + that supports it. .. versionadded:: 3.5 @@ -185,7 +187,8 @@ Startup hooks be used as the new hook function; if omitted or ``None``, any function already installed is removed. The hook is called with no arguments after the first prompt has been printed and just before - readline starts reading input characters. + readline starts reading input characters. This function only exists + if Python was compiled for a version of the library that supports it. Completion diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 3bba935..605d8d3 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -309,25 +309,26 @@ Connection Objects call :meth:`commit`. If you just close your database connection without calling :meth:`commit` first, your changes will be lost! - .. method:: execute(sql, [parameters]) + .. method:: execute(sql[, parameters]) - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`execute - <Cursor.execute>` method with the parameters given. + This is a nonstandard shortcut that creates a cursor object by calling + the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.execute` method with the *parameters* given, and returns + the cursor. + .. method:: executemany(sql[, parameters]) - .. method:: executemany(sql, [parameters]) - - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`executemany - <Cursor.executemany>` method with the parameters given. + This is a nonstandard shortcut that creates a cursor object by + calling the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.executemany` method with the *parameters* given, and + returns the cursor. .. method:: executescript(sql_script) - This is a nonstandard shortcut that creates an intermediate cursor object by - calling the cursor method, then calls the cursor's :meth:`executescript - <Cursor.executescript>` method with the parameters given. - + This is a nonstandard shortcut that creates a cursor object by + calling the :meth:`~Connection.cursor` method, calls the cursor's + :meth:`~Cursor.executescript` method with the given *sql_script*, and + returns the cursor. .. method:: create_function(name, num_params, func) @@ -488,10 +489,6 @@ Connection Objects :mod:`sqlite3` module will return Unicode objects for ``TEXT``. If you want to return bytestrings instead, you can set it to :class:`bytes`. - For efficiency reasons, there's also a way to return :class:`str` objects - only for non-ASCII data, and :class:`bytes` otherwise. To activate it, set - this attribute to :const:`sqlite3.OptimizedUnicode`. - You can also set it to any other callable that accepts a single bytestring parameter and returns the resulting object. @@ -533,7 +530,7 @@ Cursor Objects A :class:`Cursor` instance has the following attributes and methods. - .. method:: execute(sql, [parameters]) + .. method:: execute(sql[, parameters]) Executes an SQL statement. The SQL statement may be parameterized (i. e. placeholders instead of SQL literals). The :mod:`sqlite3` module supports two @@ -545,7 +542,7 @@ Cursor Objects .. literalinclude:: ../includes/sqlite3/execute_1.py :meth:`execute` will only execute a single SQL statement. If you try to execute - more than one statement with it, it will raise a Warning. Use + more than one statement with it, it will raise an ``sqlite3.Warning``. Use :meth:`executescript` if you want to execute multiple SQL statements with one call. @@ -553,8 +550,8 @@ Cursor Objects .. method:: executemany(sql, seq_of_parameters) Executes an SQL command against all parameter sequences or mappings found in - the sequence *sql*. The :mod:`sqlite3` module also allows using an - :term:`iterator` yielding parameters instead of a sequence. + the sequence *seq_of_parameters*. The :mod:`sqlite3` module also allows + using an :term:`iterator` yielding parameters instead of a sequence. .. literalinclude:: ../includes/sqlite3/executemany_1.py @@ -569,7 +566,7 @@ Cursor Objects at once. It issues a ``COMMIT`` statement first, then executes the SQL script it gets as a parameter. - *sql_script* can be an instance of :class:`str` or :class:`bytes`. + *sql_script* can be an instance of :class:`str`. Example: diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index e8a488e..db1c2d0 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -4360,9 +4360,10 @@ an (external) *definition* for a module named *foo* somewhere.) A special attribute of every module is :attr:`~object.__dict__`. This is the dictionary containing the module's symbol table. Modifying this dictionary will actually change the module's symbol table, but direct assignment to the -:attr:`__dict__` attribute is not possible (you can write +:attr:`~object.__dict__` attribute is not possible (you can write ``m.__dict__['a'] = 1``, which defines ``m.a`` to be ``1``, but you can't write -``m.__dict__ = {}``). Modifying :attr:`__dict__` directly is not recommended. +``m.__dict__ = {}``). Modifying :attr:`~object.__dict__` directly is +not recommended. Modules built into the interpreter are written like this: ``<module 'sys' (built-in)>``. If loaded from a file, they are written as ``<module 'os' from @@ -4575,14 +4576,16 @@ types, where they are relevant. Some of these are not reported by the The tuple of base classes of a class object. -.. attribute:: class.__name__ +.. attribute:: definition.__name__ - The name of the class or type. + The name of the class, function, method, descriptor, or + generator instance. -.. attribute:: class.__qualname__ +.. attribute:: definition.__qualname__ - The :term:`qualified name` of the class or type. + The :term:`qualified name` of the class, function, method, descriptor, + or generator instance. .. versionadded:: 3.3 diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 32d69bf..90a5852 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -64,19 +64,19 @@ Some facts and figures: | ``'x'`` or | Create a tarfile exclusively without | | ``'x:'`` | compression. | | | Raise an :exc:`FileExistsError` exception | - | | if it is already exists. | + | | if it already exists. | +------------------+---------------------------------------------+ | ``'x:gz'`` | Create a tarfile with gzip compression. | | | Raise an :exc:`FileExistsError` exception | - | | if it is already exists. | + | | if it already exists. | +------------------+---------------------------------------------+ | ``'x:bz2'`` | Create a tarfile with bzip2 compression. | | | Raise an :exc:`FileExistsError` exception | - | | if it is already exists. | + | | if it already exists. | +------------------+---------------------------------------------+ | ``'x:xz'`` | Create a tarfile with lzma compression. | | | Raise an :exc:`FileExistsError` exception | - | | if it is already exists. | + | | if it already exists. | +------------------+---------------------------------------------+ | ``'a' or 'a:'`` | Open for appending with no compression. The | | | file is created if it does not exist. | @@ -148,8 +148,8 @@ Some facts and figures: .. class:: TarFile - Class for reading and writing tar archives. Do not use this class directly, - better use :func:`tarfile.open` instead. See :ref:`tarfile-objects`. + Class for reading and writing tar archives. Do not use this class directly: + use :func:`tarfile.open` instead. See :ref:`tarfile-objects`. .. function:: is_tarfile(name) @@ -271,7 +271,7 @@ be finalized; only the internally used file object will be closed. See the *mode* is either ``'r'`` to read from an existing archive, ``'a'`` to append data to an existing file, ``'w'`` to create a new file overwriting an existing - one or ``'x'`` to create a new file only if it's not exists. + one, or ``'x'`` to create a new file only if it does not already exist. If *fileobj* is given, it is used for reading or writing data. If it can be determined, *mode* is overridden by *fileobj*'s mode. *fileobj* will be used diff --git a/Doc/library/zipfile.rst b/Doc/library/zipfile.rst index b421ea5..abe38c4 100644 --- a/Doc/library/zipfile.rst +++ b/Doc/library/zipfile.rst @@ -250,7 +250,7 @@ ZipFile Objects .. method:: ZipFile.extract(member, path=None, pwd=None) Extract a member from the archive to the current working directory; *member* - must be its full name or a :class:`ZipInfo` object). Its file information is + must be its full name or a :class:`ZipInfo` object. Its file information is extracted as accurately as possible. *path* specifies a different directory to extract to. *member* can be a filename or a :class:`ZipInfo` object. *pwd* is the password used for encrypted files. @@ -343,9 +343,9 @@ ZipFile Objects If ``arcname`` (or ``filename``, if ``arcname`` is not given) contains a null byte, the name of the file in the archive will be truncated at the null byte. -.. method:: ZipFile.writestr(zinfo_or_arcname, bytes[, compress_type]) +.. method:: ZipFile.writestr(zinfo_or_arcname, data[, compress_type]) - Write the string *bytes* to the archive; *zinfo_or_arcname* is either the file + Write the string *data* to the archive; *zinfo_or_arcname* is either the file name it will be given in the archive, or a :class:`ZipInfo` instance. If it's an instance, at least the filename, date, and time must be given. If it's a name, the date and time is set to the current date and time. |