[Python-checkins] r56827 - doctools/trunk/Doc-26/library/calendar.rst doctools/trunk/Doc-26/library/collections.rst doctools/trunk/Doc-26/library/datetime.rst doctools/trunk/Doc-26/library/functions.rst doctools/trunk/Doc-26/library/os.path.rst doctools/trunk/Doc-26/library/os.rst doctools/trunk/Doc-26/library/stdtypes.rst doctools/trunk/Doc-26/library/sys.rst doctools/trunk/Doc-26/library/time.rst
mark.summerfield
python-checkins at python.org
Wed Aug 8 13:10:09 CEST 2007
Author: mark.summerfield
Date: Wed Aug 8 13:10:08 2007
New Revision: 56827
Modified:
doctools/trunk/Doc-26/library/calendar.rst
doctools/trunk/Doc-26/library/collections.rst
doctools/trunk/Doc-26/library/datetime.rst
doctools/trunk/Doc-26/library/functions.rst
doctools/trunk/Doc-26/library/os.path.rst
doctools/trunk/Doc-26/library/os.rst
doctools/trunk/Doc-26/library/stdtypes.rst
doctools/trunk/Doc-26/library/sys.rst
doctools/trunk/Doc-26/library/time.rst
Log:
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.
Modified: doctools/trunk/Doc-26/library/calendar.rst
==============================================================================
--- doctools/trunk/Doc-26/library/calendar.rst (original)
+++ doctools/trunk/Doc-26/library/calendar.rst Wed Aug 8 13:10:08 2007
@@ -13,7 +13,8 @@
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
Modified: doctools/trunk/Doc-26/library/collections.rst
==============================================================================
--- doctools/trunk/Doc-26/library/collections.rst (original)
+++ doctools/trunk/Doc-26/library/collections.rst Wed Aug 8 13:10:08 2007
@@ -13,10 +13,10 @@
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.
Modified: doctools/trunk/Doc-26/library/datetime.rst
==============================================================================
--- doctools/trunk/Doc-26/library/datetime.rst (original)
+++ doctools/trunk/Doc-26/library/datetime.rst Wed Aug 8 13:10:08 2007
@@ -16,7 +16,8 @@
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
Modified: doctools/trunk/Doc-26/library/functions.rst
==============================================================================
--- doctools/trunk/Doc-26/library/functions.rst (original)
+++ doctools/trunk/Doc-26/library/functions.rst Wed Aug 8 13:10:08 2007
@@ -245,8 +245,10 @@
.. 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])
@@ -326,7 +328,7 @@
``(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
@@ -457,7 +459,9 @@
: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
@@ -616,7 +620,9 @@
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()
@@ -761,6 +767,8 @@
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.
@@ -988,7 +996,9 @@
: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
@@ -1130,7 +1140,10 @@
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)
Modified: doctools/trunk/Doc-26/library/os.path.rst
==============================================================================
--- doctools/trunk/Doc-26/library/os.path.rst (original)
+++ doctools/trunk/Doc-26/library/os.path.rst Wed Aug 8 13:10:08 2007
@@ -8,7 +8,9 @@
.. 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::
Modified: doctools/trunk/Doc-26/library/os.rst
==============================================================================
--- doctools/trunk/Doc-26/library/os.rst (original)
+++ doctools/trunk/Doc-26/library/os.rst Wed Aug 8 13:10:08 2007
@@ -9,7 +9,8 @@
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
Modified: doctools/trunk/Doc-26/library/stdtypes.rst
==============================================================================
--- doctools/trunk/Doc-26/library/stdtypes.rst (original)
+++ doctools/trunk/Doc-26/library/stdtypes.rst Wed Aug 8 13:10:08 2007
@@ -492,6 +492,10 @@
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
@@ -503,20 +507,22 @@
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.
@@ -655,9 +661,9 @@
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()
@@ -1406,6 +1412,9 @@
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
@@ -1581,12 +1590,19 @@
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:
@@ -1611,19 +1627,16 @@
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}.items())``
+ * ``dict(one=2, two=3)``
- * ``dict({'one': 2, 'two': 3}.iteritems())``
+ * ``dict({'one': 2, 'two': 3})``
* ``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
Modified: doctools/trunk/Doc-26/library/sys.rst
==============================================================================
--- doctools/trunk/Doc-26/library/sys.rst (original)
+++ doctools/trunk/Doc-26/library/sys.rst Wed Aug 8 13:10:08 2007
@@ -19,6 +19,9 @@
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
Modified: doctools/trunk/Doc-26/library/time.rst
==============================================================================
--- doctools/trunk/Doc-26/library/time.rst (original)
+++ doctools/trunk/Doc-26/library/time.rst Wed Aug 8 13:10:08 2007
@@ -6,8 +6,11 @@
: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.
More information about the Python-checkins
mailing list