Anonymous avatar Anonymous committed 45447ff

Merge latest two revs, write about.

Comments (0)

Files changed (16)

 anyone else should be on this list, please let us know (send email to
 docs@python.org), and we'll be glad to correct the problem.
 
-It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- Thank You!
-
-
 * Aahz
 * Michael Abbott
 * Steve Alexander
 * Robin Boerdijk
 * Michal Bozon
 * Aaron Brancotti
+* Georg Brandl
 * Keith Briggs
 * Lee Busby
 * Lorenzo M. Catucci
+* Carl Cerecke
 * Mauro Cicognini
 * Gilles Civario
 * Mike Clarkson
 
 * split very large files and add toctrees
 * find out which files get "comments disabled" metadata
-* write "About these documents"
 * finish "Documenting Python"
 docs@python.org mailing list.  We're always looking for volunteers wanting
 to help with the docs, so feel free to send a mail there!
 
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `docutils <http://docutils.sf.net/>`_ project for creating
+  reStructuredText and the docutils suite;
+* Fredrik Lundh for his `Alternative Python Reference
+  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
+  ideas.
+
 See :ref:`reporting-bugs` for information how to report bugs in Python itself.
 
-.. % include the ACKS file here so that it can be maintained separately
+.. including the ACKS file here so that it can be maintained separately
+.. include:: ACKS
 
-.. include:: ACKS
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!
 anyone else should be on this list, please let us know (send email to
 docs@python.org), and we'll be glad to correct the problem.
 
-It is only with the input and contributions of the Python community
-that Python has such wonderful documentation -- Thank You!
-
-
 * Aahz
 * Michael Abbott
 * Steve Alexander
 * Robin Boerdijk
 * Michal Bozon
 * Aaron Brancotti
+* Georg Brandl
 * Keith Briggs
 * Lee Busby
 * Lorenzo M. Catucci
+* Carl Cerecke
 * Mauro Cicognini
 * Gilles Civario
 * Mike Clarkson
 
 * split very large files and add toctrees
 * find out which files get "comments disabled" metadata
-* write "About these documents"
 * finish "Documenting Python"
 docs@python.org mailing list.  We're always looking for volunteers wanting
 to help with the docs, so feel free to send a mail there!
 
+Many thanks go to:
+
+* Fred L. Drake, Jr., the creator of the original Python documentation toolset
+  and writer of much of the content;
+* the `docutils <http://docutils.sf.net/>`_ project for creating
+  reStructuredText and the docutils suite;
+* Fredrik Lundh for his `Alternative Python Reference
+  <http://effbot.org/zone/pyref.htm>`_ project from which Sphinx got many good
+  ideas.
+
 See :ref:`reporting-bugs` for information how to report bugs in Python itself.
 
-.. % include the ACKS file here so that it can be maintained separately
+.. including the ACKS file here so that it can be maintained separately
+.. include:: ACKS
 
-.. include:: ACKS
+It is only with the input and contributions of the Python community
+that Python has such wonderful documentation -- Thank You!

Doc-3k/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-3k/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-3k/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-3k/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-3k/library/index.rst

    strings.rst
    datatypes.rst
    numeric.rst
+   filesys.rst
+   persistence.rst
+   archiving.rst
+   fileformats.rst
+   crypto.rst
+   allos.rst
+   someos.rst
+   ipc.rst
    netdata.rst
    markup.rst
-   fileformats.rst
-   crypto.rst
-   filesys.rst
-   archiving.rst
-   persistence.rst
-   allos.rst
-   someos.rst
-   unix.rst
-   ipc.rst
    internet.rst
    mm.rst
-   tk.rst
    i18n.rst
    frameworks.rst
+   tk.rst
    development.rst
    pdb.rst
    profile.rst
    language.rst
    misc.rst
    windows.rst
+   unix.rst
    undoc.rst

Doc-3k/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-3k/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-3k/library/stdtypes.rst

 
 There are six sequence types: strings, Unicode strings, lists, tuples, buffers,
 and range 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: string
-   object: Unicode
    object: tuple
    object: list
    object: buffer
    object: range
 
 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.  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 range are similar to buffers in that there is no specific syntax to
 create them, but they are created using the :func:`range` 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-3k/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-3k/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.