Anonymous avatar Anonymous committed fa37c13

Added more cross-references between containers & regarding strings.
Deleted some of the dict constructor examples to avoid confusing
newcomers.
Added mild warning about using float keys for dicts.
Added cross-references between time, datetime, and calendar.
Added other cross-references.

Comments (0)

Files changed (9)

Doc-26/library/calendar.rst

 these calendars have Monday as the first day of the week, and Sunday as the last
 (the European convention). Use :func:`setfirstweekday` to set the first day of
 the week to Sunday (6) or to any other weekday.  Parameters that specify dates
-are given as integers.
+are given as integers. For related
+functionality, see also the :mod:`datetime` and :mod:`time` modules.
 
 Most of these functions and classses rely on the :mod:`datetime` module which
 uses an idealized calendar, the current Gregorian calendar indefinitely extended

Doc-26/library/collections.rst

 This module implements high-performance container datatypes.  Currently,
 there are two datatypes, :class:`deque` and :class:`defaultdict`, and
 one datatype factory function, :func:`NamedTuple`. Python already
-includes built-in containers, :func:`dict`, :func:`list`, and
-:func:`tuple`. The optional :mod:`bsddb` module has a :meth:`btopen`
-method that can be used to create in-memory or file based ordered
-dictionaries with string keys.
+includes built-in containers, :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple`. In addition, the optional :mod:`bsddb`
+module has a :meth:`bsddb.btopen` method that can be used to create in-memory
+or file based ordered dictionaries with string keys.
 
 Future editions of the standard library may include balanced trees and
 ordered dictionaries.

Doc-26/library/datetime.rst

 The :mod:`datetime` module supplies classes for manipulating dates and times in
 both simple and complex ways.  While date and time arithmetic is supported, the
 focus of the implementation is on efficient member extraction for output
-formatting and manipulation.
+formatting and manipulation. For related
+functionality, see also the :mod:`time` and :mod:`calendar` modules.
 
 There are two kinds of date and time objects: "naive" and "aware". This
 distinction refers to whether the object has any notion of time zone, daylight

Doc-26/library/functions.rst

 .. function:: dict([arg])
    :noindex:
 
-   Create a new dictionary.  The dictionary type is described in
-   :ref:`typesmapping`.
+   Create a new data dictionary.  The dictionary type is described in
+   :ref:`typesmapping`. For other containers see the built in
+   :class:`list`, :class:`set`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
 
 .. function:: dir([object])
    ``(1, seq[1])``, ``(2, seq[2])``, .... For example::
 
       >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter')]:
-      >>>	    print i, season
+      >>>     print i, season
       0 Spring
       1 Summer
       2 Fall
    :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
    set, ``frozenset([])``.
 
-   The frozenset type is described in :ref:`types-set`.
+   The frozenset type is described in :ref:`types-set`. For other containers see the built in
+   :class:`dict`, :class:`list`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
    .. versionadded:: 2.4
 
    returns ``['a', 'b', 'c']`` and ``list( (1, 2, 3) )`` returns ``[1, 2, 3]``.  If
    no argument is given, returns a new empty list, ``[]``.
 
-   :class:`list` is a mutable sequence type, as documented in :ref:`typesseq`.
+   :class:`list` is a mutable sequence type, as documented in
+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
+   :class:`set`, and :class:`tuple` classes, and the :mod:`collections` module.
 
 
 .. function:: locals()
    Python enforces that the mode, after stripping ``'U'``, begins with ``'r'``,
    ``'w'`` or ``'a'``.
 
+   See also the :mod:`fileinput` module.
+
    .. versionchanged:: 2.5
       Restriction on first letter of mode string introduced.
 
    :class:`frozenset` objects.  If *iterable* is not specified, returns a new empty
    set, ``set([])``.
 
-   The set type is described in :ref:`types-set`.
+   The set type is described in :ref:`types-set`. For other containers see the built in
+   :class:`dict`, :class:`list`, and :class:`tuple` classes, and the
+   :mod:`collections` module.
 
    .. versionadded:: 2.4
 
    3])`` returns ``(1, 2, 3)``.  If no argument is given, returns a new empty
    tuple, ``()``.
 
-   :class:`tuple` is a mutable sequence type, as documented in :ref:`typesseq`.
+   :class:`tuple` is an immutable sequence type, as documented in
+   :ref:`typesseq`. For other containers see the built in :class:`dict`,
+   :class:`list`, and :class:`set` classes, and the :mod:`collections` module.
+
 
 .. function:: type(object)
 

Doc-26/library/os.path.rst

 
 .. index:: single: path; operations
 
-This module implements some useful functions on pathnames.
+This module implements some useful functions on pathnames. To read or
+write files see :func:`open`, and for accessing the filesystem see the
+:mod:`os` module.
 
 .. warning::
 

Doc-26/library/os.rst

 This module provides a more portable way of using operating system dependent
 functionality than importing a operating system dependent built-in module like
 :mod:`posix` or :mod:`nt`. (If you just want to read or write a file see
-:func:`open`.)
+:func:`open`, and if you want to manipulate paths, see the :mod:`os.path`
+module.)
 
 This module searches for an operating system dependent built-in module like
 :mod:`mac` or :mod:`posix` and exports the same functions and data as found

Doc-26/library/stdtypes.rst

 
 There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
 and xrange objects.
+(For other containers see the built in :class:`dict`, :class:`list`,
+:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
+module.)
+
 
 .. index::
    object: sequence
    object: xrange
 
 String literals are written in single or double quotes: ``'xyzzy'``,
-``"frobozz"``.  See :ref:`strings` for more about string literals.  Unicode
-strings are much like strings, but are specified in the syntax using a preceding
-``'u'`` character: ``u'abc'``, ``u"def"``.  Lists are constructed with square
-brackets, separating items with commas: ``[a, b, c]``.  Tuples are constructed
-by the comma operator (not within square brackets), with or without enclosing
-parentheses, but an empty tuple must have the enclosing parentheses, such as
-``a, b, c`` or ``()``.  A single item tuple must have a trailing comma, such as
-``(d,)``.
+``"frobozz"``.  See :ref:`strings` for more about string literals.
+Unicode strings are much like strings, but are specified in the syntax
+using a preceding ``'u'`` character: ``u'abc'``, ``u"def"``. In addition
+to the functionality described here, there are also string-specific
+methods described in the :ref:`string-methods` section. Lists are
+constructed with square brackets, separating items with commas: ``[a, b, c]``.
+Tuples are constructed by the comma operator (not within square
+brackets), with or without enclosing parentheses, but an empty tuple
+must have the enclosing parentheses, such as ``a, b, c`` or ``()``.  A
+single item tuple must have a trailing comma, such as ``(d,)``.
 
 Buffer objects are not directly supported by Python syntax, but can be created
 by calling the builtin function :func:`buffer`.  They don't support
 concatenation or repetition.
 
-Xrange objects are similar to buffers in that there is no specific syntax to
+Objects of type xrange are similar to buffers in that there is no specific syntax to
 create them, but they are created using the :func:`xrange` function.  They don't
 support slicing, concatenation or repetition, and using ``in``, ``not in``,
 :func:`min` or :func:`max` on them is inefficient.
 
 Below are listed the string methods which both 8-bit strings and Unicode objects
 support. In addition, Python's strings support the sequence type methods
-described in the :ref:`typesseq` section (above). To output formatted strings
+described in the :ref:`typesseq` section. To output formatted strings
 use template strings or the ``%`` operator described in the
-:ref:`string-formatting` section (below). Also, see the :mod:`re` module for
+:ref:`string-formatting` section. Also, see the :mod:`re` module for
 string functions based on regular expressions.
 
 .. method:: str.capitalize()
 Common uses include membership testing, removing duplicates from a sequence, and
 computing mathematical operations such as intersection, union, difference, and
 symmetric difference.
+(For other containers see the built in :class:`dict`, :class:`list`,
+and :class:`tuple` classes, and the :mod:`collections` module.)
+
 
 .. versionadded:: 2.4
 
 
 A :dfn:`mapping` object maps immutable values to arbitrary objects.  Mappings
 are mutable objects.  There is currently only one standard mapping type, the
-:dfn:`dictionary`.  A dictionary's keys are *almost* arbitrary values.  Only
+:dfn:`dictionary`.
+(For other containers see the built in :class:`list`,
+:class:`set`, and :class:`tuple` classes, and the :mod:`collections`
+module.)
+
+A dictionary's keys are *almost* arbitrary values.  Only
 values containing lists, dictionaries or other mutable types (that are compared
 by value rather than by object identity) may not be used as keys. Numeric types
 used for keys obey the normal rules for numeric comparison: if two numbers
 compare equal (such as ``1`` and ``1.0``) then they can be used interchangeably
-to index the same dictionary entry.
+to index the same dictionary entry. (Note however, that since computers
+store floating-point numbers as approximations it is usually unwise to
+use them as dictionary keys.)
 
 Dictionaries can be created by placing a comma-separated list of ``key: value``
 pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098:
    keyword is retained in the dictionary. For example, these all return a
    dictionary equal to ``{"one": 2, "two": 3}``:
 
+   * ``dict(one=2, two=3)``
+
    * ``dict({'one': 2, 'two': 3})``
 
-   * ``dict({'one': 2, 'two': 3}.items())``
-
-   * ``dict({'one': 2, 'two': 3}.iteritems())``
-
    * ``dict(zip(('one', 'two'), (2, 3)))``
 
    * ``dict([['two', 3], ['one', 2]])``
 
-   * ``dict(one=2, two=3)``
-
-   * ``dict([(['one', 'two'][i-2], i) for i in (2, 3)])``
+   The first example only works for keys that are valid Python
+   identifiers; the others work with any valid keys.
 
    .. versionadded:: 2.2
 

Doc-26/library/sys.rst

    the interpreter, ``argv[0]`` is set to the string ``'-c'``.  If no script name
    was passed to the Python interpreter, ``argv[0]`` is the empty string.
 
+   To loop over the standard input, or the list of files given on the
+   command line, see the :mod:`fileinput` module.
+
 
 .. data:: byteorder
 

Doc-26/library/time.rst

    :synopsis: Time access and conversions.
 
 
-This module provides various time-related functions.  It is always available,
-but not all functions are available on all platforms.  Most of the functions
+This module provides various time-related functions. For related
+functionality, see also the :mod:`datetime` and :mod:`calendar` modules.
+
+Although this module is always available,
+not all functions are available on all platforms.  Most of the functions
 defined in this module call platform C library functions with the same name.  It
 may sometimes be helpful to consult the platform documentation, because the
 semantics of these functions varies among platforms.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.