Note that normalization of negative values may be surprising at first. For
example, ::
+ >>> from datetime import timedelta
>>> d = timedelta(microseconds=-1)
>>> (d.days, d.seconds, d.microseconds)
(-1, 86399, 999999)
efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
considered to be true if and only if it isn't equal to ``timedelta(0)``.
+Example usage::
+
+ >>> from datetime import timedelta
+ >>> year = timedelta(days=365)
+ >>> another_year = timedelta(weeks=40, days=84, hours=23,
+ ... minutes=50, seconds=600) # adds up to 365 days
+ >>> year == another_year
+ True
+ >>> ten_years = 10 * year
+ >>> ten_years, ten_years.days // 365
+ (datetime.timedelta(3650), 10)
+ >>> nine_years = ten_years - year
+ >>> nine_years, nine_years.days // 365
+ (datetime.timedelta(3285), 9)
+ >>> three_years = nine_years // 3;
+ >>> three_years, three_years.days // 365
+ (datetime.timedelta(1095), 3)
+ >>> abs(three_years - ten_years) == 2 * three_years + year
+ True
+
.. _datetime-date:
Format codes referring to hours, minutes or seconds will see 0 values. See
section :ref:`strftime-behavior`.
+Example of counting days to an event::
+
+ >>> import time
+ >>> from datetime import date
+ >>> today = date.today()
+ >>> today
+ datetime.date(2007, 12, 5)
+ >>> today == date.fromtimestamp(time.time())
+ True
+ >>> my_birthday = date(today.year, 6, 24)
+ >>> if my_birthday < today:
+ ... my_birthday = my_birthday.replace(year=today.year + 1)
+ >>> my_birthday
+ datetime.date(2008, 6, 24)
+ >>> time_to_birthday = abs(my_birthday - today)
+ >>> time_to_birthday.days
+ 202
+
+Example of working with :class:`date`::
+
+ >>> from datetime import date
+ >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
+ >>> d
+ datetime.date(2002, 3, 11)
+ >>> t = d.timetuple()
+ >>> for i in t:
+ ... print i
+ 2002 # year
+ 3 # month
+ 11 # day
+ 0
+ 0
+ 0
+ 0 # weekday (0 = Monday)
+ 70 # 70th day in the year
+ -1
+ >>> ic = d.isocalendar()
+ >>> for i in ic:
+ ... print i # doctest: +SKIP
+ 2002 # ISO year
+ 11 # ISO week number
+ 1 # ISO day number ( 1 = Monday )
+ >>> d.isoformat()
+ '2002-03-11'
+ >>> d.strftime("%d/%m/%y")
+ '11/03/02'
+ >>> d.strftime("%A %d. %B %Y")
+ 'Monday 11. March 2002'
+
.. _datetime-datetime:
Return a string representing the date and time, controlled by an explicit format
string. See section :ref:`strftime-behavior`.
+Examples of working with datetime objects::
+
+ >>> from datetime import datetime, date, time
+ >>> # Using datetime.combine()
+ >>> d = date(2005, 7, 14)
+ >>> t = time(12, 30)
+ >>> datetime.combine(d, t)
+ datetime.datetime(2005, 7, 14, 12, 30)
+ >>> # Using datetime.now() or datetime.utcnow()
+ >>> datetime.now()
+ datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
+ >>> datetime.utcnow()
+ datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
+ >>> # Using datetime.strptime()
+ >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
+ >>> dt
+ datetime.datetime(2006, 11, 21, 16, 30)
+ >>> # Using datetime.timetuple() to get tuple of all attributes
+ >>> tt = dt.timetuple()
+ >>> for it in tt:
+ ... print it
+ ...
+ 2006 # year
+ 11 # month
+ 21 # day
+ 16 # hour
+ 30 # minute
+ 0 # second
+ 1 # weekday (0 = Monday)
+ 325 # number of days since 1st January
+ -1 # dst - method tzinfo.dst() returned None
+ >>> # Date in ISO format
+ >>> ic = dt.isocalendar()
+ >>> for it in ic:
+ ... print it
+ ...
+ 2006 # ISO year
+ 47 # ISO week
+ 2 # ISO weekday
+ >>> # Formatting datetime
+ >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
+ 'Tuesday, 21. November 2006 04:30PM'
+
+Using datetime with tzinfo::
+
+ >>> from datetime import timedelta, datetime, tzinfo
+ >>> class GMT1(tzinfo):
+ ... def __init__(self): # DST starts last Sunday in March
+ ... d = datetime(dt.year, 4, 1) # ends last Sunday in October
+ ... self.dston = d - timedelta(days=d.weekday() + 1)
+ ... d = datetime(dt.year, 11, 1)
+ ... self.dstoff = d - timedelta(days=d.weekday() + 1)
+ ... def utcoffset(self, dt):
+ ... return timedelta(hours=1) + self.dst(dt)
+ ... def dst(self, dt):
+ ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
+ ... return timedelta(hours=1)
+ ... else:
+ ... return timedelta(0)
+ ... def tzname(self,dt):
+ ... return "GMT +1"
+ ...
+ >>> class GMT2(tzinfo):
+ ... def __init__(self):
+ ... d = datetime(dt.year, 4, 1)
+ ... self.dston = d - timedelta(days=d.weekday() + 1)
+ ... d = datetime(dt.year, 11, 1)
+ ... self.dstoff = d - timedelta(days=d.weekday() + 1)
+ ... def utcoffset(self, dt):
+ ... return timedelta(hours=1) + self.dst(dt)
+ ... def dst(self, dt):
+ ... if self.dston <= dt.replace(tzinfo=None) < self.dstoff:
+ ... return timedelta(hours=2)
+ ... else:
+ ... return timedelta(0)
+ ... def tzname(self,dt):
+ ... return "GMT +2"
+ ...
+ >>> gmt1 = GMT1()
+ >>> # Daylight Saving Time
+ >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
+ >>> dt1.dst()
+ datetime.timedelta(0)
+ >>> dt1.utcoffset()
+ datetime.timedelta(0, 3600)
+ >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
+ >>> dt2.dst()
+ datetime.timedelta(0, 3600)
+ >>> dt2.utcoffset()
+ datetime.timedelta(0, 7200)
+ >>> # Convert datetime to another time zone
+ >>> dt3 = dt2.astimezone(GMT2())
+ >>> dt3 # doctest: +ELLIPSIS
+ datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
+ >>> dt2 # doctest: +ELLIPSIS
+ datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
+ >>> dt2.utctimetuple() == dt3.utctimetuple()
+ True
+
+
.. _datetime-time:
``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
+ >>> class GMT1(tzinfo):
+ ... def utcoffset(self, dt):
+ ... return timedelta(hours=1)
+ ... def dst(self, dt):
+ ... return timedelta(0)
+ ... def tzname(self,dt):
+ ... return "Europe/Prague"
+ ...
+ >>> t = time(12, 10, 30, tzinfo=GMT1())
+ >>> t # doctest: +ELLIPSIS
+ datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
+ >>> gmt = GMT1()
+ >>> t.isoformat()
+ '12:10:30+01:00'
+ >>> t.dst()
+ datetime.timedelta(0)
+ >>> t.tzname()
+ 'Europe/Prague'
+ >>> t.strftime("%H:%M:%S %Z")
+ '12:10:30 Europe/Prague'
+
.. _datetime-tzinfo:
:class:`tzinfo` subclasses; there are no ambiguities when using UTC, or any
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:
should not be used, as :class:`date` objects have no such values. If they're
used anyway, ``0`` is substituted for them.
-For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
-strings.
-
-For an aware object:
-
-``%z``
- :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
- -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
- MM is a 2-digit string giving the number of UTC offset minutes. For example, if
- :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
- replaced with the string ``'-0330'``.
-
-``%Z``
- If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
- Otherwise ``%Z`` is replaced by the returned value, which must be a string.
-
The full set of format codes supported varies across platforms, because Python
calls the platform C library's :func:`strftime` function, and platform
-variations are common. The documentation for Python's :mod:`time` module lists
-the format codes that the C standard (1989 version) requires, and those work on
-all platforms with a standard C implementation. Note that the 1999 version of
-the C standard added additional format codes.
+variations are common.
+
+The following is a list of all the format codes that the C standard (1989
+version) requires, and these work on all platforms with a standard C
+implementation. Note that the 1999 version of the C standard added additional
+format codes.
The exact range of years for which :meth:`strftime` works also varies across
platforms. Regardless of platform, years before 1900 cannot be used.
-.. % %% This example is obsolete, since strptime is now supported by datetime.
-.. %
-.. % \subsection{Examples}
-.. %
-.. % \subsubsection{Creating Datetime Objects from Formatted Strings}
-.. %
-.. % The \class{datetime} class does not directly support parsing formatted time
-.. % strings. You can use \function{time.strptime} to do the parsing and create
-.. % a \class{datetime} object from the tuple it returns:
-.. %
-.. % \begin{verbatim}
-.. % >>> s = "2005-12-06T12:13:14"
-.. % >>> from datetime import datetime
-.. % >>> from time import strptime
-.. % >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
-.. % datetime.datetime(2005, 12, 6, 12, 13, 14)
-.. % \end{verbatim}
-.. %
++-----------+--------------------------------+-------+
+| Directive | Meaning | Notes |
++===========+================================+=======+
+| ``%a`` | Locale's abbreviated weekday | |
+| | name. | |
++-----------+--------------------------------+-------+
+| ``%A`` | Locale's full weekday name. | |
++-----------+--------------------------------+-------+
+| ``%b`` | Locale's abbreviated month | |
+| | name. | |
++-----------+--------------------------------+-------+
+| ``%B`` | Locale's full month name. | |
++-----------+--------------------------------+-------+
+| ``%c`` | Locale's appropriate date and | |
+| | time representation. | |
++-----------+--------------------------------+-------+
+| ``%d`` | Day of the month as a decimal | |
+| | number [01,31]. | |
++-----------+--------------------------------+-------+
+| ``%H`` | Hour (24-hour clock) as a | |
+| | decimal number [00,23]. | |
++-----------+--------------------------------+-------+
+| ``%I`` | Hour (12-hour clock) as a | |
+| | decimal number [01,12]. | |
++-----------+--------------------------------+-------+
+| ``%j`` | Day of the year as a decimal | |
+| | number [001,366]. | |
++-----------+--------------------------------+-------+
+| ``%m`` | Month as a decimal number | |
+| | [01,12]. | |
++-----------+--------------------------------+-------+
+| ``%M`` | Minute as a decimal number | |
+| | [00,59]. | |
++-----------+--------------------------------+-------+
+| ``%p`` | Locale's equivalent of either | \(1) |
+| | AM or PM. | |
++-----------+--------------------------------+-------+
+| ``%S`` | Second as a decimal number | \(2) |
+| | [00,61]. | |
++-----------+--------------------------------+-------+
+| ``%U`` | Week number of the year | \(3) |
+| | (Sunday as the first day of | |
+| | the week) as a decimal number | |
+| | [00,53]. All days in a new | |
+| | year preceding the first | |
+| | Sunday are considered to be in | |
+| | week 0. | |
++-----------+--------------------------------+-------+
+| ``%w`` | Weekday as a decimal number | |
+| | [0(Sunday),6]. | |
++-----------+--------------------------------+-------+
+| ``%W`` | Week number of the year | \(3) |
+| | (Monday as the first day of | |
+| | the week) as a decimal number | |
+| | [00,53]. All days in a new | |
+| | year preceding the first | |
+| | Monday are considered to be in | |
+| | week 0. | |
++-----------+--------------------------------+-------+
+| ``%x`` | Locale's appropriate date | |
+| | representation. | |
++-----------+--------------------------------+-------+
+| ``%X`` | Locale's appropriate time | |
+| | representation. | |
++-----------+--------------------------------+-------+
+| ``%y`` | Year without century as a | |
+| | decimal number [00,99]. | |
++-----------+--------------------------------+-------+
+| ``%Y`` | Year with century as a decimal | |
+| | number. | |
++-----------+--------------------------------+-------+
+| ``%z`` | UTC offset in the form +HHMM | \(4) |
+| | or -HHMM (empty string if the | |
+| | the object is naive). | |
++-----------+--------------------------------+-------+
+| ``%Z`` | Time zone name (empty string | |
+| | if the object is naive). | |
++-----------+--------------------------------+-------+
+| ``%%`` | A literal ``'%'`` character. | |
++-----------+--------------------------------+-------+
+Notes:
+
+(1)
+ When used with the :func:`strptime` function, the ``%p`` directive only affects
+ the output hour field if the ``%I`` directive is used to parse the hour.
+
+(2)
+ The range really is ``0`` to ``61``; this accounts for leap seconds and the
+ (very rare) double leap seconds.
+
+(3)
+ When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
+ calculations when the day of the week and the year are specified.
+
+(4)
+ For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
+ ``%z`` is replaced with the string ``'-0330'``.
#define RSKIP_NONSPACE(s, i) { while (i>=0 && !ISSPACE(s[i])) i--; }
Py_LOCAL_INLINE(PyObject *)
-split_whitespace(const char *s, Py_ssize_t len, Py_ssize_t maxsplit)
+split_whitespace(PyStringObject *self, Py_ssize_t len, Py_ssize_t maxsplit)
{
+ const char *s = PyString_AS_STRING(self);
Py_ssize_t i, j, count=0;
PyObject *str;
PyObject *list = PyList_New(PREALLOC_SIZE(maxsplit));
if (i==len) break;
j = i; i++;
SKIP_NONSPACE(s, i, len);
+ if (j == 0 && i == len && PyString_CheckExact(self)) {
+ /* No whitespace in self, so just use it as list[0] */
+ Py_INCREF(self);
+ PyList_SET_ITEM(list, 0, (PyObject *)self);
+ count++;
+ break;
+ }
SPLIT_ADD(s, j, i);
}
}
Py_LOCAL_INLINE(PyObject *)
-split_char(const char *s, Py_ssize_t len, char ch, Py_ssize_t maxcount)
+split_char(PyStringObject *self, Py_ssize_t len, char ch, Py_ssize_t maxcount)
{
+ const char *s = PyString_AS_STRING(self);
register Py_ssize_t i, j, count=0;
PyObject *str;
PyObject *list = PyList_New(PREALLOC_SIZE(maxcount));
}
}
}
- if (i <= len) {
+ if (i == 0 && count == 0 && PyString_CheckExact(self)) {
+ /* ch not in self, so just use self as list[0] */
+ Py_INCREF(self);
+ PyList_SET_ITEM(list, 0, (PyObject *)self);
+ count++;
+ }
+ else if (i <= len) {
SPLIT_ADD(s, i, len);
}
FIX_PREALLOC_SIZE(list);
if (maxsplit < 0)
maxsplit = PY_SSIZE_T_MAX;
if (subobj == Py_None)
- return split_whitespace(s, len, maxsplit);
+ return split_whitespace(self, len, maxsplit);
if (_getbuffer(subobj, &vsub) < 0)
return NULL;
sub = vsub.buf;
PyObject_ReleaseBuffer(subobj, &vsub);
return NULL;
}
- else if (n == 1) {
- char ch = sub[0];
- PyObject_ReleaseBuffer(subobj, &vsub);
- return split_char(s, len, ch, maxsplit);
- }
+ else if (n == 1)
+ return split_char(self, len, sub[0], maxsplit);
list = PyList_New(PREALLOC_SIZE(maxsplit));
if (list == NULL) {
}
Py_LOCAL_INLINE(PyObject *)
-rsplit_whitespace(const char *s, Py_ssize_t len, Py_ssize_t maxsplit)
+rsplit_whitespace(PyStringObject *self, Py_ssize_t len, Py_ssize_t maxsplit)
{
+ const char *s = PyString_AS_STRING(self);
Py_ssize_t i, j, count=0;
PyObject *str;
PyObject *list = PyList_New(PREALLOC_SIZE(maxsplit));
if (i<0) break;
j = i; i--;
RSKIP_NONSPACE(s, i);
+ if (j == len-1 && i < 0 && PyString_CheckExact(self)) {
+ /* No whitespace in self, so just use it as list[0] */
+ Py_INCREF(self);
+ PyList_SET_ITEM(list, 0, (PyObject *)self);
+ count++;
+ break;
+ }
SPLIT_ADD(s, i + 1, j + 1);
}
if (i >= 0) {
}
Py_LOCAL_INLINE(PyObject *)
-rsplit_char(const char *s, Py_ssize_t len, char ch, Py_ssize_t maxcount)
+rsplit_char(PyStringObject *self, Py_ssize_t len, char ch, Py_ssize_t maxcount)
{
+ const char *s = PyString_AS_STRING(self);
register Py_ssize_t i, j, count=0;
PyObject *str;
PyObject *list = PyList_New(PREALLOC_SIZE(maxcount));
}
}
}
- if (j >= -1) {
+ if (i < 0 && count == 0 && PyString_CheckExact(self)) {
+ /* ch not in self, so just use self as list[0] */
+ Py_INCREF(self);
+ PyList_SET_ITEM(list, 0, (PyObject *)self);
+ count++;
+ }
+ else if (j >= -1) {
SPLIT_ADD(s, 0, j + 1);
}
FIX_PREALLOC_SIZE(list);
{
Py_ssize_t len = PyString_GET_SIZE(self), n, i, j;
Py_ssize_t maxsplit = -1, count=0;
- const char *s = PyString_AS_STRING(self), *sub;
+ const char *s, *sub;
Py_buffer vsub;
PyObject *list, *str, *subobj = Py_None;
if (maxsplit < 0)
maxsplit = PY_SSIZE_T_MAX;
if (subobj == Py_None)
- return rsplit_whitespace(s, len, maxsplit);
+ return rsplit_whitespace(self, len, maxsplit);
if (_getbuffer(subobj, &vsub) < 0)
return NULL;
sub = vsub.buf;
PyObject_ReleaseBuffer(subobj, &vsub);
return NULL;
}
- else if (n == 1) {
- char ch = sub[0];
- PyObject_ReleaseBuffer(subobj, &vsub);
- return rsplit_char(s, len, ch, maxsplit);
- }
+ else if (n == 1)
+ return rsplit_char(self, len, sub[0], maxsplit);
list = PyList_New(PREALLOC_SIZE(maxsplit));
if (list == NULL) {
j = len;
i = j - n;
+ s = PyString_AS_STRING(self);
while ( (i >= 0) && (maxsplit-- > 0) ) {
for (; i>=0; i--) {
if (Py_STRING_MATCH(s, i, sub, n)) {
projects / python / commitdiff