From 6cbb7f945af7bdc988e44a20910d498631f79230 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 17 Jan 2010 08:42:30 +0000 Subject: #7699: improve datetime docs: straightforward linking to strftime/strptime section, mark classmethods as such. --- Doc/library/datetime.rst | 82 +++++++++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 4bfd9a3..44c1cde 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -38,7 +38,6 @@ than rational, and there is no standard suitable for every application. The :mod:`datetime` module exports the following constants: - .. data:: MINYEAR The smallest year number allowed in a :class:`date` or :class:`datetime` object. @@ -63,7 +62,6 @@ The :mod:`datetime` module exports the following constants: Available Types --------------- - .. class:: date :noindex: @@ -133,7 +131,6 @@ Subclass relationships:: A :class:`timedelta` object represents a duration, the difference between two dates or times. - .. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]]) All arguments are optional and default to ``0``. Arguments may be ints, longs, @@ -170,8 +167,8 @@ dates or times. >>> (d.days, d.seconds, d.microseconds) (-1, 86399, 999999) -Class attributes are: +Class attributes are: .. attribute:: timedelta.min @@ -328,16 +325,16 @@ systems. If an argument outside those ranges is given, :exc:`ValueError` is raised. -Other constructors, all class methods: +Other constructors, all class methods: -.. method:: date.today() +.. classmethod:: date.today() Return the current local date. This is equivalent to ``date.fromtimestamp(time.time())``. -.. method:: date.fromtimestamp(timestamp) +.. classmethod:: date.fromtimestamp(timestamp) Return the local date corresponding to the POSIX timestamp, such as is returned by :func:`time.time`. This may raise :exc:`ValueError`, if the timestamp is out @@ -347,15 +344,15 @@ Other constructors, all class methods: timestamp, leap seconds are ignored by :meth:`fromtimestamp`. -.. method:: date.fromordinal(ordinal) +.. classmethod:: date.fromordinal(ordinal) Return the date corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <= date.max.toordinal()``. For any date *d*, ``date.fromordinal(d.toordinal()) == d``. -Class attributes: +Class attributes: .. attribute:: date.min @@ -372,8 +369,8 @@ Class attributes: The smallest possible difference between non-equal date objects, ``timedelta(days=1)``. -Instance attributes (read-only): +Instance attributes (read-only): .. attribute:: date.year @@ -389,6 +386,7 @@ Instance attributes (read-only): Between 1 and the number of days in the given month of the given year. + Supported operations: +-------------------------------+----------------------------------------------+ @@ -441,7 +439,6 @@ objects are considered to be true. Instance methods: - .. method:: date.replace(year, month, day) Return a date with the same value, except for those members given new values by @@ -521,7 +518,8 @@ Instance methods: Return a string representing the date, controlled by an explicit format string. Format codes referring to hours, minutes or seconds will see 0 values. See - section :ref:`strftime-behavior`. + section :ref:`strftime-strptime-behavior`. + Example of counting days to an event:: @@ -588,7 +586,6 @@ both directions; like a time object, :class:`datetime` assumes there are exactly Constructor: - .. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]) The year, month and day arguments are required. *tzinfo* may be ``None``, or an @@ -607,15 +604,14 @@ Constructor: Other constructors, all class methods: - -.. method:: datetime.today() +.. classmethod:: datetime.today() Return the current local datetime, with :attr:`tzinfo` ``None``. This is equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`, :meth:`fromtimestamp`. -.. method:: datetime.now([tz]) +.. classmethod:: datetime.now([tz]) Return the current local date and time. If optional argument *tz* is ``None`` or not specified, this is like :meth:`today`, but, if possible, supplies more @@ -629,14 +625,14 @@ Other constructors, all class methods: See also :meth:`today`, :meth:`utcnow`. -.. method:: datetime.utcnow() +.. classmethod:: datetime.utcnow() Return the current UTC date and time, with :attr:`tzinfo` ``None``. This is like :meth:`now`, but returns the current UTC date and time, as a naive :class:`datetime` object. See also :meth:`now`. -.. method:: datetime.fromtimestamp(timestamp[, tz]) +.. classmethod:: datetime.fromtimestamp(timestamp[, tz]) Return the local date and time corresponding to the POSIX timestamp, such as is returned by :func:`time.time`. If optional argument *tz* is ``None`` or not @@ -657,7 +653,7 @@ Other constructors, all class methods: identical :class:`datetime` objects. See also :meth:`utcfromtimestamp`. -.. method:: datetime.utcfromtimestamp(timestamp) +.. classmethod:: datetime.utcfromtimestamp(timestamp) Return the UTC :class:`datetime` corresponding to the POSIX timestamp, with :attr:`tzinfo` ``None``. This may raise :exc:`ValueError`, if the timestamp is @@ -666,7 +662,7 @@ Other constructors, all class methods: :meth:`fromtimestamp`. -.. method:: datetime.fromordinal(ordinal) +.. classmethod:: datetime.fromordinal(ordinal) Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal, where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 @@ -674,7 +670,7 @@ Other constructors, all class methods: microsecond of the result are all 0, and :attr:`tzinfo` is ``None``. -.. method:: datetime.combine(date, time) +.. classmethod:: datetime.combine(date, time) Return a new :class:`datetime` object whose date members are equal to the given :class:`date` object's, and whose time and :attr:`tzinfo` members are equal to @@ -683,18 +679,18 @@ Other constructors, all class methods: object, its time and :attr:`tzinfo` members are ignored. -.. method:: datetime.strptime(date_string, format) +.. classmethod:: datetime.strptime(date_string, format) Return a :class:`datetime` corresponding to *date_string*, parsed according to *format*. This is equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format can't be parsed by :func:`time.strptime` or if it returns a value which isn't a - time tuple. + time tuple. See section :ref:`strftime-strptime-behavior`. .. versionadded:: 2.5 -Class attributes: +Class attributes: .. attribute:: datetime.min @@ -713,8 +709,8 @@ Class attributes: The smallest possible difference between non-equal :class:`datetime` objects, ``timedelta(microseconds=1)``. -Instance attributes (read-only): +Instance attributes (read-only): .. attribute:: datetime.year @@ -756,6 +752,7 @@ Instance attributes (read-only): The object passed as the *tzinfo* argument to the :class:`datetime` constructor, or ``None`` if none was passed. + Supported operations: +---------------------------------------+-------------------------------+ @@ -829,7 +826,6 @@ all :class:`datetime` objects are considered to be true. Instance methods: - .. method:: datetime.date() Return :class:`date` object with same year, month and day. @@ -1007,7 +1003,8 @@ Instance methods: .. method:: datetime.strftime(format) Return a string representing the date and time, controlled by an explicit format - string. See section :ref:`strftime-behavior`. + string. See section :ref:`strftime-strptime-behavior`. + Examples of working with datetime objects: @@ -1120,7 +1117,6 @@ Using datetime with tzinfo: A time object represents a (local) time of day, independent of any particular day, and subject to adjustment via a :class:`tzinfo` object. - .. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]]) All arguments are optional. *tzinfo* may be ``None``, or an instance of a @@ -1154,8 +1150,8 @@ Class attributes: ``timedelta(microseconds=1)``, although note that arithmetic on :class:`time` objects is not supported. -Instance attributes (read-only): +Instance attributes (read-only): .. attribute:: time.hour @@ -1182,6 +1178,7 @@ Instance attributes (read-only): The object passed as the tzinfo argument to the :class:`time` constructor, or ``None`` if none was passed. + Supported operations: * comparison of :class:`time` to :class:`time`, where *a* is considered less @@ -1204,8 +1201,8 @@ Supported operations: only if, after converting it to minutes and subtracting :meth:`utcoffset` (or ``0`` if that's ``None``), the result is non-zero. -Instance methods: +Instance methods: .. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]]) @@ -1231,7 +1228,7 @@ Instance methods: .. method:: time.strftime(format) Return a string representing the time, controlled by an explicit format string. - See section :ref:`strftime-behavior`. + See section :ref:`strftime-strptime-behavior`. .. method:: time.utcoffset() @@ -1256,6 +1253,7 @@ Instance methods: ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't return ``None`` or a string object. + Example: >>> from datetime import time, tzinfo @@ -1392,6 +1390,7 @@ methods. Exactly which methods are needed depends on the uses made of aware The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`. + These methods are called by a :class:`datetime` or :class:`time` object, in response to their methods of the same names. A :class:`datetime` object passes itself as the argument, and a :class:`time` object passes ``None`` as the @@ -1495,10 +1494,10 @@ other fixed-offset :class:`tzinfo` subclass (such as a class representing only EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)). -.. _strftime-behavior: +.. _strftime-strptime-behavior: -:meth:`strftime` Behavior -------------------------- +:meth:`strftime` and :meth:`strptime` Behavior +---------------------------------------------- :class:`date`, :class:`datetime`, and :class:`time` objects all support a ``strftime(format)`` method, to create a string representing the time under the @@ -1506,9 +1505,14 @@ control of an explicit format string. Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())`` although not all objects support a :meth:`timetuple` method. +Conversely, the :meth:`datetime.strptime` class method creates a +:class:`datetime` object from a string representing a date and time and a +corresponding format string. ``datetime.strptime(date_string, format)`` is +equivalent to ``datetime(*(time.strptime(date_string, format)[0:6]))``. + For :class:`time` objects, the format codes for year, month, and day should not be used, as time objects have no such values. If they're used anyway, ``1900`` -is substituted for the year, and ``0`` for the month and day. +is substituted for the year, and ``1`` for the month and day. For :class:`date` objects, the format codes for hours, minutes, seconds, and microseconds should not be used, as :class:`date` objects have no such @@ -1635,14 +1639,14 @@ platforms. Regardless of platform, years before 1900 cannot be used. Notes: (1) - When used with the :func:`strptime` function, the ``%f`` directive + When used with the :meth:`strptime` method, the ``%f`` directive accepts from one to six digits and zero pads on the right. ``%f`` is an extension to the set of format characters in the C standard (but implemented separately in datetime objects, and therefore always available). (2) - When used with the :func:`strptime` function, the ``%p`` directive only affects + When used with the :meth:`strptime` method, the ``%p`` directive only affects the output hour field if the ``%I`` directive is used to parse the hour. (3) @@ -1650,11 +1654,11 @@ Notes: accounts for leap seconds and the (very rare) double leap seconds. The :mod:`time` module may produce and does accept leap seconds since it is based on the Posix standard, but the :mod:`datetime` module - does not accept leap seconds in :func:`strptime` input nor will it + does not accept leap seconds in :meth:`strptime` input nor will it produce them in :func:`strftime` output. (4) - When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in + When used with the :meth:`strptime` method, ``%U`` and ``%W`` are only used in calculations when the day of the week and the year are specified. (5) -- cgit v0.12