merge heads

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`

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)
 
@@ -267,14 +271,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])
@@ -688,6 +695,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 +717,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 +1091,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 +1216,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 <textseq>` 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 +1240,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 +1319,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 +1352,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])
 

Doc/library/stdtypes.rst

@@ -2953,33 +2953,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])
+.. class:: dict(**kwarg)
+           dict(mapping, **kwarg)
+           dict(iterable, **kwarg)
 
-   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
+   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

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: