datetime
8.1. datetime
The datetime module, the focus of the implementation is on efficient attribute extraction for output formatting and manipulation.
There are two kinds of date and time objects: “naive” and “aware”.
An aware object has sufficient knowledge of applicable algorithmic and political time adjustments, such as time zone and daylight saving time information, to locate itself relative to other aware objects. An aware object is used to represent a specific moment in time.
A naive object does not contain enough information to unambiguously locate itself relative to other date/time objects. Whether a naive object represents Coordinated Universal Time (UTC), local time, or time in some other timezone is purely up to the program, Naive objects are easy to understand and to work with, at the cost of ignoring some aspects of reality.
For applications requiring aware objects, datetime and time objects have an optional time zone information attribute, tzinfo, that can be set to an instance of a subclass of the abstract tzinfo class. These tzinfo objects capture information about the offset from UTC time, the time zone name, and whether Daylight Saving Time is in effect. Note that only one concrete tzinfo class, the timezone class, is supplied by the datetime module. The timezone class can represent simple timezones with fixed offset from UTC, such as UTC itself or North American EST and EDT timezones.
The datetime module exports the following constants:
datetime.MINYEAR
The smallest year number allowed in a date or datetime object. MINYEAR is 1.
datetime.MAXYEAR
The largest year number allowed in a date or datetime object. MAXYEAR is 9999.
8.1.1. Available Types
class datetime.date
An idealized naive date, Attributes: year, month, and day.
class datetime.time
An idealized time. Attributes: hour, minute, second, microsecond, and tzinfo.
class datetime.datetime
A combination of a date and a time. Attributes: year, month, day, hour, minute, second, microsecond, and tzinfo.
class datetime.timedelta
A duration expressing the difference between two date, time, or datetime instances to microsecond resolution.
class datetime.tzinfo
An abstract base class for time zone information objects. These are used by the datetime and time classes to provide a customizable notion of time adjustment (for example, to account for time zone and/or daylight saving time).
class datetime.timezone
A class that implements the tzinfo abstract base class as a fixed offset from the UTC.
Objects of these types are immutable.
Objects of the date type are always naive.
An object of type time or datetime may be naive or aware. A datetime object d is aware if d.tzinfo is not None and d.tzinfo.utcoffset(d) does not return None. If d.tzinfo is None, or if d.tzinfo is not None but d.tzinfo.utcoffset(d) returns None, d is naive. A time object t is aware if t.tzinfo is not None and t.tzinfo.utcoffset(None) does not return None. Otherwise, t is naive.
The distinction between naive and aware doesn’t apply to timedelta objects.
Subclass relationships:
object timedelta tzinfo timezone time date datetime
8.1.2. timedelta Objects
A timedelta object represents a duration, the difference between two dates or times.
class datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
If the normalized value of days lies outside the indicated range, OverflowError is raised.
Note that normalization of negative values may be surprising at first.
Class attributes are:
timedelta.min, The most negative timedelta object
timedelta.max, The most positive timedelta object
timedelta.resolution, The smallest possible difference between non-equal timedelta objects
Instance attributes (read-only):days, seconds, microseconds
Operation: + , - , * , / , // , % , q, r = divmod(t1, t2) , +t1 , -t1, abs(t), str(t), repr(t)
timedelta.total_seconds() Return the total number of seconds contained in the duration.
8.1.3. date Objects
A date object represents a date (year, month and day) in an idealized calendar, the current Gregorian calendar indefinitely extended in both directions. January 1 of year 1 is called day number 1, January 2 of year 1 is called day number 2, and so on.
Constructor:
class datetime.date(year, month, day)
All arguments are required. If an argument outside those ranges is given, ValueError is raised.
classmethod :
date.today() Return the current local date. This is equivalent to date.fromtimestamp(time.time()).
date.fromtimestamp(timestamp)
Return the local date corresponding to the POSIX timestamp, such as is returned by time.time(). This may raise OverflowError
date.fromordinal(ordinal) Return the date corresponding to the proleptic Gregorian ordinal.
Class attributes:
date.min The earliest representable date
date.max The latest representable date
date.resolution The smallest possible difference between non-equal date objects
Instance attributes (read-only):
date.year
date.month
date.day
Supported operations:
date2 = date1 + timedelta
date2 = date1 - timedelta
timedelta = date1 - date2
date1 < date2
Dates can be used as dictionary keys. In Boolean contexts, all date objects are considered to be true.
Instance methods:
date.replace(year=self.year, month=self.month, day=self.day) Return a date
date.timetuple() Return a time.struct_time such as returned by time.localtime().
date.toordinal() Return the proleptic Gregorian ordinal of the date
date.weekday() Return the day of the week as an integer, where Monday is 0 and Sunday is 6.
date.isoweekday() Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
date.isocalendar() Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
date.isoformat() Return a string representing the date in ISO 8601 format, ‘YYYY-MM-DD’.
date.str() For a date d, str(d) is equivalent to d.isoformat().
date.ctime() Return a string representing the date, date(2002, 12, 4).ctime() == ‘Wed Dec 4 00:00:00 2002’.
date.strftime(format) Return a string representing the date, controlled by an explicit format string.
date.format(format) Same as date.strftime(). see strftime() and strptime() Behavior
>» d.isoformat() ‘2002-03-11’ >» d.strftime("%d/%m/%y") ‘11/03/02’ >» d.strftime("%A %d. %B %Y") ‘Monday 11. March 2002’ >» ‘The {1} is {0:%d}, the {2} is {0:%B}.’.format(d, “day”, “month”) ‘The day is 11, the month is March.’
8.1.4. datetime Objects
A datetime object is a single object containing all the information from a date object and a time object.
Constructor:
class datetime.datetime(year, month, day, hour=0, minute=0, second=0, microsecond=0, tzinfo=None, *, fold=0)
The year, month and day arguments are required. tzinfo may be None, or an instance of a tzinfo subclass.
class methods:
datetime.today()
datetime.now(tz=None) If optional argument tz is None or not specified, this is like today(), but, if possible, supplies more precision than can be gotten from going through a time.time() timestamp
datetime.utcnow()