From 801985e4b7bb0dd0fdef446e5b5d6d59484b7170 Mon Sep 17 00:00:00 2001 From: Nadeem Vawda Date: Sat, 13 Oct 2012 04:26:49 +0200 Subject: lzma module: Rewrap docstrings at 72 columns, as per PEP 8. --- Lib/lzma.py | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/Lib/lzma.py b/Lib/lzma.py index 1a1b065..13603ef 100644 --- a/Lib/lzma.py +++ b/Lib/lzma.py @@ -55,7 +55,7 @@ class LZMAFile(io.BufferedIOBase): be an existing file object to read from or write to. mode can be "r" for reading (default), "w" for (over)writing, or - "a" for appending. These can equivalently be given as "rb", "wb", + "a" for appending. These can equivalently be given as "rb", "wb" and "ab" respectively. format specifies the container format to use for the file. @@ -381,23 +381,24 @@ def open(filename, mode="rb", *, encoding=None, errors=None, newline=None): """Open an LZMA-compressed file in binary or text mode. - filename can be either an actual file name (given as a str or bytes object), - in which case the named file is opened, or it can be an existing file object - to read from or write to. + filename can be either an actual file name (given as a str or bytes + object), in which case the named file is opened, or it can be an + existing file object to read from or write to. - The mode argument can be "r", "rb" (default), "w", "wb", "a", or "ab" for - binary mode, or "rt", "wt" or "at" for text mode. + The mode argument can be "r", "rb" (default), "w", "wb", "a" or "ab" + for binary mode, or "rt", "wt" or "at" for text mode. - The format, check, preset and filters arguments specify the compression - settings, as for LZMACompressor, LZMADecompressor and LZMAFile. + The format, check, preset and filters arguments specify the + compression settings, as for LZMACompressor, LZMADecompressor and + LZMAFile. - For binary mode, this function is equivalent to the LZMAFile constructor: - LZMAFile(filename, mode, ...). In this case, the encoding, errors and - newline arguments must not be provided. + For binary mode, this function is equivalent to the LZMAFile + constructor: LZMAFile(filename, mode, ...). In this case, the + encoding, errors and newline arguments must not be provided. For text mode, a LZMAFile object is created, and wrapped in an - io.TextIOWrapper instance with the specified encoding, error handling - behavior, and line ending(s). + io.TextIOWrapper instance with the specified encoding, error + handling behavior, and line ending(s). """ if "t" in mode: @@ -427,7 +428,7 @@ def compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None): Refer to LZMACompressor's docstring for a description of the optional arguments *format*, *check*, *preset* and *filters*. - For incremental compression, use an LZMACompressor object instead. + For incremental compression, use an LZMACompressor instead. """ comp = LZMACompressor(format, check, preset, filters) return comp.compress(data) + comp.flush() @@ -439,7 +440,7 @@ def decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None): Refer to LZMADecompressor's docstring for a description of the optional arguments *format*, *check* and *filters*. - For incremental decompression, use a LZMADecompressor object instead. + For incremental decompression, use an LZMADecompressor instead. """ results = [] while True: -- cgit v0.12 From 006d907afc138a99869481c198eaf39a918df99d Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Fri, 12 Oct 2012 20:28:26 -0700 Subject: Undo changes accidentally reverted in de8787029fe4. --- Doc/howto/functional.rst | 5 +++-- Doc/library/functions.rst | 25 ++++++++++++++++--------- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/Doc/howto/functional.rst b/Doc/howto/functional.rst index ebbb229..b621a84 100644 --- a/Doc/howto/functional.rst +++ b/Doc/howto/functional.rst @@ -292,13 +292,14 @@ ordering of the objects in the dictionary. Applying :func:`iter` to a dictionary always loops over the keys, but dictionaries have methods that return other iterators. If you want to iterate over values or key/value pairs, you can explicitly call the -:meth:`~dict.values` or :meth:`~dict.items` methods to get an appropriate iterator. +:meth:`~dict.values` or :meth:`~dict.items` methods to get an appropriate +iterator. The :func:`dict` constructor can accept an iterator that returns a finite stream of ``(key, value)`` tuples: >>> L = [('Italy', 'Rome'), ('France', 'Paris'), ('US', 'Washington DC')] - >>> dict(iter(L)) + >>> dict(iter(L)) #doctest: +SKIP {'Italy': 'Rome', 'US': 'Washington DC', 'France': 'Paris'} Files also support iteration by calling the :meth:`~io.TextIOBase.readline` diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 173baf4..f782655 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -122,6 +122,8 @@ are always available. They are listed here in alphabetical order. Without an argument, an array of size 0 is created. + See also :ref:`binaryseq` and :ref:`typebytearray`. + .. _func-bytes: .. function:: bytes([source[, encoding[, errors]]]) @@ -135,6 +137,8 @@ are always available. They are listed here in alphabetical order. Bytes objects can also be created with literals, see :ref:`strings`. + See also :ref:`binaryseq`, :ref:`typebytes`, and :ref:`bytes-methods`. + .. function:: callable(object) @@ -688,6 +692,8 @@ are always available. They are listed here in alphabetical order. *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will be returned. + See also :ref:`typeiter`. + One useful application of the second form of :func:`iter` is to read lines of a file until a certain line is reached. The following example reads a file until the :meth:`readline` method returns an empty string:: @@ -708,7 +714,7 @@ are always available. They are listed here in alphabetical order. :noindex: Rather than being a function, :class:`list` is actually a mutable - sequence type, as documented in :ref:`typesseq`. + sequence type, as documented in :ref:`typesseq-list` and :ref:`typesseq`. .. function:: locals() @@ -1082,7 +1088,7 @@ are always available. They are listed here in alphabetical order. :noindex: Rather than being a function, :class:`range` is actually an immutable - sequence type, as documented in :ref:`typesseq`. + sequence type, as documented in :ref:`typesseq-range` and :ref:`typesseq`. .. function:: repr(object) @@ -1207,7 +1213,8 @@ are always available. They are listed here in alphabetical order. .. function:: str(object='') str(object[, encoding[, errors]]) - Return a string version of an object, using one of the following modes: + Return a :ref:`string ` version of an object, using one of the + following modes: If *encoding* and/or *errors* are given, :func:`str` will decode the *object* which can either be a byte string or a character buffer using @@ -1230,11 +1237,9 @@ are always available. They are listed here in alphabetical order. Objects can specify what ``str(object)`` returns by defining a :meth:`__str__` special method. - For more information on strings see :ref:`typesseq` which describes sequence - functionality (strings are sequences), and also the string-specific methods - described in the :ref:`string-methods` section. To output formatted strings, - see the :ref:`string-formatting` section. In addition see the - :ref:`stringservices` section. + For more information on strings and string methods, see the :ref:`textseq` + section. To output formatted strings, see the :ref:`string-formatting` + section. In addition, see the :ref:`stringservices` section. .. function:: sum(iterable[, start]) @@ -1311,7 +1316,7 @@ are always available. They are listed here in alphabetical order. :noindex: Rather than being a function, :class:`tuple` is actually an immutable - sequence type, as documented in :ref:`typesseq`. + sequence type, as documented in :ref:`typesseq-tuple` and :ref:`typesseq`. .. function:: type(object) @@ -1344,6 +1349,8 @@ are always available. They are listed here in alphabetical order. ... >>> X = type('X', (object,), dict(a=1)) + See also :ref:`bltin-type-objects`. + .. function:: vars([object]) -- cgit v0.12 From f341317185ef7ec6d0cfb2ca93c9d253c3c75305 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Sat, 13 Oct 2012 03:22:33 -0700 Subject: Issue #16206: Improve the documentation of the dict constructor. This change includes replacing the single-line signature documentation with a more complete multiple-line signature. --- Doc/library/functions.rst | 13 +++++++----- Doc/library/stdtypes.rst | 54 +++++++++++++++++++++++++++-------------------- 2 files changed, 39 insertions(+), 28 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 572706a..b7d7e08 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -266,14 +266,17 @@ are always available. They are listed here in alphabetical order. .. _func-dict: -.. function:: dict([arg]) +.. function:: dict(**kwarg) + dict(mapping, **kwarg) + dict(iterable, **kwarg) :noindex: - Create a new data dictionary, optionally with items taken from *arg*. - The dictionary type is described in :ref:`typesmapping`. + Create a new dictionary. The :class:`dict` object is the dictionary class. + See :class:`dict` and :ref:`typesmapping` for documentation about this + class. - For other containers see the built in :class:`list`, :class:`set`, and - :class:`tuple` classes, and the :mod:`collections` module. + For other containers see the built-in :class:`list`, :class:`set`, and + :class:`tuple` classes, as well as the :mod:`collections` module. .. function:: dir([object]) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 7d47ec7..20174c5 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2114,33 +2114,41 @@ Dictionaries can be created by placing a comma-separated list of ``key: value`` pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: 'jack', 4127: 'sjoerd'}``, or by the :class:`dict` constructor. -.. class:: dict([arg]) - - Return a new dictionary initialized from an optional positional argument or - from a set of keyword arguments. If no arguments are given, return a new - empty dictionary. If the positional argument *arg* is a mapping object, - return a dictionary mapping the same keys to the same values as does the - mapping object. Otherwise the positional argument must be a sequence, a - container that supports iteration, or an iterator object. The elements of - the argument must each also be of one of those kinds, and each must in turn - contain exactly two objects. The first is used as a key in the new - dictionary, and the second as the key's value. If a given key is seen more - than once, the last value associated with it is retained in the new +.. class:: dict(**kwarg) + dict(mapping, **kwarg) + dict(iterable, **kwarg) + + Return a new dictionary initialized from an optional positional argument + and a possibly empty set of keyword arguments. + + If no positional argument is given, an empty dictionary is created. + If a positional argument is given and it is a mapping object, a dictionary + is created with the same key-value pairs as the mapping object. Otherwise, + the positional argument must be an :term:`iterator` object. Each item in + the iterable must itself be an iterator with exactly two objects. The + first object of each item becomes a key in the new dictionary, and the + second object the corresponding value. If a key occurs more than once, the + last value for that key becomes the corresponding value in the new dictionary. - If keyword arguments are given, the keywords themselves with their associated - values are added as items to the dictionary. If a key is specified both in - the positional argument and as a keyword argument, the value associated with - the keyword is retained in the dictionary. For example, these all return a - dictionary equal to ``{"one": 1, "two": 2}``: + If keyword arguments are given, the keyword arguments and their values are + added to the dictionary created from the positional argument. If a key + being added is already present, the value from the keyword argument + replaces the value from the positional argument. - * ``dict(one=1, two=2)`` - * ``dict({'one': 1, 'two': 2})`` - * ``dict(zip(('one', 'two'), (1, 2)))`` - * ``dict([['two', 2], ['one', 1]])`` + To illustrate, the following examples all return a dictionary equal to + ``{"one": 1, "two": 2}``:: - The first example only works for keys that are valid Python identifiers; the - others work with any valid keys. + >>> a = dict(one=1, two=2) + >>> b = dict({'one': 1, 'two': 2}) + >>> c = dict(zip(('one', 'two'), (1, 2))) + >>> d = dict([['two', 2], ['one', 1]]) + >>> e = {"one": 1, "two": 2} + >>> a == b == c == d == e + True + + Providing keyword arguments as in the first example only works for keys that + are valid Python identifiers. Otherwise, any valid keys can be used. These are the operations that dictionaries support (and therefore, custom -- cgit v0.12