datetime

This package provides a DateTime data type, as known from Zope. Unless you need to communicate with Zope APIs, you're probably better off using Python's built-in datetime module.

Description

.. image:: https://github.com/zopefoundation/DateTime/workflows/tests/badge.svg
        :target: https://github.com/zopefoundation/DateTime/actions?query=workflow%3Atests
        :alt: CI status

.. image:: https://img.shields.io/pypi/v/DateTime.svg
        :target: https://pypi.org/project/DateTime/
        :alt: Current version on PyPI

.. image:: https://img.shields.io/pypi/pyversions/DateTime.svg
        :target: https://pypi.org/project/DateTime/
        :alt: Supported Python versions


DateTime
========

This package provides a DateTime data type, as known from Zope.

Unless you need to communicate with Zope APIs, you're probably better
off using Python's built-in datetime module.

For further documentation, please have a look at `src/DateTime/DateTime.txt`.


.. contents::

The DateTime package
====================

Encapsulation of date/time values.


Function Timezones()
--------------------

Returns the list of recognized timezone names:

  >>> from DateTime import Timezones
  >>> zones = set(Timezones())

Almost all of the standard pytz timezones are included, with the exception
of some commonly-used but ambiguous abbreviations, where historical Zope
usage conflicts with the name used by pytz:

  >>> import pytz
  >>> [x for x in pytz.all_timezones if x not in zones]
  ['CET', 'EET', 'EST', 'MET', 'MST', 'WET']

Class DateTime
--------------

DateTime objects represent instants in time and provide interfaces for
controlling its representation without affecting the absolute value of
the object.

DateTime objects may be created from a wide variety of string or
numeric data, or may be computed from other DateTime objects.
DateTimes support the ability to convert their representations to many
major timezones, as well as the ability to create a DateTime object
in the context of a given timezone.

DateTime objects provide partial numerical behavior:

* Two date-time objects can be subtracted to obtain a time, in days
  between the two.

* A date-time object and a positive or negative number may be added to
  obtain a new date-time object that is the given number of days later
  than the input date-time object.

* A positive or negative number and a date-time object may be added to
  obtain a new date-time object that is the given number of days later
  than the input date-time object.

* A positive or negative number may be subtracted from a date-time
  object to obtain a new date-time object that is the given number of
  days earlier than the input date-time object.

DateTime objects may be converted to integer, long, or float numbers
of days since January 1, 1901, using the standard int, long, and float
functions (Compatibility Note: int, long and float return the number
of days since 1901 in GMT rather than local machine timezone).
DateTime objects also provide access to their value in a float format
usable with the Python time module, provided that the value of the
object falls in the range of the epoch-based time module.

A DateTime object should be considered immutable; all conversion and numeric
operations return a new DateTime object rather than modify the current object.

A DateTime object always maintains its value as an absolute UTC time,
and is represented in the context of some timezone based on the
arguments used to create the object.  A DateTime object's methods
return values based on the timezone context.

Note that in all cases the local machine timezone is used for
representation if no timezone is specified.

Constructor for DateTime
------------------------

DateTime() returns a new date-time object.  DateTimes may be created
with from zero to seven arguments:

* If the function is called with no arguments, then the current date/
  time is returned, represented in the timezone of the local machine.

* If the function is invoked with a single string argument which is a
  recognized timezone name, an object representing the current time is
  returned, represented in the specified timezone.

* If the function is invoked with a single string argument
  representing a valid date/time, an object representing that date/
  time will be returned.

  As a general rule, any date-time representation that is recognized
  and unambiguous to a resident of North America is acceptable.  (The
  reason for this qualification is that in North America, a date like:
  2/1/1994 is interpreted as February 1, 1994, while in some parts of
  the world, it is interpreted as January 2, 1994.) A date/ time
  string consists of two components, a date component and an optional
  time component, separated by one or more spaces.  If the time
  component is omitted, 12:00am is assumed.
  
  Any recognized timezone name specified as the final element of the
  date/time string will be used for computing the date/time value.
  (If you create a DateTime with the string,
  "Mar 9, 1997 1:45pm US/Pacific", the value will essentially be the
  same as if you had captured time.time() at the specified date and
  time on a machine in that timezone).  If no timezone is passed, then
  the timezone configured on the local machine will be used, **except**
  that if the date format matches ISO 8601 ('YYYY-MM-DD'), the instance
  will use UTC / GMT+0 as the timezone.

  o Returns current date/time, represented in US/Eastern:

    >>> from DateTime import DateTime
    >>> e = DateTime('US/Eastern')
    >>> e.timezone()
    'US/Eastern'

  o Returns specified time, represented in local machine zone:

    >>> x = DateTime('1997/3/9 1:45pm')
    >>> x.parts() # doctest: +ELLIPSIS
    (1997, 3, 9, 13, 45, ...)

  o Specified time in local machine zone, verbose format:

    >>> y = DateTime('Mar 9, 1997 13:45:00')
    >>> y.parts() # doctest: +ELLIPSIS
    (1997, 3, 9, 13, 45, ...)
    >>> y == x
    True
    
  o Specified time in UTC via ISO 8601 rule:
  
    >>> z = DateTime('2014-03-24')
    >>> z.parts() # doctest: +ELLIPSIS
    (2014, 3, 24, 0, 0, ...)
    >>> z.timezone()
    'GMT+0'

  The date component consists of year, month, and day values.  The
  year value must be a one-, two-, or four-digit integer.  If a one-
  or two-digit year is used, the year is assumed to be in the
  twentieth century.  The month may an integer, from 1 to 12, a month
  name, or a month abbreviation, where a period may optionally follow
  the abbreviation.  The day must be an integer from 1 to the number of
  days in the month.  The year, month, and day values may be separated
  by periods, hyphens, forward slashes, or spaces.  Extra spaces are
  permitted around the delimiters.  Year, month, and day values may be
  given in any order as long as it is possible to distinguish the
  components.  If all three components are numbers that are less than
  13, then a month-day-year ordering is assumed.

  The time component consists of hour, minute, and second values
  separated by colons.  The hour value must be an integer between 0
  and 23 inclusively.  The minute value must be an integer between 0
  and 59 inclusively.  The second value may be an integer value
  between 0 and 59.999 inclusively.  The second value or both the
  minute and second values may be omitted.  The time may be followed
  by am or pm in upper or lower case, in which case a 12-hour clock is
  assumed.

* If the DateTime function is invoked with a single numeric argument,
  the number is assumed to be either a floating point value such as
  that returned by time.time(), or a number of days after January 1,
  1901 00:00:00 UTC.

  A DateTime object is returned that represents either the GMT value
  of the time.time() float represented in the local machine's
  timezone, or that number of days after January 1, 1901.  Note that
  the number of days after 1901 need to be expressed from the
  viewpoint of the local machine's timezone.  A negative argument will
  yield a date-time value before 1901.

* If the function is invoked with two numeric arguments, then the
  first is taken to be an integer year and the second argument is
  taken to be an offset in days from the beginning of the year, in the
  context of the local machine timezone.  The date-time value returned
  is the given offset number of days from the beginning of the given
  year, represented in the timezone of the local machine.  The offset
  may be positive or negative.  Two-digit years are assumed to be in
  the twentieth century.

* If the function is invoked with two arguments, the first a float
  representing a number of seconds past the epoch in GMT (such as
  those returned by time.time()) and the second a string naming a
  recognized timezone, a DateTime with a value of that GMT time will
  be returned, represented in the given timezone.

    >>> import time
    >>> t = time.time()

  Time t represented as US/Eastern:

    >>> now_east = DateTime(t, 'US/Eastern')

  Time t represented as US/Pacific:

    >>> now_west = DateTime(t, 'US/Pacific')

  Only their representations are different:

    >>> now_east.equalTo(now_west)
    True

* If the function is invoked with three or more numeric arguments,
  then the first is taken to be an integer year, the second is taken
  to be an integer month, and the third is taken to be an integer day.
  If the combination of values is not valid, then a DateTimeError is
  raised.  One- or two-digit years up to 69 are assumed to be in the 
  21st century, whereas values 70-99 are assumed to be 20th century.
  The fourth, fifth, and sixth arguments are floating point, positive
  or negative offsets in units of hours, minutes, and days, and
  default to zero if not given.  An optional string may be given as
  the final argument to indicate timezone (the effect of this is as if
  you had taken the value of time.time() at that time on a machine in
  the specified timezone).

If a string argument passed to the DateTime constructor cannot be
parsed, it will raise SyntaxError.  Invalid date, time, or
timezone components will raise a DateTimeError.

The module function Timezones() will return a l