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 mach