diff options
Diffstat (limited to 'Doc')
31 files changed, 161 insertions, 124 deletions
diff --git a/Doc/Makefile b/Doc/Makefile index a42e98b..878685d 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -166,7 +166,7 @@ autobuild-dev: -make suspicious # for quick rebuilds (HTML only) -autobuild-html: +autobuild-dev-html: make html SPHINXOPTS='-A daily=1 -A versionswitcher=1' # for stable releases: only build if not in pre-release stage (alpha, beta) @@ -177,3 +177,10 @@ autobuild-stable: exit 1;; \ esac @make autobuild-dev + +autobuild-stable-html: + @case $(DISTVERSION) in *[ab]*) \ + echo "Not building; $(DISTVERSION) is not a release version."; \ + exit 1;; \ + esac + @make autobuild-dev-html diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst index 904b4b1..34f8443 100644 --- a/Doc/c-api/module.rst +++ b/Doc/c-api/module.rst @@ -59,10 +59,10 @@ Module Objects .. index:: single: __dict__ (module attribute) Return the dictionary object that implements *module*'s namespace; this object - is the same as the :attr:`__dict__` attribute of the module object. This + is the same as the :attr:`~object.__dict__` attribute of the module object. This function never fails. It is recommended extensions use other :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly - manipulate a module's :attr:`__dict__`. + manipulate a module's :attr:`~object.__dict__`. .. c:function:: PyObject* PyModule_GetNameObject(PyObject *module) diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst index e9e8add..cc84314 100644 --- a/Doc/c-api/structures.rst +++ b/Doc/c-api/structures.rst @@ -150,9 +150,8 @@ specific C type of the *self* object. The :attr:`ml_flags` field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention. Of the calling convention flags, only :const:`METH_VARARGS` and -:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS` -alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling -convention flags can be combined with a binding flag. +:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags +can be combined with a binding flag. .. data:: METH_VARARGS diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ac589b8..2c448a0 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -111,10 +111,10 @@ type objects) *must* have the :attr:`ob_size` field. For statically allocated type objects, the tp_name field should contain a dot. Everything before the last dot is made accessible as the :attr:`__module__` attribute, and everything after the last dot is made accessible as the - :attr:`__name__` attribute. + :attr:`~definition.__name__` attribute. If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the - :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined + :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined (unless explicitly set in the dictionary, as explained above). This means your type will be impossible to pickle. diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst index 6b773dd..3f96700 100644 --- a/Doc/faq/general.rst +++ b/Doc/faq/general.rst @@ -438,7 +438,7 @@ remember the methods for a list, they can do something like this:: >>> L [1] -With the interpreter, documentation is never far from the student as he's +With the interpreter, documentation is never far from the student as they are programming. There are also good IDEs for Python. IDLE is a cross-platform IDE for Python diff --git a/Doc/howto/regex.rst b/Doc/howto/regex.rst index de3f461..371ef59 100644 --- a/Doc/howto/regex.rst +++ b/Doc/howto/regex.rst @@ -374,9 +374,7 @@ module. If you have :mod:`tkinter` available, you may also want to look at :source:`Tools/demo/redemo.py`, a demonstration program included with the Python distribution. It allows you to enter REs and strings, and displays whether the RE matches or fails. :file:`redemo.py` can be quite useful when -trying to debug a complicated RE. Phil Schwartz's `Kodos -<http://kodos.sourceforge.net/>`_ is also an interactive tool for developing and -testing RE patterns. +trying to debug a complicated RE. This HOWTO uses the standard Python interpreter for its examples. First, run the Python interpreter, import the :mod:`re` module, and compile a RE:: 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. diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 71d695f..f97eb08 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -454,6 +454,19 @@ Callable types .. tabularcolumns:: |l|L|l| + .. index:: + single: __doc__ (function attribute) + single: __name__ (function attribute) + single: __module__ (function attribute) + single: __dict__ (function attribute) + single: __defaults__ (function attribute) + single: __closure__ (function attribute) + single: __code__ (function attribute) + single: __globals__ (function attribute) + single: __annotations__ (function attribute) + single: __kwdefaults__ (function attribute) + pair: global; namespace + +-------------------------+-------------------------------+-----------+ | Attribute | Meaning | | +=========================+===============================+===========+ @@ -462,10 +475,11 @@ Callable types | | unavailable; not inherited by | | | | subclasses | | +-------------------------+-------------------------------+-----------+ - | :attr:`__name__` | The function's name | Writable | + | :attr:`~definition.\ | The function's name | Writable | + | __name__` | | | +-------------------------+-------------------------------+-----------+ - | :attr:`__qualname__` | The function's | Writable | - | | :term:`qualified name` | | + | :attr:`~definition.\ | The function's | Writable | + | __qualname__` | :term:`qualified name` | | | | | | | | .. versionadded:: 3.3 | | +-------------------------+-------------------------------+-----------+ @@ -489,7 +503,7 @@ Callable types | | module in which the function | | | | was defined. | | +-------------------------+-------------------------------+-----------+ - | :attr:`__dict__` | The namespace supporting | Writable | + | :attr:`~object.__dict__`| The namespace supporting | Writable | | | arbitrary function | | | | attributes. | | +-------------------------+-------------------------------+-----------+ @@ -519,19 +533,6 @@ Callable types Additional information about a function's definition can be retrieved from its code object; see the description of internal types below. - .. index:: - single: __doc__ (function attribute) - single: __name__ (function attribute) - single: __module__ (function attribute) - single: __dict__ (function attribute) - single: __defaults__ (function attribute) - single: __closure__ (function attribute) - single: __code__ (function attribute) - single: __globals__ (function attribute) - single: __annotations__ (function attribute) - single: __kwdefaults__ (function attribute) - pair: global; namespace - Instance methods .. index:: object: method @@ -550,7 +551,7 @@ Callable types Special read-only attributes: :attr:`__self__` is the class instance object, :attr:`__func__` is the function object; :attr:`__doc__` is the method's - documentation (same as ``__func__.__doc__``); :attr:`__name__` is the + documentation (same as ``__func__.__doc__``); :attr:`~definition.__name__` is the method name (same as ``__func__.__name__``); :attr:`__module__` is the name of the module the method was defined in, or ``None`` if unavailable. @@ -637,7 +638,7 @@ Callable types standard built-in module). The number and type of the arguments are determined by the C function. Special read-only attributes: :attr:`__doc__` is the function's documentation string, or ``None`` if - unavailable; :attr:`__name__` is the function's name; :attr:`__self__` is + unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is set to ``None`` (but see the next item); :attr:`__module__` is the name of the module the function was defined in or ``None`` if unavailable. @@ -687,7 +688,7 @@ Modules .. index:: single: __dict__ (module attribute) - Special read-only attribute: :attr:`__dict__` is the module's namespace as a + Special read-only attribute: :attr:`~object.__dict__` is the module's namespace as a dictionary object. .. impl-detail:: @@ -743,7 +744,7 @@ Custom classes method object, it is transformed into the object wrapped by the static method object. See section :ref:`descriptors` for another way in which attributes retrieved from a class may differ from those actually contained in its - :attr:`__dict__`. + :attr:`~object.__dict__`. .. index:: triple: class; attribute; assignment @@ -761,8 +762,8 @@ Custom classes single: __bases__ (class attribute) single: __doc__ (class attribute) - Special attributes: :attr:`__name__` is the class name; :attr:`__module__` is - the module name in which the class was defined; :attr:`__dict__` is the + Special attributes: :attr:`~definition.__name__` is the class name; :attr:`__module__` is + the module name in which the class was defined; :attr:`~object.__dict__` is the dictionary containing the class's namespace; :attr:`~class.__bases__` is a tuple (possibly empty or a singleton) containing the base classes, in the order of their occurrence in the base class list; :attr:`__doc__` is the @@ -785,7 +786,7 @@ Class instances class method objects are also transformed; see above under "Classes". See section :ref:`descriptors` for another way in which attributes of a class retrieved via its instances may differ from the objects actually stored in - the class's :attr:`__dict__`. If no class attribute is found, and the + the class's :attr:`~object.__dict__`. If no class attribute is found, and the object's class has a :meth:`__getattr__` method, that is called to satisfy the lookup. @@ -1466,7 +1467,7 @@ method (a so-called *descriptor* class) appears in an *owner* class (the descriptor must be in either the owner's class dictionary or in the class dictionary for one of its parents). In the examples below, "the attribute" refers to the attribute whose name is the key of the property in the owner -class' :attr:`__dict__`. +class' :attr:`~object.__dict__`. .. method:: object.__get__(self, instance, owner) diff --git a/Doc/tools/extensions/suspicious.py b/Doc/tools/extensions/suspicious.py index d3ed849..0a70e57 100644 --- a/Doc/tools/extensions/suspicious.py +++ b/Doc/tools/extensions/suspicious.py @@ -270,5 +270,5 @@ class SuspiciousVisitor(nodes.GenericNodeVisitor): # ignore comments -- too much false positives. # (although doing this could miss some errors; # there were two sections "commented-out" by mistake - # in the Python docs that would not be catched) + # in the Python docs that would not be caught) raise nodes.SkipNode diff --git a/Doc/tutorial/classes.rst b/Doc/tutorial/classes.rst index 2489d75..03b77e0 100644 --- a/Doc/tutorial/classes.rst +++ b/Doc/tutorial/classes.rst @@ -951,8 +951,8 @@ Examples:: .. rubric:: Footnotes .. [#] Except for one thing. Module objects have a secret read-only attribute called - :attr:`__dict__` which returns the dictionary used to implement the module's - namespace; the name :attr:`__dict__` is an attribute but not a global name. + :attr:`~object.__dict__` which returns the dictionary used to implement the module's + namespace; the name :attr:`~object.__dict__` is an attribute but not a global name. Obviously, using this violates the abstraction of namespace implementation, and should be restricted to things like post-mortem debuggers. diff --git a/Doc/whatsnew/2.0.rst b/Doc/whatsnew/2.0.rst index 87462f3..4d49af1 100644 --- a/Doc/whatsnew/2.0.rst +++ b/Doc/whatsnew/2.0.rst @@ -506,7 +506,7 @@ arguments and/or a dictionary of keyword arguments. In Python 1.5 and earlier, you'd use the :func:`apply` built-in function: ``apply(f, args, kw)`` calls the function :func:`f` with the argument tuple *args* and the keyword arguments in the dictionary *kw*. :func:`apply` is the same in 2.0, but thanks to a patch -from Greg Ewing, ``f(*args, **kw)`` as a shorter and clearer way to achieve the +from Greg Ewing, ``f(*args, **kw)`` is a shorter and clearer way to achieve the same effect. This syntax is symmetrical with the syntax for defining functions:: diff --git a/Doc/whatsnew/2.1.rst b/Doc/whatsnew/2.1.rst index e55eaac..06366b8 100644 --- a/Doc/whatsnew/2.1.rst +++ b/Doc/whatsnew/2.1.rst @@ -442,8 +442,8 @@ Python syntax:: f.grammar = "A ::= B (C D)*" The dictionary containing attributes can be accessed as the function's -:attr:`__dict__`. Unlike the :attr:`__dict__` attribute of class instances, in -functions you can actually assign a new dictionary to :attr:`__dict__`, though +:attr:`~object.__dict__`. Unlike the :attr:`~object.__dict__` attribute of class instances, in +functions you can actually assign a new dictionary to :attr:`~object.__dict__`, though the new value is restricted to a regular Python dictionary; you *can't* be tricky and set it to a :class:`UserDict` instance, or any other random object that behaves like a mapping. diff --git a/Doc/whatsnew/2.2.rst b/Doc/whatsnew/2.2.rst index 885fd60..4e8d7fa 100644 --- a/Doc/whatsnew/2.2.rst +++ b/Doc/whatsnew/2.2.rst @@ -157,7 +157,7 @@ attributes and methods were supported by an object. There were some informal conventions, such as defining :attr:`__members__` and :attr:`__methods__` attributes that were lists of names, but often the author of an extension type or a class wouldn't bother to define them. You could fall back on inspecting -the :attr:`__dict__` of an object, but when class inheritance or an arbitrary +the :attr:`~object.__dict__` of an object, but when class inheritance or an arbitrary :meth:`__getattr__` hook were in use this could still be inaccurate. The one big idea underlying the new class model is that an API for describing @@ -169,7 +169,7 @@ possible, as well as more exotic constructs. Attribute descriptors are objects that live inside class objects, and have a few attributes of their own: -* :attr:`__name__` is the attribute's name. +* :attr:`~definition.__name__` is the attribute's name. * :attr:`__doc__` is the attribute's docstring. @@ -329,7 +329,7 @@ However, Python 2.2's support for :dfn:`properties` will often be a simpler way to trap attribute references. Writing a :meth:`__getattr__` method is complicated because to avoid recursion you can't use regular attribute accesses inside them, and instead have to mess around with the contents of -:attr:`__dict__`. :meth:`__getattr__` methods also end up being called by Python +:attr:`~object.__dict__`. :meth:`__getattr__` methods also end up being called by Python when it checks for other methods such as :meth:`__repr__` or :meth:`__coerce__`, and so have to be written with this in mind. Finally, calling a function on every attribute access results in a sizable performance loss. @@ -357,15 +357,15 @@ write:: That is certainly clearer and easier to write than a pair of :meth:`__getattr__`/:meth:`__setattr__` methods that check for the :attr:`size` attribute and handle it specially while retrieving all other attributes from the -instance's :attr:`__dict__`. Accesses to :attr:`size` are also the only ones +instance's :attr:`~object.__dict__`. Accesses to :attr:`size` are also the only ones which have to perform the work of calling a function, so references to other attributes run at their usual speed. Finally, it's possible to constrain the list of attributes that can be -referenced on an object using the new :attr:`__slots__` class attribute. Python +referenced on an object using the new :attr:`~object.__slots__` class attribute. Python objects are usually very dynamic; at any time it's possible to define a new attribute on an instance by just doing ``obj.new_attr=1``. A new-style class -can define a class attribute named :attr:`__slots__` to limit the legal +can define a class attribute named :attr:`~object.__slots__` to limit the legal attributes to a particular set of names. An example will make this clear:: >>> class C(object): @@ -383,7 +383,7 @@ attributes to a particular set of names. An example will make this clear:: AttributeError: 'C' object has no attribute 'newattr' Note how you get an :exc:`AttributeError` on the attempt to assign to an -attribute not listed in :attr:`__slots__`. +attribute not listed in :attr:`~object.__slots__`. .. _sect-rellinks: diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst index b8cdcf1..fe8368e 100644 --- a/Doc/whatsnew/2.3.rst +++ b/Doc/whatsnew/2.3.rst @@ -1111,10 +1111,10 @@ Here are all of the changes that Python 2.3 makes to the core Python language. <type '_socket.socket'> * One of the noted incompatibilities between old- and new-style classes has been - removed: you can now assign to the :attr:`__name__` and :attr:`__bases__` + removed: you can now assign to the :attr:`~definition.__name__` and :attr:`~class.__bases__` attributes of new-style classes. There are some restrictions on what can be - assigned to :attr:`__bases__` along the lines of those relating to assigning to - an instance's :attr:`__class__` attribute. + assigned to :attr:`~class.__bases__` along the lines of those relating to assigning to + an instance's :attr:`~instance.__class__` attribute. .. ====================================================================== @@ -1920,7 +1920,7 @@ Changes to Python's build process and to the C API include: * If you dynamically allocate type objects in your extension, you should be aware of a change in the rules relating to the :attr:`__module__` and - :attr:`__name__` attributes. In summary, you will want to ensure the type's + :attr:`~definition.__name__` attributes. In summary, you will want to ensure the type's dictionary contains a ``'__module__'`` key; making the module name the part of the type name leading up to the final period will no longer have the desired effect. For more detail, read the API reference documentation or the source. diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst index 044d7be..f53e4f8 100644 --- a/Doc/whatsnew/3.0.rst +++ b/Doc/whatsnew/3.0.rst @@ -783,8 +783,8 @@ Operators And Special Methods :attr:`func_closure`, :attr:`func_code`, :attr:`func_defaults`, :attr:`func_dict`, :attr:`func_doc`, :attr:`func_globals`, :attr:`func_name` were renamed to :attr:`__closure__`, - :attr:`__code__`, :attr:`__defaults__`, :attr:`__dict__`, - :attr:`__doc__`, :attr:`__globals__`, :attr:`__name__`, + :attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`, + :attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`, respectively. * :meth:`__nonzero__` is now :meth:`__bool__`. |