1 /* C implementation for the date/time type documented at
2 * http://www.zope.org/Members/fdrake/DateTimeWiki/FrontPage
6 #include "modsupport.h"
7 #include "structmember.h"
11 #include "timefuncs.h"
13 /* Differentiate between building the core module and building extension
20 /* We require that C int be at least 32 bits, and use int virtually
21 * everywhere. In just a few cases we use a temp long, where a Python
22 * API returns a C long. In such cases, we have to ensure that the
23 * final result fits in a C int (this can be an issue on 64-bit boxes).
26 # error "datetime.c requires that C int have at least 32 bits"
32 /* Nine decimal digits is easy to communicate, and leaves enough room
33 * so that two delta days can be added w/o fear of overflowing a signed
34 * 32-bit int, and with plenty of room left over to absorb any possible
35 * carries from adding seconds.
37 #define MAX_DELTA_DAYS 999999999
39 /* Rename the long macros in datetime.h to more reasonable short names. */
40 #define GET_YEAR PyDateTime_GET_YEAR
41 #define GET_MONTH PyDateTime_GET_MONTH
42 #define GET_DAY PyDateTime_GET_DAY
43 #define DATE_GET_HOUR PyDateTime_DATE_GET_HOUR
44 #define DATE_GET_MINUTE PyDateTime_DATE_GET_MINUTE
45 #define DATE_GET_SECOND PyDateTime_DATE_GET_SECOND
46 #define DATE_GET_MICROSECOND PyDateTime_DATE_GET_MICROSECOND
48 /* Date accessors for date and datetime. */
49 #define SET_YEAR(o, v) (((o)->data[0] = ((v) & 0xff00) >> 8), \
50 ((o)->data[1] = ((v) & 0x00ff)))
51 #define SET_MONTH(o, v) (PyDateTime_GET_MONTH(o) = (v))
52 #define SET_DAY(o, v) (PyDateTime_GET_DAY(o) = (v))
54 /* Date/Time accessors for datetime. */
55 #define DATE_SET_HOUR(o, v) (PyDateTime_DATE_GET_HOUR(o) = (v))
56 #define DATE_SET_MINUTE(o, v) (PyDateTime_DATE_GET_MINUTE(o) = (v))
57 #define DATE_SET_SECOND(o, v) (PyDateTime_DATE_GET_SECOND(o) = (v))
58 #define DATE_SET_MICROSECOND(o, v) \
59 (((o)->data[7] = ((v) & 0xff0000) >> 16), \
60 ((o)->data[8] = ((v) & 0x00ff00) >> 8), \
61 ((o)->data[9] = ((v) & 0x0000ff)))
63 /* Time accessors for time. */
64 #define TIME_GET_HOUR PyDateTime_TIME_GET_HOUR
65 #define TIME_GET_MINUTE PyDateTime_TIME_GET_MINUTE
66 #define TIME_GET_SECOND PyDateTime_TIME_GET_SECOND
67 #define TIME_GET_MICROSECOND PyDateTime_TIME_GET_MICROSECOND
68 #define TIME_SET_HOUR(o, v) (PyDateTime_TIME_GET_HOUR(o) = (v))
69 #define TIME_SET_MINUTE(o, v) (PyDateTime_TIME_GET_MINUTE(o) = (v))
70 #define TIME_SET_SECOND(o, v) (PyDateTime_TIME_GET_SECOND(o) = (v))
71 #define TIME_SET_MICROSECOND(o, v) \
72 (((o)->data[3] = ((v) & 0xff0000) >> 16), \
73 ((o)->data[4] = ((v) & 0x00ff00) >> 8), \
74 ((o)->data[5] = ((v) & 0x0000ff)))
76 /* Delta accessors for timedelta. */
77 #define GET_TD_DAYS(o) (((PyDateTime_Delta *)(o))->days)
78 #define GET_TD_SECONDS(o) (((PyDateTime_Delta *)(o))->seconds)
79 #define GET_TD_MICROSECONDS(o) (((PyDateTime_Delta *)(o))->microseconds)
81 #define SET_TD_DAYS(o, v) ((o)->days = (v))
82 #define SET_TD_SECONDS(o, v) ((o)->seconds = (v))
83 #define SET_TD_MICROSECONDS(o, v) ((o)->microseconds = (v))
85 /* p is a pointer to a time or a datetime object; HASTZINFO(p) returns
88 #define HASTZINFO(p) (((_PyDateTime_BaseTZInfo *)(p))->hastzinfo)
90 /* M is a char or int claiming to be a valid month. The macro is equivalent
91 * to the two-sided Python test
94 #define MONTH_IS_SANE(M) ((unsigned int)(M) - 1 < 12)
96 /* Forward declarations. */
97 static PyTypeObject PyDateTime_DateType
;
98 static PyTypeObject PyDateTime_DateTimeType
;
99 static PyTypeObject PyDateTime_DeltaType
;
100 static PyTypeObject PyDateTime_TimeType
;
101 static PyTypeObject PyDateTime_TZInfoType
;
103 /* ---------------------------------------------------------------------------
107 /* k = i+j overflows iff k differs in sign from both inputs,
108 * iff k^i has sign bit set and k^j has sign bit set,
109 * iff (k^i)&(k^j) has sign bit set.
111 #define SIGNED_ADD_OVERFLOWED(RESULT, I, J) \
112 ((((RESULT) ^ (I)) & ((RESULT) ^ (J))) < 0)
114 /* Compute Python divmod(x, y), returning the quotient and storing the
115 * remainder into *r. The quotient is the floor of x/y, and that's
116 * the real point of this. C will probably truncate instead (C99
117 * requires truncation; C89 left it implementation-defined).
118 * Simplification: we *require* that y > 0 here. That's appropriate
119 * for all the uses made of it. This simplifies the code and makes
120 * the overflow case impossible (divmod(LONG_MIN, -1) is the only
124 divmod(int x
, int y
, int *r
)
135 assert(0 <= *r
&& *r
< y
);
139 /* Round a double to the nearest long. |x| must be small enough to fit
140 * in a C long; this is not checked.
143 round_to_long(double x
)
152 /* ---------------------------------------------------------------------------
153 * General calendrical helper functions
156 /* For each month ordinal in 1..12, the number of days in that month,
157 * and the number of days before that month in the same year. These
158 * are correct for non-leap years only.
160 static int _days_in_month
[] = {
161 0, /* unused; this vector uses 1-based indexing */
162 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31
165 static int _days_before_month
[] = {
166 0, /* unused; this vector uses 1-based indexing */
167 0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334
170 /* year -> 1 if leap year, else 0. */
174 /* Cast year to unsigned. The result is the same either way, but
175 * C can generate faster code for unsigned mod than for signed
176 * mod (especially for % 4 -- a good compiler should just grab
177 * the last 2 bits when the LHS is unsigned).
179 const unsigned int ayear
= (unsigned int)year
;
180 return ayear
% 4 == 0 && (ayear
% 100 != 0 || ayear
% 400 == 0);
183 /* year, month -> number of days in that month in that year */
185 days_in_month(int year
, int month
)
189 if (month
== 2 && is_leap(year
))
192 return _days_in_month
[month
];
195 /* year, month -> number of days in year preceeding first day of month */
197 days_before_month(int year
, int month
)
203 days
= _days_before_month
[month
];
204 if (month
> 2 && is_leap(year
))
209 /* year -> number of days before January 1st of year. Remember that we
210 * start with year 1, so days_before_year(1) == 0.
213 days_before_year(int year
)
216 /* This is incorrect if year <= 0; we really want the floor
217 * here. But so long as MINYEAR is 1, the smallest year this
218 * can see is 0 (this can happen in some normalization endcases),
219 * so we'll just special-case that.
223 return y
*365 + y
/4 - y
/100 + y
/400;
230 /* Number of days in 4, 100, and 400 year cycles. That these have
231 * the correct values is asserted in the module init function.
233 #define DI4Y 1461 /* days_before_year(5); days in 4 years */
234 #define DI100Y 36524 /* days_before_year(101); days in 100 years */
235 #define DI400Y 146097 /* days_before_year(401); days in 400 years */
237 /* ordinal -> year, month, day, considering 01-Jan-0001 as day 1. */
239 ord_to_ymd(int ordinal
, int *year
, int *month
, int *day
)
241 int n
, n1
, n4
, n100
, n400
, leapyear
, preceding
;
243 /* ordinal is a 1-based index, starting at 1-Jan-1. The pattern of
244 * leap years repeats exactly every 400 years. The basic strategy is
245 * to find the closest 400-year boundary at or before ordinal, then
246 * work with the offset from that boundary to ordinal. Life is much
247 * clearer if we subtract 1 from ordinal first -- then the values
248 * of ordinal at 400-year boundaries are exactly those divisible
252 * -- --- ---- ---------- ----------------
253 * 31 Dec -400 -DI400Y -DI400Y -1
254 * 1 Jan -399 -DI400Y +1 -DI400Y 400-year boundary
258 * 1 Jan 001 1 0 400-year boundary
262 * 31 Dec 400 DI400Y DI400Y -1
263 * 1 Jan 401 DI400Y +1 DI400Y 400-year boundary
265 assert(ordinal
>= 1);
267 n400
= ordinal
/ DI400Y
;
268 n
= ordinal
% DI400Y
;
269 *year
= n400
* 400 + 1;
271 /* Now n is the (non-negative) offset, in days, from January 1 of
272 * year, to the desired date. Now compute how many 100-year cycles
274 * Note that it's possible for n100 to equal 4! In that case 4 full
275 * 100-year cycles precede the desired day, which implies the
276 * desired day is December 31 at the end of a 400-year cycle.
281 /* Now compute how many 4-year cycles precede it. */
285 /* And now how many single years. Again n1 can be 4, and again
286 * meaning that the desired day is December 31 at the end of the
292 *year
+= n100
* 100 + n4
* 4 + n1
;
293 if (n1
== 4 || n100
== 4) {
301 /* Now the year is correct, and n is the offset from January 1. We
302 * find the month via an estimate that's either exact or one too
305 leapyear
= n1
== 3 && (n4
!= 24 || n100
== 3);
306 assert(leapyear
== is_leap(*year
));
307 *month
= (n
+ 50) >> 5;
308 preceding
= (_days_before_month
[*month
] + (*month
> 2 && leapyear
));
310 /* estimate is too large */
312 preceding
-= days_in_month(*year
, *month
);
316 assert(n
< days_in_month(*year
, *month
));
321 /* year, month, day -> ordinal, considering 01-Jan-0001 as day 1. */
323 ymd_to_ord(int year
, int month
, int day
)
325 return days_before_year(year
) + days_before_month(year
, month
) + day
;
328 /* Day of week, where Monday==0, ..., Sunday==6. 1/1/1 was a Monday. */
330 weekday(int year
, int month
, int day
)
332 return (ymd_to_ord(year
, month
, day
) + 6) % 7;
335 /* Ordinal of the Monday starting week 1 of the ISO year. Week 1 is the
336 * first calendar week containing a Thursday.
339 iso_week1_monday(int year
)
341 int first_day
= ymd_to_ord(year
, 1, 1); /* ord of 1/1 */
342 /* 0 if 1/1 is a Monday, 1 if a Tue, etc. */
343 int first_weekday
= (first_day
+ 6) % 7;
344 /* ordinal of closest Monday at or before 1/1 */
345 int week1_monday
= first_day
- first_weekday
;
347 if (first_weekday
> 3) /* if 1/1 was Fri, Sat, Sun */
352 /* ---------------------------------------------------------------------------
356 /* Check that -MAX_DELTA_DAYS <= days <= MAX_DELTA_DAYS. If so, return 0.
357 * If not, raise OverflowError and return -1.
360 check_delta_day_range(int days
)
362 if (-MAX_DELTA_DAYS
<= days
&& days
<= MAX_DELTA_DAYS
)
364 PyErr_Format(PyExc_OverflowError
,
365 "days=%d; must have magnitude <= %d",
366 days
, MAX_DELTA_DAYS
);
370 /* Check that date arguments are in range. Return 0 if they are. If they
371 * aren't, raise ValueError and return -1.
374 check_date_args(int year
, int month
, int day
)
377 if (year
< MINYEAR
|| year
> MAXYEAR
) {
378 PyErr_SetString(PyExc_ValueError
,
379 "year is out of range");
382 if (month
< 1 || month
> 12) {
383 PyErr_SetString(PyExc_ValueError
,
384 "month must be in 1..12");
387 if (day
< 1 || day
> days_in_month(year
, month
)) {
388 PyErr_SetString(PyExc_ValueError
,
389 "day is out of range for month");
395 /* Check that time arguments are in range. Return 0 if they are. If they
396 * aren't, raise ValueError and return -1.
399 check_time_args(int h
, int m
, int s
, int us
)
401 if (h
< 0 || h
> 23) {
402 PyErr_SetString(PyExc_ValueError
,
403 "hour must be in 0..23");
406 if (m
< 0 || m
> 59) {
407 PyErr_SetString(PyExc_ValueError
,
408 "minute must be in 0..59");
411 if (s
< 0 || s
> 59) {
412 PyErr_SetString(PyExc_ValueError
,
413 "second must be in 0..59");
416 if (us
< 0 || us
> 999999) {
417 PyErr_SetString(PyExc_ValueError
,
418 "microsecond must be in 0..999999");
424 /* ---------------------------------------------------------------------------
425 * Normalization utilities.
428 /* One step of a mixed-radix conversion. A "hi" unit is equivalent to
429 * factor "lo" units. factor must be > 0. If *lo is less than 0, or
430 * at least factor, enough of *lo is converted into "hi" units so that
431 * 0 <= *lo < factor. The input values must be such that int overflow
435 normalize_pair(int *hi
, int *lo
, int factor
)
439 if (*lo
< 0 || *lo
>= factor
) {
440 const int num_hi
= divmod(*lo
, factor
, lo
);
441 const int new_hi
= *hi
+ num_hi
;
442 assert(! SIGNED_ADD_OVERFLOWED(new_hi
, *hi
, num_hi
));
445 assert(0 <= *lo
&& *lo
< factor
);
448 /* Fiddle days (d), seconds (s), and microseconds (us) so that
451 * The input values must be such that the internals don't overflow.
452 * The way this routine is used, we don't get close.
455 normalize_d_s_us(int *d
, int *s
, int *us
)
457 if (*us
< 0 || *us
>= 1000000) {
458 normalize_pair(s
, us
, 1000000);
459 /* |s| can't be bigger than about
460 * |original s| + |original us|/1000000 now.
464 if (*s
< 0 || *s
>= 24*3600) {
465 normalize_pair(d
, s
, 24*3600);
466 /* |d| can't be bigger than about
468 * (|original s| + |original us|/1000000) / (24*3600) now.
471 assert(0 <= *s
&& *s
< 24*3600);
472 assert(0 <= *us
&& *us
< 1000000);
475 /* Fiddle years (y), months (m), and days (d) so that
477 * 1 <= *d <= days_in_month(*y, *m)
478 * The input values must be such that the internals don't overflow.
479 * The way this routine is used, we don't get close.
482 normalize_y_m_d(int *y
, int *m
, int *d
)
484 int dim
; /* # of days in month */
486 /* This gets muddy: the proper range for day can't be determined
487 * without knowing the correct month and year, but if day is, e.g.,
488 * plus or minus a million, the current month and year values make
489 * no sense (and may also be out of bounds themselves).
490 * Saying 12 months == 1 year should be non-controversial.
492 if (*m
< 1 || *m
> 12) {
494 normalize_pair(y
, m
, 12);
496 /* |y| can't be bigger than about
497 * |original y| + |original m|/12 now.
500 assert(1 <= *m
&& *m
<= 12);
502 /* Now only day can be out of bounds (year may also be out of bounds
503 * for a datetime object, but we don't care about that here).
504 * If day is out of bounds, what to do is arguable, but at least the
505 * method here is principled and explainable.
507 dim
= days_in_month(*y
, *m
);
508 if (*d
< 1 || *d
> dim
) {
509 /* Move day-1 days from the first of the month. First try to
510 * get off cheap if we're only one day out of range
511 * (adjustments for timezone alone can't be worse than that).
516 *d
= days_in_month(*y
, *m
);
523 else if (*d
== dim
+ 1) {
524 /* move forward a day */
533 int ordinal
= ymd_to_ord(*y
, *m
, 1) +
535 ord_to_ymd(ordinal
, y
, m
, d
);
542 /* Fiddle out-of-bounds months and days so that the result makes some kind
543 * of sense. The parameters are both inputs and outputs. Returns < 0 on
544 * failure, where failure means the adjusted year is out of bounds.
547 normalize_date(int *year
, int *month
, int *day
)
551 normalize_y_m_d(year
, month
, day
);
552 if (MINYEAR
<= *year
&& *year
<= MAXYEAR
)
555 PyErr_SetString(PyExc_OverflowError
,
556 "date value out of range");
562 /* Force all the datetime fields into range. The parameters are both
563 * inputs and outputs. Returns < 0 on error.
566 normalize_datetime(int *year
, int *month
, int *day
,
567 int *hour
, int *minute
, int *second
,
570 normalize_pair(second
, microsecond
, 1000000);
571 normalize_pair(minute
, second
, 60);
572 normalize_pair(hour
, minute
, 60);
573 normalize_pair(day
, hour
, 24);
574 return normalize_date(year
, month
, day
);
577 /* ---------------------------------------------------------------------------
578 * Basic object allocation: tp_alloc implementations. These allocate
579 * Python objects of the right size and type, and do the Python object-
580 * initialization bit. If there's not enough memory, they return NULL after
581 * setting MemoryError. All data members remain uninitialized trash.
583 * We abuse the tp_alloc "nitems" argument to communicate whether a tzinfo
584 * member is needed. This is ugly, imprecise, and possibly insecure.
585 * tp_basicsize for the time and datetime types is set to the size of the
586 * struct that has room for the tzinfo member, so subclasses in Python will
587 * allocate enough space for a tzinfo member whether or not one is actually
588 * needed. That's the "ugly and imprecise" parts. The "possibly insecure"
589 * part is that PyType_GenericAlloc() (which subclasses in Python end up
590 * using) just happens today to effectively ignore the nitems argument
591 * when tp_itemsize is 0, which it is for these type objects. If that
592 * changes, perhaps the callers of tp_alloc slots in this file should
593 * be changed to force a 0 nitems argument unless the type being allocated
594 * is a base type implemented in this file (so that tp_alloc is time_alloc
595 * or datetime_alloc below, which know about the nitems abuse).
599 time_alloc(PyTypeObject
*type
, int aware
)
604 PyObject_MALLOC(aware
?
605 sizeof(PyDateTime_Time
) :
606 sizeof(_PyDateTime_BaseTime
));
608 return (PyObject
*)PyErr_NoMemory();
609 PyObject_INIT(self
, type
);
614 datetime_alloc(PyTypeObject
*type
, int aware
)
619 PyObject_MALLOC(aware
?
620 sizeof(PyDateTime_DateTime
) :
621 sizeof(_PyDateTime_BaseDateTime
));
623 return (PyObject
*)PyErr_NoMemory();
624 PyObject_INIT(self
, type
);
628 /* ---------------------------------------------------------------------------
629 * Helpers for setting object fields. These work on pointers to the
630 * appropriate base class.
633 /* For date and datetime. */
635 set_date_fields(PyDateTime_Date
*self
, int y
, int m
, int d
)
643 /* ---------------------------------------------------------------------------
644 * Create various objects, mostly without range checking.
647 /* Create a date instance with no range checking. */
649 new_date_ex(int year
, int month
, int day
, PyTypeObject
*type
)
651 PyDateTime_Date
*self
;
653 self
= (PyDateTime_Date
*) (type
->tp_alloc(type
, 0));
655 set_date_fields(self
, year
, month
, day
);
656 return (PyObject
*) self
;
659 #define new_date(year, month, day) \
660 new_date_ex(year, month, day, &PyDateTime_DateType)
662 /* Create a datetime instance with no range checking. */
664 new_datetime_ex(int year
, int month
, int day
, int hour
, int minute
,
665 int second
, int usecond
, PyObject
*tzinfo
, PyTypeObject
*type
)
667 PyDateTime_DateTime
*self
;
668 char aware
= tzinfo
!= Py_None
;
670 self
= (PyDateTime_DateTime
*) (type
->tp_alloc(type
, aware
));
672 self
->hastzinfo
= aware
;
673 set_date_fields((PyDateTime_Date
*)self
, year
, month
, day
);
674 DATE_SET_HOUR(self
, hour
);
675 DATE_SET_MINUTE(self
, minute
);
676 DATE_SET_SECOND(self
, second
);
677 DATE_SET_MICROSECOND(self
, usecond
);
680 self
->tzinfo
= tzinfo
;
683 return (PyObject
*)self
;
686 #define new_datetime(y, m, d, hh, mm, ss, us, tzinfo) \
687 new_datetime_ex(y, m, d, hh, mm, ss, us, tzinfo, \
688 &PyDateTime_DateTimeType)
690 /* Create a time instance with no range checking. */
692 new_time_ex(int hour
, int minute
, int second
, int usecond
,
693 PyObject
*tzinfo
, PyTypeObject
*type
)
695 PyDateTime_Time
*self
;
696 char aware
= tzinfo
!= Py_None
;
698 self
= (PyDateTime_Time
*) (type
->tp_alloc(type
, aware
));
700 self
->hastzinfo
= aware
;
702 TIME_SET_HOUR(self
, hour
);
703 TIME_SET_MINUTE(self
, minute
);
704 TIME_SET_SECOND(self
, second
);
705 TIME_SET_MICROSECOND(self
, usecond
);
708 self
->tzinfo
= tzinfo
;
711 return (PyObject
*)self
;
714 #define new_time(hh, mm, ss, us, tzinfo) \
715 new_time_ex(hh, mm, ss, us, tzinfo, &PyDateTime_TimeType)
717 /* Create a timedelta instance. Normalize the members iff normalize is
718 * true. Passing false is a speed optimization, if you know for sure
719 * that seconds and microseconds are already in their proper ranges. In any
720 * case, raises OverflowError and returns NULL if the normalized days is out
724 new_delta_ex(int days
, int seconds
, int microseconds
, int normalize
,
727 PyDateTime_Delta
*self
;
730 normalize_d_s_us(&days
, &seconds
, µseconds
);
731 assert(0 <= seconds
&& seconds
< 24*3600);
732 assert(0 <= microseconds
&& microseconds
< 1000000);
734 if (check_delta_day_range(days
) < 0)
737 self
= (PyDateTime_Delta
*) (type
->tp_alloc(type
, 0));
740 SET_TD_DAYS(self
, days
);
741 SET_TD_SECONDS(self
, seconds
);
742 SET_TD_MICROSECONDS(self
, microseconds
);
744 return (PyObject
*) self
;
747 #define new_delta(d, s, us, normalize) \
748 new_delta_ex(d, s, us, normalize, &PyDateTime_DeltaType)
750 /* ---------------------------------------------------------------------------
754 /* Ensure that p is None or of a tzinfo subclass. Return 0 if OK; if not
755 * raise TypeError and return -1.
758 check_tzinfo_subclass(PyObject
*p
)
760 if (p
== Py_None
|| PyTZInfo_Check(p
))
762 PyErr_Format(PyExc_TypeError
,
763 "tzinfo argument must be None or of a tzinfo subclass, "
765 p
->ob_type
->tp_name
);
769 /* Return tzinfo.methname(tzinfoarg), without any checking of results.
770 * If tzinfo is None, returns None.
773 call_tzinfo_method(PyObject
*tzinfo
, char *methname
, PyObject
*tzinfoarg
)
777 assert(tzinfo
&& methname
&& tzinfoarg
);
778 assert(check_tzinfo_subclass(tzinfo
) >= 0);
779 if (tzinfo
== Py_None
) {
784 result
= PyObject_CallMethod(tzinfo
, methname
, "O", tzinfoarg
);
788 /* If self has a tzinfo member, return a BORROWED reference to it. Else
789 * return NULL, which is NOT AN ERROR. There are no error returns here,
790 * and the caller must not decref the result.
793 get_tzinfo_member(PyObject
*self
)
795 PyObject
*tzinfo
= NULL
;
797 if (PyDateTime_Check(self
) && HASTZINFO(self
))
798 tzinfo
= ((PyDateTime_DateTime
*)self
)->tzinfo
;
799 else if (PyTime_Check(self
) && HASTZINFO(self
))
800 tzinfo
= ((PyDateTime_Time
*)self
)->tzinfo
;
805 /* Call getattr(tzinfo, name)(tzinfoarg), and extract an int from the
806 * result. tzinfo must be an instance of the tzinfo class. If the method
807 * returns None, this returns 0 and sets *none to 1. If the method doesn't
808 * return None or timedelta, TypeError is raised and this returns -1. If it
809 * returnsa timedelta and the value is out of range or isn't a whole number
810 * of minutes, ValueError is raised and this returns -1.
811 * Else *none is set to 0 and the integer method result is returned.
814 call_utc_tzinfo_method(PyObject
*tzinfo
, char *name
, PyObject
*tzinfoarg
,
820 assert(tzinfo
!= NULL
);
821 assert(PyTZInfo_Check(tzinfo
));
822 assert(tzinfoarg
!= NULL
);
825 u
= call_tzinfo_method(tzinfo
, name
, tzinfoarg
);
829 else if (u
== Py_None
) {
833 else if (PyDelta_Check(u
)) {
834 const int days
= GET_TD_DAYS(u
);
835 if (days
< -1 || days
> 0)
836 result
= 24*60; /* trigger ValueError below */
838 /* next line can't overflow because we know days
841 int ss
= days
* 24 * 3600 + GET_TD_SECONDS(u
);
842 result
= divmod(ss
, 60, &ss
);
843 if (ss
|| GET_TD_MICROSECONDS(u
)) {
844 PyErr_Format(PyExc_ValueError
,
845 "tzinfo.%s() must return a "
846 "whole number of minutes",
853 PyErr_Format(PyExc_TypeError
,
854 "tzinfo.%s() must return None or "
855 "timedelta, not '%s'",
856 name
, u
->ob_type
->tp_name
);
860 if (result
< -1439 || result
> 1439) {
861 PyErr_Format(PyExc_ValueError
,
862 "tzinfo.%s() returned %d; must be in "
870 /* Call tzinfo.utcoffset(tzinfoarg), and extract an integer from the
871 * result. tzinfo must be an instance of the tzinfo class. If utcoffset()
872 * returns None, call_utcoffset returns 0 and sets *none to 1. If uctoffset()
873 * doesn't return None or timedelta, TypeError is raised and this returns -1.
874 * If utcoffset() returns an invalid timedelta (out of range, or not a whole
875 * # of minutes), ValueError is raised and this returns -1. Else *none is
876 * set to 0 and the offset is returned (as int # of minutes east of UTC).
879 call_utcoffset(PyObject
*tzinfo
, PyObject
*tzinfoarg
, int *none
)
881 return call_utc_tzinfo_method(tzinfo
, "utcoffset", tzinfoarg
, none
);
884 /* Call tzinfo.name(tzinfoarg), and return the offset as a timedelta or None.
887 offset_as_timedelta(PyObject
*tzinfo
, char *name
, PyObject
*tzinfoarg
) {
890 assert(tzinfo
&& name
&& tzinfoarg
);
891 if (tzinfo
== Py_None
) {
897 int offset
= call_utc_tzinfo_method(tzinfo
, name
, tzinfoarg
,
899 if (offset
< 0 && PyErr_Occurred())
906 result
= new_delta(0, offset
* 60, 0, 1);
911 /* Call tzinfo.dst(tzinfoarg), and extract an integer from the
912 * result. tzinfo must be an instance of the tzinfo class. If dst()
913 * returns None, call_dst returns 0 and sets *none to 1. If dst()
914 & doesn't return None or timedelta, TypeError is raised and this
915 * returns -1. If dst() returns an invalid timedelta for a UTC offset,
916 * ValueError is raised and this returns -1. Else *none is set to 0 and
917 * the offset is returned (as an int # of minutes east of UTC).
920 call_dst(PyObject
*tzinfo
, PyObject
*tzinfoarg
, int *none
)
922 return call_utc_tzinfo_method(tzinfo
, "dst", tzinfoarg
, none
);
925 /* Call tzinfo.tzname(tzinfoarg), and return the result. tzinfo must be
926 * an instance of the tzinfo class or None. If tzinfo isn't None, and
927 * tzname() doesn't return None or a string, TypeError is raised and this
931 call_tzname(PyObject
*tzinfo
, PyObject
*tzinfoarg
)
935 assert(tzinfo
!= NULL
);
936 assert(check_tzinfo_subclass(tzinfo
) >= 0);
937 assert(tzinfoarg
!= NULL
);
939 if (tzinfo
== Py_None
) {
944 result
= PyObject_CallMethod(tzinfo
, "tzname", "O", tzinfoarg
);
946 if (result
!= NULL
&& result
!= Py_None
&& ! PyString_Check(result
)) {
947 PyErr_Format(PyExc_TypeError
, "tzinfo.tzname() must "
948 "return None or a string, not '%s'",
949 result
->ob_type
->tp_name
);
957 /* an exception has been set; the caller should pass it on */
960 /* type isn't date, datetime, or time subclass */
964 * datetime with !hastzinfo
965 * datetime with None tzinfo,
966 * datetime where utcoffset() returns None
967 * time with !hastzinfo
968 * time with None tzinfo,
969 * time where utcoffset() returns None
973 /* time or datetime where utcoffset() doesn't return None */
977 /* Classify an object as to whether it's naive or offset-aware. See
978 * the "naivety" typedef for details. If the type is aware, *offset is set
979 * to minutes east of UTC (as returned by the tzinfo.utcoffset() method).
980 * If the type is offset-naive (or unknown, or error), *offset is set to 0.
981 * tzinfoarg is the argument to pass to the tzinfo.utcoffset() method.
984 classify_utcoffset(PyObject
*op
, PyObject
*tzinfoarg
, int *offset
)
989 assert(tzinfoarg
!= NULL
);
991 tzinfo
= get_tzinfo_member(op
); /* NULL means no tzinfo, not error */
992 if (tzinfo
== Py_None
)
994 if (tzinfo
== NULL
) {
995 /* note that a datetime passes the PyDate_Check test */
996 return (PyTime_Check(op
) || PyDate_Check(op
)) ?
997 OFFSET_NAIVE
: OFFSET_UNKNOWN
;
999 *offset
= call_utcoffset(tzinfo
, tzinfoarg
, &none
);
1000 if (*offset
== -1 && PyErr_Occurred())
1001 return OFFSET_ERROR
;
1002 return none
? OFFSET_NAIVE
: OFFSET_AWARE
;
1005 /* Classify two objects as to whether they're naive or offset-aware.
1006 * This isn't quite the same as calling classify_utcoffset() twice: for
1007 * binary operations (comparison and subtraction), we generally want to
1008 * ignore the tzinfo members if they're identical. This is by design,
1009 * so that results match "naive" expectations when mixing objects from a
1010 * single timezone. So in that case, this sets both offsets to 0 and
1011 * both naiveties to OFFSET_NAIVE.
1012 * The function returns 0 if everything's OK, and -1 on error.
1015 classify_two_utcoffsets(PyObject
*o1
, int *offset1
, naivety
*n1
,
1016 PyObject
*tzinfoarg1
,
1017 PyObject
*o2
, int *offset2
, naivety
*n2
,
1018 PyObject
*tzinfoarg2
)
1020 if (get_tzinfo_member(o1
) == get_tzinfo_member(o2
)) {
1021 *offset1
= *offset2
= 0;
1022 *n1
= *n2
= OFFSET_NAIVE
;
1025 *n1
= classify_utcoffset(o1
, tzinfoarg1
, offset1
);
1026 if (*n1
== OFFSET_ERROR
)
1028 *n2
= classify_utcoffset(o2
, tzinfoarg2
, offset2
);
1029 if (*n2
== OFFSET_ERROR
)
1035 /* repr is like "someclass(arg1, arg2)". If tzinfo isn't None,
1037 * ", tzinfo=" + repr(tzinfo)
1038 * before the closing ")".
1041 append_keyword_tzinfo(PyObject
*repr
, PyObject
*tzinfo
)
1045 assert(PyString_Check(repr
));
1047 if (tzinfo
== Py_None
)
1049 /* Get rid of the trailing ')'. */
1050 assert(PyString_AsString(repr
)[PyString_Size(repr
)-1] == ')');
1051 temp
= PyString_FromStringAndSize(PyString_AsString(repr
),
1052 PyString_Size(repr
) - 1);
1058 /* Append ", tzinfo=". */
1059 PyString_ConcatAndDel(&repr
, PyString_FromString(", tzinfo="));
1061 /* Append repr(tzinfo). */
1062 PyString_ConcatAndDel(&repr
, PyObject_Repr(tzinfo
));
1064 /* Add a closing paren. */
1065 PyString_ConcatAndDel(&repr
, PyString_FromString(")"));
1069 /* ---------------------------------------------------------------------------
1070 * String format helpers.
1074 format_ctime(PyDateTime_Date
*date
, int hours
, int minutes
, int seconds
)
1076 static const char *DayNames
[] = {
1077 "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"
1079 static const char *MonthNames
[] = {
1080 "Jan", "Feb", "Mar", "Apr", "May", "Jun",
1081 "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
1085 int wday
= weekday(GET_YEAR(date
), GET_MONTH(date
), GET_DAY(date
));
1087 PyOS_snprintf(buffer
, sizeof(buffer
), "%s %s %2d %02d:%02d:%02d %04d",
1088 DayNames
[wday
], MonthNames
[GET_MONTH(date
) - 1],
1089 GET_DAY(date
), hours
, minutes
, seconds
,
1091 return PyString_FromString(buffer
);
1094 /* Add an hours & minutes UTC offset string to buf. buf has no more than
1095 * buflen bytes remaining. The UTC offset is gotten by calling
1096 * tzinfo.uctoffset(tzinfoarg). If that returns None, \0 is stored into
1097 * *buf, and that's all. Else the returned value is checked for sanity (an
1098 * integer in range), and if that's OK it's converted to an hours & minutes
1099 * string of the form
1101 * Returns 0 if everything is OK. If the return value from utcoffset() is
1102 * bogus, an appropriate exception is set and -1 is returned.
1105 format_utcoffset(char *buf
, size_t buflen
, const char *sep
,
1106 PyObject
*tzinfo
, PyObject
*tzinfoarg
)
1114 offset
= call_utcoffset(tzinfo
, tzinfoarg
, &none
);
1115 if (offset
== -1 && PyErr_Occurred())
1126 hours
= divmod(offset
, 60, &minutes
);
1127 PyOS_snprintf(buf
, buflen
, "%c%02d%s%02d", sign
, hours
, sep
, minutes
);
1131 /* I sure don't want to reproduce the strftime code from the time module,
1132 * so this imports the module and calls it. All the hair is due to
1133 * giving special meanings to the %z and %Z format codes via a preprocessing
1134 * step on the format string.
1135 * tzinfoarg is the argument to pass to the object's tzinfo method, if
1139 wrap_strftime(PyObject
*object
, PyObject
*format
, PyObject
*timetuple
,
1140 PyObject
*tzinfoarg
)
1142 PyObject
*result
= NULL
; /* guilty until proved innocent */
1144 PyObject
*zreplacement
= NULL
; /* py string, replacement for %z */
1145 PyObject
*Zreplacement
= NULL
; /* py string, replacement for %Z */
1147 char *pin
; /* pointer to next char in input format */
1148 char ch
; /* next char in input format */
1150 PyObject
*newfmt
= NULL
; /* py string, the output format */
1151 char *pnew
; /* pointer to available byte in output format */
1152 char totalnew
; /* number bytes total in output format buffer,
1153 exclusive of trailing \0 */
1154 char usednew
; /* number bytes used so far in output format buffer */
1156 char *ptoappend
; /* pointer to string to append to output buffer */
1157 int ntoappend
; /* # of bytes to append to output buffer */
1159 assert(object
&& format
&& timetuple
);
1160 assert(PyString_Check(format
));
1162 /* Give up if the year is before 1900.
1163 * Python strftime() plays games with the year, and different
1164 * games depending on whether envar PYTHON2K is set. This makes
1165 * years before 1900 a nightmare, even if the platform strftime
1166 * supports them (and not all do).
1167 * We could get a lot farther here by avoiding Python's strftime
1168 * wrapper and calling the C strftime() directly, but that isn't
1169 * an option in the Python implementation of this module.
1173 PyObject
*pyyear
= PySequence_GetItem(timetuple
, 0);
1174 if (pyyear
== NULL
) return NULL
;
1175 assert(PyInt_Check(pyyear
));
1176 year
= PyInt_AsLong(pyyear
);
1179 PyErr_Format(PyExc_ValueError
, "year=%ld is before "
1180 "1900; the datetime strftime() "
1181 "methods require year >= 1900",
1187 /* Scan the input format, looking for %z and %Z escapes, building
1188 * a new format. Since computing the replacements for those codes
1189 * is expensive, don't unless they're actually used.
1191 totalnew
= PyString_Size(format
) + 1; /* realistic if no %z/%Z */
1192 newfmt
= PyString_FromStringAndSize(NULL
, totalnew
);
1193 if (newfmt
== NULL
) goto Done
;
1194 pnew
= PyString_AsString(newfmt
);
1197 pin
= PyString_AsString(format
);
1198 while ((ch
= *pin
++) != '\0') {
1200 ptoappend
= pin
- 1;
1203 else if ((ch
= *pin
++) == '\0') {
1204 /* There's a lone trailing %; doesn't make sense. */
1205 PyErr_SetString(PyExc_ValueError
, "strftime format "
1209 /* A % has been seen and ch is the character after it. */
1210 else if (ch
== 'z') {
1211 if (zreplacement
== NULL
) {
1212 /* format utcoffset */
1214 PyObject
*tzinfo
= get_tzinfo_member(object
);
1215 zreplacement
= PyString_FromString("");
1216 if (zreplacement
== NULL
) goto Done
;
1217 if (tzinfo
!= Py_None
&& tzinfo
!= NULL
) {
1218 assert(tzinfoarg
!= NULL
);
1219 if (format_utcoffset(buf
,
1225 Py_DECREF(zreplacement
);
1226 zreplacement
= PyString_FromString(buf
);
1227 if (zreplacement
== NULL
) goto Done
;
1230 assert(zreplacement
!= NULL
);
1231 ptoappend
= PyString_AsString(zreplacement
);
1232 ntoappend
= PyString_Size(zreplacement
);
1234 else if (ch
== 'Z') {
1236 if (Zreplacement
== NULL
) {
1237 PyObject
*tzinfo
= get_tzinfo_member(object
);
1238 Zreplacement
= PyString_FromString("");
1239 if (Zreplacement
== NULL
) goto Done
;
1240 if (tzinfo
!= Py_None
&& tzinfo
!= NULL
) {
1242 assert(tzinfoarg
!= NULL
);
1243 temp
= call_tzname(tzinfo
, tzinfoarg
);
1244 if (temp
== NULL
) goto Done
;
1245 if (temp
!= Py_None
) {
1246 assert(PyString_Check(temp
));
1247 /* Since the tzname is getting
1248 * stuffed into the format, we
1249 * have to double any % signs
1250 * so that strftime doesn't
1251 * treat them as format codes.
1253 Py_DECREF(Zreplacement
);
1254 Zreplacement
= PyObject_CallMethod(
1258 if (Zreplacement
== NULL
)
1265 assert(Zreplacement
!= NULL
);
1266 ptoappend
= PyString_AsString(Zreplacement
);
1267 ntoappend
= PyString_Size(Zreplacement
);
1270 /* percent followed by neither z nor Z */
1271 ptoappend
= pin
- 2;
1275 /* Append the ntoappend chars starting at ptoappend to
1278 assert(ntoappend
>= 0);
1281 while (usednew
+ ntoappend
> totalnew
) {
1282 int bigger
= totalnew
<< 1;
1283 if ((bigger
>> 1) != totalnew
) { /* overflow */
1287 if (_PyString_Resize(&newfmt
, bigger
) < 0)
1290 pnew
= PyString_AsString(newfmt
) + usednew
;
1292 memcpy(pnew
, ptoappend
, ntoappend
);
1294 usednew
+= ntoappend
;
1295 assert(usednew
<= totalnew
);
1298 if (_PyString_Resize(&newfmt
, usednew
) < 0)
1301 PyObject
*time
= PyImport_ImportModule("time");
1304 result
= PyObject_CallMethod(time
, "strftime", "OO",
1309 Py_XDECREF(zreplacement
);
1310 Py_XDECREF(Zreplacement
);
1316 isoformat_date(PyDateTime_Date
*dt
, char buffer
[], int bufflen
)
1319 x
= PyOS_snprintf(buffer
, bufflen
,
1321 GET_YEAR(dt
), GET_MONTH(dt
), GET_DAY(dt
));
1326 isoformat_time(PyDateTime_DateTime
*dt
, char buffer
[], int bufflen
)
1328 int us
= DATE_GET_MICROSECOND(dt
);
1330 PyOS_snprintf(buffer
, bufflen
,
1331 "%02d:%02d:%02d", /* 8 characters */
1333 DATE_GET_MINUTE(dt
),
1334 DATE_GET_SECOND(dt
));
1336 PyOS_snprintf(buffer
+ 8, bufflen
- 8, ".%06d", us
);
1339 /* ---------------------------------------------------------------------------
1340 * Wrap functions from the time module. These aren't directly available
1341 * from C. Perhaps they should be.
1344 /* Call time.time() and return its result (a Python float). */
1348 PyObject
*result
= NULL
;
1349 PyObject
*time
= PyImport_ImportModule("time");
1352 result
= PyObject_CallMethod(time
, "time", "()");
1358 /* Build a time.struct_time. The weekday and day number are automatically
1359 * computed from the y,m,d args.
1362 build_struct_time(int y
, int m
, int d
, int hh
, int mm
, int ss
, int dstflag
)
1365 PyObject
*result
= NULL
;
1367 time
= PyImport_ImportModule("time");
1369 result
= PyObject_CallMethod(time
, "struct_time",
1374 days_before_month(y
, m
) + d
,
1381 /* ---------------------------------------------------------------------------
1382 * Miscellaneous helpers.
1385 /* For obscure reasons, we need to use tp_richcompare instead of tp_compare.
1386 * The comparisons here all most naturally compute a cmp()-like result.
1387 * This little helper turns that into a bool result for rich comparisons.
1390 diff_to_bool(int diff
, int op
)
1396 case Py_EQ
: istrue
= diff
== 0; break;
1397 case Py_NE
: istrue
= diff
!= 0; break;
1398 case Py_LE
: istrue
= diff
<= 0; break;
1399 case Py_GE
: istrue
= diff
>= 0; break;
1400 case Py_LT
: istrue
= diff
< 0; break;
1401 case Py_GT
: istrue
= diff
> 0; break;
1403 assert(! "op unknown");
1404 istrue
= 0; /* To shut up compiler */
1406 result
= istrue
? Py_True
: Py_False
;
1411 /* Raises a "can't compare" TypeError and returns NULL. */
1413 cmperror(PyObject
*a
, PyObject
*b
)
1415 PyErr_Format(PyExc_TypeError
,
1416 "can't compare %s to %s",
1417 a
->ob_type
->tp_name
, b
->ob_type
->tp_name
);
1421 /* ---------------------------------------------------------------------------
1422 * Cached Python objects; these are set by the module init function.
1425 /* Conversion factors. */
1426 static PyObject
*us_per_us
= NULL
; /* 1 */
1427 static PyObject
*us_per_ms
= NULL
; /* 1000 */
1428 static PyObject
*us_per_second
= NULL
; /* 1000000 */
1429 static PyObject
*us_per_minute
= NULL
; /* 1e6 * 60 as Python int */
1430 static PyObject
*us_per_hour
= NULL
; /* 1e6 * 3600 as Python long */
1431 static PyObject
*us_per_day
= NULL
; /* 1e6 * 3600 * 24 as Python long */
1432 static PyObject
*us_per_week
= NULL
; /* 1e6*3600*24*7 as Python long */
1433 static PyObject
*seconds_per_day
= NULL
; /* 3600*24 as Python int */
1435 /* ---------------------------------------------------------------------------
1436 * Class implementations.
1440 * PyDateTime_Delta implementation.
1443 /* Convert a timedelta to a number of us,
1444 * (24*3600*self.days + self.seconds)*1000000 + self.microseconds
1445 * as a Python int or long.
1446 * Doing mixed-radix arithmetic by hand instead is excruciating in C,
1447 * due to ubiquitous overflow possibilities.
1450 delta_to_microseconds(PyDateTime_Delta
*self
)
1452 PyObject
*x1
= NULL
;
1453 PyObject
*x2
= NULL
;
1454 PyObject
*x3
= NULL
;
1455 PyObject
*result
= NULL
;
1457 x1
= PyInt_FromLong(GET_TD_DAYS(self
));
1460 x2
= PyNumber_Multiply(x1
, seconds_per_day
); /* days in seconds */
1466 /* x2 has days in seconds */
1467 x1
= PyInt_FromLong(GET_TD_SECONDS(self
)); /* seconds */
1470 x3
= PyNumber_Add(x1
, x2
); /* days and seconds in seconds */
1477 /* x3 has days+seconds in seconds */
1478 x1
= PyNumber_Multiply(x3
, us_per_second
); /* us */
1484 /* x1 has days+seconds in us */
1485 x2
= PyInt_FromLong(GET_TD_MICROSECONDS(self
));
1488 result
= PyNumber_Add(x1
, x2
);
1497 /* Convert a number of us (as a Python int or long) to a timedelta.
1500 microseconds_to_delta_ex(PyObject
*pyus
, PyTypeObject
*type
)
1507 PyObject
*tuple
= NULL
;
1508 PyObject
*num
= NULL
;
1509 PyObject
*result
= NULL
;
1511 tuple
= PyNumber_Divmod(pyus
, us_per_second
);
1515 num
= PyTuple_GetItem(tuple
, 1); /* us */
1518 temp
= PyLong_AsLong(num
);
1520 if (temp
== -1 && PyErr_Occurred())
1522 assert(0 <= temp
&& temp
< 1000000);
1525 /* The divisor was positive, so this must be an error. */
1526 assert(PyErr_Occurred());
1530 num
= PyTuple_GetItem(tuple
, 0); /* leftover seconds */
1536 tuple
= PyNumber_Divmod(num
, seconds_per_day
);
1541 num
= PyTuple_GetItem(tuple
, 1); /* seconds */
1544 temp
= PyLong_AsLong(num
);
1546 if (temp
== -1 && PyErr_Occurred())
1548 assert(0 <= temp
&& temp
< 24*3600);
1552 /* The divisor was positive, so this must be an error. */
1553 assert(PyErr_Occurred());
1557 num
= PyTuple_GetItem(tuple
, 0); /* leftover days */
1561 temp
= PyLong_AsLong(num
);
1562 if (temp
== -1 && PyErr_Occurred())
1565 if ((long)d
!= temp
) {
1566 PyErr_SetString(PyExc_OverflowError
, "normalized days too "
1567 "large to fit in a C int");
1570 result
= new_delta_ex(d
, s
, us
, 0, type
);
1578 #define microseconds_to_delta(pymicros) \
1579 microseconds_to_delta_ex(pymicros, &PyDateTime_DeltaType)
1582 multiply_int_timedelta(PyObject
*intobj
, PyDateTime_Delta
*delta
)
1588 pyus_in
= delta_to_microseconds(delta
);
1589 if (pyus_in
== NULL
)
1592 pyus_out
= PyNumber_Multiply(pyus_in
, intobj
);
1594 if (pyus_out
== NULL
)
1597 result
= microseconds_to_delta(pyus_out
);
1598 Py_DECREF(pyus_out
);
1603 divide_timedelta_int(PyDateTime_Delta
*delta
, PyObject
*intobj
)
1609 pyus_in
= delta_to_microseconds(delta
);
1610 if (pyus_in
== NULL
)
1613 pyus_out
= PyNumber_FloorDivide(pyus_in
, intobj
);
1615 if (pyus_out
== NULL
)
1618 result
= microseconds_to_delta(pyus_out
);
1619 Py_DECREF(pyus_out
);
1624 delta_add(PyObject
*left
, PyObject
*right
)
1626 PyObject
*result
= Py_NotImplemented
;
1628 if (PyDelta_Check(left
) && PyDelta_Check(right
)) {
1630 /* The C-level additions can't overflow because of the
1633 int days
= GET_TD_DAYS(left
) + GET_TD_DAYS(right
);
1634 int seconds
= GET_TD_SECONDS(left
) + GET_TD_SECONDS(right
);
1635 int microseconds
= GET_TD_MICROSECONDS(left
) +
1636 GET_TD_MICROSECONDS(right
);
1637 result
= new_delta(days
, seconds
, microseconds
, 1);
1640 if (result
== Py_NotImplemented
)
1646 delta_negative(PyDateTime_Delta
*self
)
1648 return new_delta(-GET_TD_DAYS(self
),
1649 -GET_TD_SECONDS(self
),
1650 -GET_TD_MICROSECONDS(self
),
1655 delta_positive(PyDateTime_Delta
*self
)
1657 /* Could optimize this (by returning self) if this isn't a
1658 * subclass -- but who uses unary + ? Approximately nobody.
1660 return new_delta(GET_TD_DAYS(self
),
1661 GET_TD_SECONDS(self
),
1662 GET_TD_MICROSECONDS(self
),
1667 delta_abs(PyDateTime_Delta
*self
)
1671 assert(GET_TD_MICROSECONDS(self
) >= 0);
1672 assert(GET_TD_SECONDS(self
) >= 0);
1674 if (GET_TD_DAYS(self
) < 0)
1675 result
= delta_negative(self
);
1677 result
= delta_positive(self
);
1683 delta_subtract(PyObject
*left
, PyObject
*right
)
1685 PyObject
*result
= Py_NotImplemented
;
1687 if (PyDelta_Check(left
) && PyDelta_Check(right
)) {
1689 PyObject
*minus_right
= PyNumber_Negative(right
);
1691 result
= delta_add(left
, minus_right
);
1692 Py_DECREF(minus_right
);
1698 if (result
== Py_NotImplemented
)
1703 /* This is more natural as a tp_compare, but doesn't work then: for whatever
1704 * reason, Python's try_3way_compare ignores tp_compare unless
1705 * PyInstance_Check returns true, but these aren't old-style classes.
1708 delta_richcompare(PyDateTime_Delta
*self
, PyObject
*other
, int op
)
1710 int diff
= 42; /* nonsense */
1712 if (PyDelta_Check(other
)) {
1713 diff
= GET_TD_DAYS(self
) - GET_TD_DAYS(other
);
1715 diff
= GET_TD_SECONDS(self
) - GET_TD_SECONDS(other
);
1717 diff
= GET_TD_MICROSECONDS(self
) -
1718 GET_TD_MICROSECONDS(other
);
1721 else if (op
== Py_EQ
|| op
== Py_NE
)
1722 diff
= 1; /* any non-zero value will do */
1724 else /* stop this from falling back to address comparison */
1725 return cmperror((PyObject
*)self
, other
);
1727 return diff_to_bool(diff
, op
);
1730 static PyObject
*delta_getstate(PyDateTime_Delta
*self
);
1733 delta_hash(PyDateTime_Delta
*self
)
1735 if (self
->hashcode
== -1) {
1736 PyObject
*temp
= delta_getstate(self
);
1738 self
->hashcode
= PyObject_Hash(temp
);
1742 return self
->hashcode
;
1746 delta_multiply(PyObject
*left
, PyObject
*right
)
1748 PyObject
*result
= Py_NotImplemented
;
1750 if (PyDelta_Check(left
)) {
1752 if (PyInt_Check(right
) || PyLong_Check(right
))
1753 result
= multiply_int_timedelta(right
,
1754 (PyDateTime_Delta
*) left
);
1756 else if (PyInt_Check(left
) || PyLong_Check(left
))
1757 result
= multiply_int_timedelta(left
,
1758 (PyDateTime_Delta
*) right
);
1760 if (result
== Py_NotImplemented
)
1766 delta_divide(PyObject
*left
, PyObject
*right
)
1768 PyObject
*result
= Py_NotImplemented
;
1770 if (PyDelta_Check(left
)) {
1772 if (PyInt_Check(right
) || PyLong_Check(right
))
1773 result
= divide_timedelta_int(
1774 (PyDateTime_Delta
*)left
,
1778 if (result
== Py_NotImplemented
)
1783 /* Fold in the value of the tag ("seconds", "weeks", etc) component of a
1784 * timedelta constructor. sofar is the # of microseconds accounted for
1785 * so far, and there are factor microseconds per current unit, the number
1786 * of which is given by num. num * factor is added to sofar in a
1787 * numerically careful way, and that's the result. Any fractional
1788 * microseconds left over (this can happen if num is a float type) are
1789 * added into *leftover.
1790 * Note that there are many ways this can give an error (NULL) return.
1793 accum(const char* tag
, PyObject
*sofar
, PyObject
*num
, PyObject
*factor
,
1799 assert(num
!= NULL
);
1801 if (PyInt_Check(num
) || PyLong_Check(num
)) {
1802 prod
= PyNumber_Multiply(num
, factor
);
1805 sum
= PyNumber_Add(sofar
, prod
);
1810 if (PyFloat_Check(num
)) {
1817 /* The Plan: decompose num into an integer part and a
1818 * fractional part, num = intpart + fracpart.
1819 * Then num * factor ==
1820 * intpart * factor + fracpart * factor
1821 * and the LHS can be computed exactly in long arithmetic.
1822 * The RHS is again broken into an int part and frac part.
1823 * and the frac part is added into *leftover.
1825 dnum
= PyFloat_AsDouble(num
);
1826 if (dnum
== -1.0 && PyErr_Occurred())
1828 fracpart
= modf(dnum
, &intpart
);
1829 x
= PyLong_FromDouble(intpart
);
1833 prod
= PyNumber_Multiply(x
, factor
);
1838 sum
= PyNumber_Add(sofar
, prod
);
1843 if (fracpart
== 0.0)
1845 /* So far we've lost no information. Dealing with the
1846 * fractional part requires float arithmetic, and may
1847 * lose a little info.
1849 assert(PyInt_Check(factor
) || PyLong_Check(factor
));
1850 if (PyInt_Check(factor
))
1851 dnum
= (double)PyInt_AsLong(factor
);
1853 dnum
= PyLong_AsDouble(factor
);
1856 fracpart
= modf(dnum
, &intpart
);
1857 x
= PyLong_FromDouble(intpart
);
1863 y
= PyNumber_Add(sum
, x
);
1866 *leftover
+= fracpart
;
1870 PyErr_Format(PyExc_TypeError
,
1871 "unsupported type for timedelta %s component: %s",
1872 tag
, num
->ob_type
->tp_name
);
1877 delta_new(PyTypeObject
*type
, PyObject
*args
, PyObject
*kw
)
1879 PyObject
*self
= NULL
;
1881 /* Argument objects. */
1882 PyObject
*day
= NULL
;
1883 PyObject
*second
= NULL
;
1884 PyObject
*us
= NULL
;
1885 PyObject
*ms
= NULL
;
1886 PyObject
*minute
= NULL
;
1887 PyObject
*hour
= NULL
;
1888 PyObject
*week
= NULL
;
1890 PyObject
*x
= NULL
; /* running sum of microseconds */
1891 PyObject
*y
= NULL
; /* temp sum of microseconds */
1892 double leftover_us
= 0.0;
1894 static const char *keywords
[] = {
1895 "days", "seconds", "microseconds", "milliseconds",
1896 "minutes", "hours", "weeks", NULL
1899 if (PyArg_ParseTupleAndKeywords(args
, kw
, "|OOOOOOO:__new__",
1902 &ms
, &minute
, &hour
, &week
) == 0)
1905 x
= PyInt_FromLong(0);
1916 y
= accum("microseconds", x
, us
, us_per_us
, &leftover_us
);
1920 y
= accum("milliseconds", x
, ms
, us_per_ms
, &leftover_us
);
1924 y
= accum("seconds", x
, second
, us_per_second
, &leftover_us
);
1928 y
= accum("minutes", x
, minute
, us_per_minute
, &leftover_us
);
1932 y
= accum("hours", x
, hour
, us_per_hour
, &leftover_us
);
1936 y
= accum("days", x
, day
, us_per_day
, &leftover_us
);
1940 y
= accum("weeks", x
, week
, us_per_week
, &leftover_us
);
1944 /* Round to nearest whole # of us, and add into x. */
1945 PyObject
*temp
= PyLong_FromLong(round_to_long(leftover_us
));
1950 y
= PyNumber_Add(x
, temp
);
1955 self
= microseconds_to_delta_ex(x
, type
);
1964 delta_nonzero(PyDateTime_Delta
*self
)
1966 return (GET_TD_DAYS(self
) != 0
1967 || GET_TD_SECONDS(self
) != 0
1968 || GET_TD_MICROSECONDS(self
) != 0);
1972 delta_repr(PyDateTime_Delta
*self
)
1974 if (GET_TD_MICROSECONDS(self
) != 0)
1975 return PyString_FromFormat("%s(%d, %d, %d)",
1976 self
->ob_type
->tp_name
,
1978 GET_TD_SECONDS(self
),
1979 GET_TD_MICROSECONDS(self
));
1980 if (GET_TD_SECONDS(self
) != 0)
1981 return PyString_FromFormat("%s(%d, %d)",
1982 self
->ob_type
->tp_name
,
1984 GET_TD_SECONDS(self
));
1986 return PyString_FromFormat("%s(%d)",
1987 self
->ob_type
->tp_name
,
1992 delta_str(PyDateTime_Delta
*self
)
1994 int days
= GET_TD_DAYS(self
);
1995 int seconds
= GET_TD_SECONDS(self
);
1996 int us
= GET_TD_MICROSECONDS(self
);
2001 size_t buflen
= sizeof(buf
);
2004 minutes
= divmod(seconds
, 60, &seconds
);
2005 hours
= divmod(minutes
, 60, &minutes
);
2008 n
= PyOS_snprintf(pbuf
, buflen
, "%d day%s, ", days
,
2009 (days
== 1 || days
== -1) ? "" : "s");
2010 if (n
< 0 || (size_t)n
>= buflen
)
2013 buflen
-= (size_t)n
;
2016 n
= PyOS_snprintf(pbuf
, buflen
, "%d:%02d:%02d",
2017 hours
, minutes
, seconds
);
2018 if (n
< 0 || (size_t)n
>= buflen
)
2021 buflen
-= (size_t)n
;
2024 n
= PyOS_snprintf(pbuf
, buflen
, ".%06d", us
);
2025 if (n
< 0 || (size_t)n
>= buflen
)
2030 return PyString_FromStringAndSize(buf
, pbuf
- buf
);
2033 PyErr_SetString(PyExc_SystemError
, "goofy result from PyOS_snprintf");
2037 /* Pickle support, a simple use of __reduce__. */
2039 /* __getstate__ isn't exposed */
2041 delta_getstate(PyDateTime_Delta
*self
)
2043 return Py_BuildValue("iii", GET_TD_DAYS(self
),
2044 GET_TD_SECONDS(self
),
2045 GET_TD_MICROSECONDS(self
));
2049 delta_reduce(PyDateTime_Delta
* self
)
2051 return Py_BuildValue("ON", self
->ob_type
, delta_getstate(self
));
2054 #define OFFSET(field) offsetof(PyDateTime_Delta, field)
2056 static PyMemberDef delta_members
[] = {
2058 {"days", T_INT
, OFFSET(days
), READONLY
,
2059 PyDoc_STR("Number of days.")},
2061 {"seconds", T_INT
, OFFSET(seconds
), READONLY
,
2062 PyDoc_STR("Number of seconds (>= 0 and less than 1 day).")},
2064 {"microseconds", T_INT
, OFFSET(microseconds
), READONLY
,
2065 PyDoc_STR("Number of microseconds (>= 0 and less than 1 second).")},
2069 static PyMethodDef delta_methods
[] = {
2070 {"__reduce__", (PyCFunction
)delta_reduce
, METH_NOARGS
,
2071 PyDoc_STR("__reduce__() -> (cls, state)")},
2076 static char delta_doc
[] =
2077 PyDoc_STR("Difference between two datetime values.");
2079 static PyNumberMethods delta_as_number
= {
2080 delta_add
, /* nb_add */
2081 delta_subtract
, /* nb_subtract */
2082 delta_multiply
, /* nb_multiply */
2083 delta_divide
, /* nb_divide */
2084 0, /* nb_remainder */
2087 (unaryfunc
)delta_negative
, /* nb_negative */
2088 (unaryfunc
)delta_positive
, /* nb_positive */
2089 (unaryfunc
)delta_abs
, /* nb_absolute */
2090 (inquiry
)delta_nonzero
, /* nb_nonzero */
2103 0, /*nb_inplace_add*/
2104 0, /*nb_inplace_subtract*/
2105 0, /*nb_inplace_multiply*/
2106 0, /*nb_inplace_divide*/
2107 0, /*nb_inplace_remainder*/
2108 0, /*nb_inplace_power*/
2109 0, /*nb_inplace_lshift*/
2110 0, /*nb_inplace_rshift*/
2111 0, /*nb_inplace_and*/
2112 0, /*nb_inplace_xor*/
2113 0, /*nb_inplace_or*/
2114 delta_divide
, /* nb_floor_divide */
2115 0, /* nb_true_divide */
2116 0, /* nb_inplace_floor_divide */
2117 0, /* nb_inplace_true_divide */
2120 static PyTypeObject PyDateTime_DeltaType
= {
2121 PyObject_HEAD_INIT(NULL
)
2123 "datetime.timedelta", /* tp_name */
2124 sizeof(PyDateTime_Delta
), /* tp_basicsize */
2125 0, /* tp_itemsize */
2131 (reprfunc
)delta_repr
, /* tp_repr */
2132 &delta_as_number
, /* tp_as_number */
2133 0, /* tp_as_sequence */
2134 0, /* tp_as_mapping */
2135 (hashfunc
)delta_hash
, /* tp_hash */
2137 (reprfunc
)delta_str
, /* tp_str */
2138 PyObject_GenericGetAttr
, /* tp_getattro */
2139 0, /* tp_setattro */
2140 0, /* tp_as_buffer */
2141 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_CHECKTYPES
|
2142 Py_TPFLAGS_BASETYPE
, /* tp_flags */
2143 delta_doc
, /* tp_doc */
2144 0, /* tp_traverse */
2146 (richcmpfunc
)delta_richcompare
, /* tp_richcompare */
2147 0, /* tp_weaklistoffset */
2149 0, /* tp_iternext */
2150 delta_methods
, /* tp_methods */
2151 delta_members
, /* tp_members */
2155 0, /* tp_descr_get */
2156 0, /* tp_descr_set */
2157 0, /* tp_dictoffset */
2160 delta_new
, /* tp_new */
2165 * PyDateTime_Date implementation.
2168 /* Accessor properties. */
2171 date_year(PyDateTime_Date
*self
, void *unused
)
2173 return PyInt_FromLong(GET_YEAR(self
));
2177 date_month(PyDateTime_Date
*self
, void *unused
)
2179 return PyInt_FromLong(GET_MONTH(self
));
2183 date_day(PyDateTime_Date
*self
, void *unused
)
2185 return PyInt_FromLong(GET_DAY(self
));
2188 static PyGetSetDef date_getset
[] = {
2189 {"year", (getter
)date_year
},
2190 {"month", (getter
)date_month
},
2191 {"day", (getter
)date_day
},
2197 static const char *date_kws
[] = {"year", "month", "day", NULL
};
2200 date_new(PyTypeObject
*type
, PyObject
*args
, PyObject
*kw
)
2202 PyObject
*self
= NULL
;
2208 /* Check for invocation from pickle with __getstate__ state */
2209 if (PyTuple_GET_SIZE(args
) == 1 &&
2210 PyString_Check(state
= PyTuple_GET_ITEM(args
, 0)) &&
2211 PyString_GET_SIZE(state
) == _PyDateTime_DATE_DATASIZE
&&
2212 MONTH_IS_SANE(PyString_AS_STRING(state
)[2]))
2214 PyDateTime_Date
*me
;
2216 me
= (PyDateTime_Date
*) (type
->tp_alloc(type
, 0));
2218 char *pdata
= PyString_AS_STRING(state
);
2219 memcpy(me
->data
, pdata
, _PyDateTime_DATE_DATASIZE
);
2222 return (PyObject
*)me
;
2225 if (PyArg_ParseTupleAndKeywords(args
, kw
, "iii", date_kws
,
2226 &year
, &month
, &day
)) {
2227 if (check_date_args(year
, month
, day
) < 0)
2229 self
= new_date_ex(year
, month
, day
, type
);
2234 /* Return new date from localtime(t). */
2236 date_local_from_time_t(PyObject
*cls
, double ts
)
2240 PyObject
*result
= NULL
;
2242 t
= _PyTime_DoubleToTimet(ts
);
2243 if (t
== (time_t)-1 && PyErr_Occurred())
2247 result
= PyObject_CallFunction(cls
, "iii",
2252 PyErr_SetString(PyExc_ValueError
,
2253 "timestamp out of range for "
2254 "platform localtime() function");
2258 /* Return new date from current time.
2259 * We say this is equivalent to fromtimestamp(time.time()), and the
2260 * only way to be sure of that is to *call* time.time(). That's not
2261 * generally the same as calling C's time.
2264 date_today(PyObject
*cls
, PyObject
*dummy
)
2273 /* Note well: today() is a class method, so this may not call
2274 * date.fromtimestamp. For example, it may call
2275 * datetime.fromtimestamp. That's why we need all the accuracy
2276 * time.time() delivers; if someone were gonzo about optimization,
2277 * date.today() could get away with plain C time().
2279 result
= PyObject_CallMethod(cls
, "fromtimestamp", "O", time
);
2284 /* Return new date from given timestamp (Python timestamp -- a double). */
2286 date_fromtimestamp(PyObject
*cls
, PyObject
*args
)
2289 PyObject
*result
= NULL
;
2291 if (PyArg_ParseTuple(args
, "d:fromtimestamp", ×tamp
))
2292 result
= date_local_from_time_t(cls
, timestamp
);
2296 /* Return new date from proleptic Gregorian ordinal. Raises ValueError if
2297 * the ordinal is out of range.
2300 date_fromordinal(PyObject
*cls
, PyObject
*args
)
2302 PyObject
*result
= NULL
;
2305 if (PyArg_ParseTuple(args
, "i:fromordinal", &ordinal
)) {
2311 PyErr_SetString(PyExc_ValueError
, "ordinal must be "
2314 ord_to_ymd(ordinal
, &year
, &month
, &day
);
2315 result
= PyObject_CallFunction(cls
, "iii",
2326 /* date + timedelta -> date. If arg negate is true, subtract the timedelta
2330 add_date_timedelta(PyDateTime_Date
*date
, PyDateTime_Delta
*delta
, int negate
)
2332 PyObject
*result
= NULL
;
2333 int year
= GET_YEAR(date
);
2334 int month
= GET_MONTH(date
);
2335 int deltadays
= GET_TD_DAYS(delta
);
2336 /* C-level overflow is impossible because |deltadays| < 1e9. */
2337 int day
= GET_DAY(date
) + (negate
? -deltadays
: deltadays
);
2339 if (normalize_date(&year
, &month
, &day
) >= 0)
2340 result
= new_date(year
, month
, day
);
2345 date_add(PyObject
*left
, PyObject
*right
)
2347 if (PyDateTime_Check(left
) || PyDateTime_Check(right
)) {
2348 Py_INCREF(Py_NotImplemented
);
2349 return Py_NotImplemented
;
2351 if (PyDate_Check(left
)) {
2353 if (PyDelta_Check(right
))
2355 return add_date_timedelta((PyDateTime_Date
*) left
,
2356 (PyDateTime_Delta
*) right
,
2361 * 'right' must be one of us, or we wouldn't have been called
2363 if (PyDelta_Check(left
))
2365 return add_date_timedelta((PyDateTime_Date
*) right
,
2366 (PyDateTime_Delta
*) left
,
2369 Py_INCREF(Py_NotImplemented
);
2370 return Py_NotImplemented
;
2374 date_subtract(PyObject
*left
, PyObject
*right
)
2376 if (PyDateTime_Check(left
) || PyDateTime_Check(right
)) {
2377 Py_INCREF(Py_NotImplemented
);
2378 return Py_NotImplemented
;
2380 if (PyDate_Check(left
)) {
2381 if (PyDate_Check(right
)) {
2383 int left_ord
= ymd_to_ord(GET_YEAR(left
),
2386 int right_ord
= ymd_to_ord(GET_YEAR(right
),
2389 return new_delta(left_ord
- right_ord
, 0, 0, 0);
2391 if (PyDelta_Check(right
)) {
2393 return add_date_timedelta((PyDateTime_Date
*) left
,
2394 (PyDateTime_Delta
*) right
,
2398 Py_INCREF(Py_NotImplemented
);
2399 return Py_NotImplemented
;
2403 /* Various ways to turn a date into a string. */
2406 date_repr(PyDateTime_Date
*self
)
2409 const char *typename
;
2411 typename
= self
->ob_type
->tp_name
;
2412 PyOS_snprintf(buffer
, sizeof(buffer
), "%s(%d, %d, %d)",
2414 GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
));
2416 return PyString_FromString(buffer
);
2420 date_isoformat(PyDateTime_Date
*self
)
2424 isoformat_date(self
, buffer
, sizeof(buffer
));
2425 return PyString_FromString(buffer
);
2428 /* str() calls the appropriate isoformat() method. */
2430 date_str(PyDateTime_Date
*self
)
2432 return PyObject_CallMethod((PyObject
*)self
, "isoformat", "()");
2437 date_ctime(PyDateTime_Date
*self
)
2439 return format_ctime(self
, 0, 0, 0);
2443 date_strftime(PyDateTime_Date
*self
, PyObject
*args
, PyObject
*kw
)
2445 /* This method can be inherited, and needs to call the
2446 * timetuple() method appropriate to self's class.
2451 static const char *keywords
[] = {"format", NULL
};
2453 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "O!:strftime", keywords
,
2454 &PyString_Type
, &format
))
2457 tuple
= PyObject_CallMethod((PyObject
*)self
, "timetuple", "()");
2460 result
= wrap_strftime((PyObject
*)self
, format
, tuple
,
2469 date_isoweekday(PyDateTime_Date
*self
)
2471 int dow
= weekday(GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
));
2473 return PyInt_FromLong(dow
+ 1);
2477 date_isocalendar(PyDateTime_Date
*self
)
2479 int year
= GET_YEAR(self
);
2480 int week1_monday
= iso_week1_monday(year
);
2481 int today
= ymd_to_ord(year
, GET_MONTH(self
), GET_DAY(self
));
2485 week
= divmod(today
- week1_monday
, 7, &day
);
2488 week1_monday
= iso_week1_monday(year
);
2489 week
= divmod(today
- week1_monday
, 7, &day
);
2491 else if (week
>= 52 && today
>= iso_week1_monday(year
+ 1)) {
2495 return Py_BuildValue("iii", year
, week
+ 1, day
+ 1);
2498 /* Miscellaneous methods. */
2500 /* This is more natural as a tp_compare, but doesn't work then: for whatever
2501 * reason, Python's try_3way_compare ignores tp_compare unless
2502 * PyInstance_Check returns true, but these aren't old-style classes.
2505 date_richcompare(PyDateTime_Date
*self
, PyObject
*other
, int op
)
2507 int diff
= 42; /* nonsense */
2509 if (PyDate_Check(other
))
2510 diff
= memcmp(self
->data
, ((PyDateTime_Date
*)other
)->data
,
2511 _PyDateTime_DATE_DATASIZE
);
2513 else if (PyObject_HasAttrString(other
, "timetuple")) {
2514 /* A hook for other kinds of date objects. */
2515 Py_INCREF(Py_NotImplemented
);
2516 return Py_NotImplemented
;
2518 else if (op
== Py_EQ
|| op
== Py_NE
)
2519 diff
= 1; /* any non-zero value will do */
2521 else /* stop this from falling back to address comparison */
2522 return cmperror((PyObject
*)self
, other
);
2524 return diff_to_bool(diff
, op
);
2528 date_timetuple(PyDateTime_Date
*self
)
2530 return build_struct_time(GET_YEAR(self
),
2537 date_replace(PyDateTime_Date
*self
, PyObject
*args
, PyObject
*kw
)
2541 int year
= GET_YEAR(self
);
2542 int month
= GET_MONTH(self
);
2543 int day
= GET_DAY(self
);
2545 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "|iii:replace", date_kws
,
2546 &year
, &month
, &day
))
2548 tuple
= Py_BuildValue("iii", year
, month
, day
);
2551 clone
= date_new(self
->ob_type
, tuple
, NULL
);
2556 static PyObject
*date_getstate(PyDateTime_Date
*self
);
2559 date_hash(PyDateTime_Date
*self
)
2561 if (self
->hashcode
== -1) {
2562 PyObject
*temp
= date_getstate(self
);
2564 self
->hashcode
= PyObject_Hash(temp
);
2568 return self
->hashcode
;
2572 date_toordinal(PyDateTime_Date
*self
)
2574 return PyInt_FromLong(ymd_to_ord(GET_YEAR(self
), GET_MONTH(self
),
2579 date_weekday(PyDateTime_Date
*self
)
2581 int dow
= weekday(GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
));
2583 return PyInt_FromLong(dow
);
2586 /* Pickle support, a simple use of __reduce__. */
2588 /* __getstate__ isn't exposed */
2590 date_getstate(PyDateTime_Date
*self
)
2592 return Py_BuildValue(
2594 PyString_FromStringAndSize((char *)self
->data
,
2595 _PyDateTime_DATE_DATASIZE
));
2599 date_reduce(PyDateTime_Date
*self
, PyObject
*arg
)
2601 return Py_BuildValue("(ON)", self
->ob_type
, date_getstate(self
));
2604 static PyMethodDef date_methods
[] = {
2606 /* Class methods: */
2608 {"fromtimestamp", (PyCFunction
)date_fromtimestamp
, METH_VARARGS
|
2610 PyDoc_STR("timestamp -> local date from a POSIX timestamp (like "
2613 {"fromordinal", (PyCFunction
)date_fromordinal
, METH_VARARGS
|
2615 PyDoc_STR("int -> date corresponding to a proleptic Gregorian "
2618 {"today", (PyCFunction
)date_today
, METH_NOARGS
| METH_CLASS
,
2619 PyDoc_STR("Current date or datetime: same as "
2620 "self.__class__.fromtimestamp(time.time()).")},
2622 /* Instance methods: */
2624 {"ctime", (PyCFunction
)date_ctime
, METH_NOARGS
,
2625 PyDoc_STR("Return ctime() style string.")},
2627 {"strftime", (PyCFunction
)date_strftime
, METH_KEYWORDS
,
2628 PyDoc_STR("format -> strftime() style string.")},
2630 {"timetuple", (PyCFunction
)date_timetuple
, METH_NOARGS
,
2631 PyDoc_STR("Return time tuple, compatible with time.localtime().")},
2633 {"isocalendar", (PyCFunction
)date_isocalendar
, METH_NOARGS
,
2634 PyDoc_STR("Return a 3-tuple containing ISO year, week number, and "
2637 {"isoformat", (PyCFunction
)date_isoformat
, METH_NOARGS
,
2638 PyDoc_STR("Return string in ISO 8601 format, YYYY-MM-DD.")},
2640 {"isoweekday", (PyCFunction
)date_isoweekday
, METH_NOARGS
,
2641 PyDoc_STR("Return the day of the week represented by the date.\n"
2642 "Monday == 1 ... Sunday == 7")},
2644 {"toordinal", (PyCFunction
)date_toordinal
, METH_NOARGS
,
2645 PyDoc_STR("Return proleptic Gregorian ordinal. January 1 of year "
2648 {"weekday", (PyCFunction
)date_weekday
, METH_NOARGS
,
2649 PyDoc_STR("Return the day of the week represented by the date.\n"
2650 "Monday == 0 ... Sunday == 6")},
2652 {"replace", (PyCFunction
)date_replace
, METH_KEYWORDS
,
2653 PyDoc_STR("Return date with new specified fields.")},
2655 {"__reduce__", (PyCFunction
)date_reduce
, METH_NOARGS
,
2656 PyDoc_STR("__reduce__() -> (cls, state)")},
2661 static char date_doc
[] =
2662 PyDoc_STR("date(year, month, day) --> date object");
2664 static PyNumberMethods date_as_number
= {
2665 date_add
, /* nb_add */
2666 date_subtract
, /* nb_subtract */
2667 0, /* nb_multiply */
2669 0, /* nb_remainder */
2672 0, /* nb_negative */
2673 0, /* nb_positive */
2674 0, /* nb_absolute */
2678 static PyTypeObject PyDateTime_DateType
= {
2679 PyObject_HEAD_INIT(NULL
)
2681 "datetime.date", /* tp_name */
2682 sizeof(PyDateTime_Date
), /* tp_basicsize */
2683 0, /* tp_itemsize */
2689 (reprfunc
)date_repr
, /* tp_repr */
2690 &date_as_number
, /* tp_as_number */
2691 0, /* tp_as_sequence */
2692 0, /* tp_as_mapping */
2693 (hashfunc
)date_hash
, /* tp_hash */
2695 (reprfunc
)date_str
, /* tp_str */
2696 PyObject_GenericGetAttr
, /* tp_getattro */
2697 0, /* tp_setattro */
2698 0, /* tp_as_buffer */
2699 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_CHECKTYPES
|
2700 Py_TPFLAGS_BASETYPE
, /* tp_flags */
2701 date_doc
, /* tp_doc */
2702 0, /* tp_traverse */
2704 (richcmpfunc
)date_richcompare
, /* tp_richcompare */
2705 0, /* tp_weaklistoffset */
2707 0, /* tp_iternext */
2708 date_methods
, /* tp_methods */
2710 date_getset
, /* tp_getset */
2713 0, /* tp_descr_get */
2714 0, /* tp_descr_set */
2715 0, /* tp_dictoffset */
2718 date_new
, /* tp_new */
2723 * PyDateTime_TZInfo implementation.
2726 /* This is a pure abstract base class, so doesn't do anything beyond
2727 * raising NotImplemented exceptions. Real tzinfo classes need
2728 * to derive from this. This is mostly for clarity, and for efficiency in
2729 * datetime and time constructors (their tzinfo arguments need to
2730 * be subclasses of this tzinfo class, which is easy and quick to check).
2732 * Note: For reasons having to do with pickling of subclasses, we have
2733 * to allow tzinfo objects to be instantiated. This wasn't an issue
2734 * in the Python implementation (__init__() could raise NotImplementedError
2735 * there without ill effect), but doing so in the C implementation hit a
2740 tzinfo_nogo(const char* methodname
)
2742 PyErr_Format(PyExc_NotImplementedError
,
2743 "a tzinfo subclass must implement %s()",
2748 /* Methods. A subclass must implement these. */
2751 tzinfo_tzname(PyDateTime_TZInfo
*self
, PyObject
*dt
)
2753 return tzinfo_nogo("tzname");
2757 tzinfo_utcoffset(PyDateTime_TZInfo
*self
, PyObject
*dt
)
2759 return tzinfo_nogo("utcoffset");
2763 tzinfo_dst(PyDateTime_TZInfo
*self
, PyObject
*dt
)
2765 return tzinfo_nogo("dst");
2769 tzinfo_fromutc(PyDateTime_TZInfo
*self
, PyDateTime_DateTime
*dt
)
2771 int y
, m
, d
, hh
, mm
, ss
, us
;
2778 if (! PyDateTime_Check(dt
)) {
2779 PyErr_SetString(PyExc_TypeError
,
2780 "fromutc: argument must be a datetime");
2783 if (! HASTZINFO(dt
) || dt
->tzinfo
!= (PyObject
*)self
) {
2784 PyErr_SetString(PyExc_ValueError
, "fromutc: dt.tzinfo "
2789 off
= call_utcoffset(dt
->tzinfo
, (PyObject
*)dt
, &none
);
2790 if (off
== -1 && PyErr_Occurred())
2793 PyErr_SetString(PyExc_ValueError
, "fromutc: non-None "
2794 "utcoffset() result required");
2798 dst
= call_dst(dt
->tzinfo
, (PyObject
*)dt
, &none
);
2799 if (dst
== -1 && PyErr_Occurred())
2802 PyErr_SetString(PyExc_ValueError
, "fromutc: non-None "
2803 "dst() result required");
2810 hh
= DATE_GET_HOUR(dt
);
2811 mm
= DATE_GET_MINUTE(dt
);
2812 ss
= DATE_GET_SECOND(dt
);
2813 us
= DATE_GET_MICROSECOND(dt
);
2817 if ((mm
< 0 || mm
>= 60) &&
2818 normalize_datetime(&y
, &m
, &d
, &hh
, &mm
, &ss
, &us
) < 0)
2820 result
= new_datetime(y
, m
, d
, hh
, mm
, ss
, us
, dt
->tzinfo
);
2824 dst
= call_dst(dt
->tzinfo
, result
, &none
);
2825 if (dst
== -1 && PyErr_Occurred())
2833 if ((mm
< 0 || mm
>= 60) &&
2834 normalize_datetime(&y
, &m
, &d
, &hh
, &mm
, &ss
, &us
) < 0)
2837 result
= new_datetime(y
, m
, d
, hh
, mm
, ss
, us
, dt
->tzinfo
);
2841 PyErr_SetString(PyExc_ValueError
, "fromutc: tz.dst() gave"
2842 "inconsistent results; cannot convert");
2844 /* fall thru to failure */
2851 * Pickle support. This is solely so that tzinfo subclasses can use
2852 * pickling -- tzinfo itself is supposed to be uninstantiable.
2856 tzinfo_reduce(PyObject
*self
)
2858 PyObject
*args
, *state
, *tmp
;
2859 PyObject
*getinitargs
, *getstate
;
2861 tmp
= PyTuple_New(0);
2865 getinitargs
= PyObject_GetAttrString(self
, "__getinitargs__");
2866 if (getinitargs
!= NULL
) {
2867 args
= PyObject_CallObject(getinitargs
, tmp
);
2868 Py_DECREF(getinitargs
);
2880 getstate
= PyObject_GetAttrString(self
, "__getstate__");
2881 if (getstate
!= NULL
) {
2882 state
= PyObject_CallObject(getstate
, tmp
);
2883 Py_DECREF(getstate
);
2884 if (state
== NULL
) {
2894 dictptr
= _PyObject_GetDictPtr(self
);
2895 if (dictptr
&& *dictptr
&& PyDict_Size(*dictptr
))
2902 if (state
== Py_None
) {
2904 return Py_BuildValue("(ON)", self
->ob_type
, args
);
2907 return Py_BuildValue("(ONN)", self
->ob_type
, args
, state
);
2910 static PyMethodDef tzinfo_methods
[] = {
2912 {"tzname", (PyCFunction
)tzinfo_tzname
, METH_O
,
2913 PyDoc_STR("datetime -> string name of time zone.")},
2915 {"utcoffset", (PyCFunction
)tzinfo_utcoffset
, METH_O
,
2916 PyDoc_STR("datetime -> minutes east of UTC (negative for "
2919 {"dst", (PyCFunction
)tzinfo_dst
, METH_O
,
2920 PyDoc_STR("datetime -> DST offset in minutes east of UTC.")},
2922 {"fromutc", (PyCFunction
)tzinfo_fromutc
, METH_O
,
2923 PyDoc_STR("datetime in UTC -> datetime in local time.")},
2925 {"__reduce__", (PyCFunction
)tzinfo_reduce
, METH_NOARGS
,
2926 PyDoc_STR("-> (cls, state)")},
2931 static char tzinfo_doc
[] =
2932 PyDoc_STR("Abstract base class for time zone info objects.");
2934 statichere PyTypeObject PyDateTime_TZInfoType
= {
2935 PyObject_HEAD_INIT(NULL
)
2937 "datetime.tzinfo", /* tp_name */
2938 sizeof(PyDateTime_TZInfo
), /* tp_basicsize */
2939 0, /* tp_itemsize */
2946 0, /* tp_as_number */
2947 0, /* tp_as_sequence */
2948 0, /* tp_as_mapping */
2952 PyObject_GenericGetAttr
, /* tp_getattro */
2953 0, /* tp_setattro */
2954 0, /* tp_as_buffer */
2955 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_CHECKTYPES
|
2956 Py_TPFLAGS_BASETYPE
, /* tp_flags */
2957 tzinfo_doc
, /* tp_doc */
2958 0, /* tp_traverse */
2960 0, /* tp_richcompare */
2961 0, /* tp_weaklistoffset */
2963 0, /* tp_iternext */
2964 tzinfo_methods
, /* tp_methods */
2969 0, /* tp_descr_get */
2970 0, /* tp_descr_set */
2971 0, /* tp_dictoffset */
2974 PyType_GenericNew
, /* tp_new */
2979 * PyDateTime_Time implementation.
2982 /* Accessor properties.
2986 time_hour(PyDateTime_Time
*self
, void *unused
)
2988 return PyInt_FromLong(TIME_GET_HOUR(self
));
2992 time_minute(PyDateTime_Time
*self
, void *unused
)
2994 return PyInt_FromLong(TIME_GET_MINUTE(self
));
2997 /* The name time_second conflicted with some platform header file. */
2999 py_time_second(PyDateTime_Time
*self
, void *unused
)
3001 return PyInt_FromLong(TIME_GET_SECOND(self
));
3005 time_microsecond(PyDateTime_Time
*self
, void *unused
)
3007 return PyInt_FromLong(TIME_GET_MICROSECOND(self
));
3011 time_tzinfo(PyDateTime_Time
*self
, void *unused
)
3013 PyObject
*result
= HASTZINFO(self
) ? self
->tzinfo
: Py_None
;
3018 static PyGetSetDef time_getset
[] = {
3019 {"hour", (getter
)time_hour
},
3020 {"minute", (getter
)time_minute
},
3021 {"second", (getter
)py_time_second
},
3022 {"microsecond", (getter
)time_microsecond
},
3023 {"tzinfo", (getter
)time_tzinfo
},
3031 static const char *time_kws
[] = {"hour", "minute", "second", "microsecond",
3035 time_new(PyTypeObject
*type
, PyObject
*args
, PyObject
*kw
)
3037 PyObject
*self
= NULL
;
3043 PyObject
*tzinfo
= Py_None
;
3045 /* Check for invocation from pickle with __getstate__ state */
3046 if (PyTuple_GET_SIZE(args
) >= 1 &&
3047 PyTuple_GET_SIZE(args
) <= 2 &&
3048 PyString_Check(state
= PyTuple_GET_ITEM(args
, 0)) &&
3049 PyString_GET_SIZE(state
) == _PyDateTime_TIME_DATASIZE
&&
3050 ((unsigned char) (PyString_AS_STRING(state
)[0])) < 24)
3052 PyDateTime_Time
*me
;
3055 if (PyTuple_GET_SIZE(args
) == 2) {
3056 tzinfo
= PyTuple_GET_ITEM(args
, 1);
3057 if (check_tzinfo_subclass(tzinfo
) < 0) {
3058 PyErr_SetString(PyExc_TypeError
, "bad "
3059 "tzinfo state arg");
3063 aware
= (char)(tzinfo
!= Py_None
);
3064 me
= (PyDateTime_Time
*) (type
->tp_alloc(type
, aware
));
3066 char *pdata
= PyString_AS_STRING(state
);
3068 memcpy(me
->data
, pdata
, _PyDateTime_TIME_DATASIZE
);
3070 me
->hastzinfo
= aware
;
3073 me
->tzinfo
= tzinfo
;
3076 return (PyObject
*)me
;
3079 if (PyArg_ParseTupleAndKeywords(args
, kw
, "|iiiiO", time_kws
,
3080 &hour
, &minute
, &second
, &usecond
,
3082 if (check_time_args(hour
, minute
, second
, usecond
) < 0)
3084 if (check_tzinfo_subclass(tzinfo
) < 0)
3086 self
= new_time_ex(hour
, minute
, second
, usecond
, tzinfo
,
3097 time_dealloc(PyDateTime_Time
*self
)
3099 if (HASTZINFO(self
)) {
3100 Py_XDECREF(self
->tzinfo
);
3102 self
->ob_type
->tp_free((PyObject
*)self
);
3106 * Indirect access to tzinfo methods.
3109 /* These are all METH_NOARGS, so don't need to check the arglist. */
3111 time_utcoffset(PyDateTime_Time
*self
, PyObject
*unused
) {
3112 return offset_as_timedelta(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3113 "utcoffset", Py_None
);
3117 time_dst(PyDateTime_Time
*self
, PyObject
*unused
) {
3118 return offset_as_timedelta(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3123 time_tzname(PyDateTime_Time
*self
, PyObject
*unused
) {
3124 return call_tzname(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3129 * Various ways to turn a time into a string.
3133 time_repr(PyDateTime_Time
*self
)
3136 const char *typename
= self
->ob_type
->tp_name
;
3137 int h
= TIME_GET_HOUR(self
);
3138 int m
= TIME_GET_MINUTE(self
);
3139 int s
= TIME_GET_SECOND(self
);
3140 int us
= TIME_GET_MICROSECOND(self
);
3141 PyObject
*result
= NULL
;
3144 PyOS_snprintf(buffer
, sizeof(buffer
),
3145 "%s(%d, %d, %d, %d)", typename
, h
, m
, s
, us
);
3147 PyOS_snprintf(buffer
, sizeof(buffer
),
3148 "%s(%d, %d, %d)", typename
, h
, m
, s
);
3150 PyOS_snprintf(buffer
, sizeof(buffer
),
3151 "%s(%d, %d)", typename
, h
, m
);
3152 result
= PyString_FromString(buffer
);
3153 if (result
!= NULL
&& HASTZINFO(self
))
3154 result
= append_keyword_tzinfo(result
, self
->tzinfo
);
3159 time_str(PyDateTime_Time
*self
)
3161 return PyObject_CallMethod((PyObject
*)self
, "isoformat", "()");
3165 time_isoformat(PyDateTime_Time
*self
)
3169 /* Reuse the time format code from the datetime type. */
3170 PyDateTime_DateTime datetime
;
3171 PyDateTime_DateTime
*pdatetime
= &datetime
;
3173 /* Copy over just the time bytes. */
3174 memcpy(pdatetime
->data
+ _PyDateTime_DATE_DATASIZE
,
3176 _PyDateTime_TIME_DATASIZE
);
3178 isoformat_time(pdatetime
, buf
, sizeof(buf
));
3179 result
= PyString_FromString(buf
);
3180 if (result
== NULL
|| ! HASTZINFO(self
) || self
->tzinfo
== Py_None
)
3183 /* We need to append the UTC offset. */
3184 if (format_utcoffset(buf
, sizeof(buf
), ":", self
->tzinfo
,
3189 PyString_ConcatAndDel(&result
, PyString_FromString(buf
));
3194 time_strftime(PyDateTime_Time
*self
, PyObject
*args
, PyObject
*kw
)
3199 static const char *keywords
[] = {"format", NULL
};
3201 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "O!:strftime", keywords
,
3202 &PyString_Type
, &format
))
3205 /* Python's strftime does insane things with the year part of the
3206 * timetuple. The year is forced to (the otherwise nonsensical)
3207 * 1900 to worm around that.
3209 tuple
= Py_BuildValue("iiiiiiiii",
3210 1900, 1, 1, /* year, month, day */
3211 TIME_GET_HOUR(self
),
3212 TIME_GET_MINUTE(self
),
3213 TIME_GET_SECOND(self
),
3214 0, 1, -1); /* weekday, daynum, dst */
3217 assert(PyTuple_Size(tuple
) == 9);
3218 result
= wrap_strftime((PyObject
*)self
, format
, tuple
, Py_None
);
3224 * Miscellaneous methods.
3227 /* This is more natural as a tp_compare, but doesn't work then: for whatever
3228 * reason, Python's try_3way_compare ignores tp_compare unless
3229 * PyInstance_Check returns true, but these aren't old-style classes.
3232 time_richcompare(PyDateTime_Time
*self
, PyObject
*other
, int op
)
3236 int offset1
, offset2
;
3238 if (! PyTime_Check(other
)) {
3239 if (op
== Py_EQ
|| op
== Py_NE
) {
3240 PyObject
*result
= op
== Py_EQ
? Py_False
: Py_True
;
3244 /* Stop this from falling back to address comparison. */
3245 return cmperror((PyObject
*)self
, other
);
3247 if (classify_two_utcoffsets((PyObject
*)self
, &offset1
, &n1
, Py_None
,
3248 other
, &offset2
, &n2
, Py_None
) < 0)
3250 assert(n1
!= OFFSET_UNKNOWN
&& n2
!= OFFSET_UNKNOWN
);
3251 /* If they're both naive, or both aware and have the same offsets,
3252 * we get off cheap. Note that if they're both naive, offset1 ==
3253 * offset2 == 0 at this point.
3255 if (n1
== n2
&& offset1
== offset2
) {
3256 diff
= memcmp(self
->data
, ((PyDateTime_Time
*)other
)->data
,
3257 _PyDateTime_TIME_DATASIZE
);
3258 return diff_to_bool(diff
, op
);
3261 if (n1
== OFFSET_AWARE
&& n2
== OFFSET_AWARE
) {
3262 assert(offset1
!= offset2
); /* else last "if" handled it */
3263 /* Convert everything except microseconds to seconds. These
3264 * can't overflow (no more than the # of seconds in 2 days).
3266 offset1
= TIME_GET_HOUR(self
) * 3600 +
3267 (TIME_GET_MINUTE(self
) - offset1
) * 60 +
3268 TIME_GET_SECOND(self
);
3269 offset2
= TIME_GET_HOUR(other
) * 3600 +
3270 (TIME_GET_MINUTE(other
) - offset2
) * 60 +
3271 TIME_GET_SECOND(other
);
3272 diff
= offset1
- offset2
;
3274 diff
= TIME_GET_MICROSECOND(self
) -
3275 TIME_GET_MICROSECOND(other
);
3276 return diff_to_bool(diff
, op
);
3280 PyErr_SetString(PyExc_TypeError
,
3281 "can't compare offset-naive and "
3282 "offset-aware times");
3287 time_hash(PyDateTime_Time
*self
)
3289 if (self
->hashcode
== -1) {
3294 n
= classify_utcoffset((PyObject
*)self
, Py_None
, &offset
);
3295 assert(n
!= OFFSET_UNKNOWN
);
3296 if (n
== OFFSET_ERROR
)
3299 /* Reduce this to a hash of another object. */
3301 temp
= PyString_FromStringAndSize((char *)self
->data
,
3302 _PyDateTime_TIME_DATASIZE
);
3307 assert(n
== OFFSET_AWARE
);
3308 assert(HASTZINFO(self
));
3309 hour
= divmod(TIME_GET_HOUR(self
) * 60 +
3310 TIME_GET_MINUTE(self
) - offset
,
3313 if (0 <= hour
&& hour
< 24)
3314 temp
= new_time(hour
, minute
,
3315 TIME_GET_SECOND(self
),
3316 TIME_GET_MICROSECOND(self
),
3319 temp
= Py_BuildValue("iiii",
3321 TIME_GET_SECOND(self
),
3322 TIME_GET_MICROSECOND(self
));
3325 self
->hashcode
= PyObject_Hash(temp
);
3329 return self
->hashcode
;
3333 time_replace(PyDateTime_Time
*self
, PyObject
*args
, PyObject
*kw
)
3337 int hh
= TIME_GET_HOUR(self
);
3338 int mm
= TIME_GET_MINUTE(self
);
3339 int ss
= TIME_GET_SECOND(self
);
3340 int us
= TIME_GET_MICROSECOND(self
);
3341 PyObject
*tzinfo
= HASTZINFO(self
) ? self
->tzinfo
: Py_None
;
3343 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "|iiiiO:replace",
3345 &hh
, &mm
, &ss
, &us
, &tzinfo
))
3347 tuple
= Py_BuildValue("iiiiO", hh
, mm
, ss
, us
, tzinfo
);
3350 clone
= time_new(self
->ob_type
, tuple
, NULL
);
3356 time_nonzero(PyDateTime_Time
*self
)
3361 if (TIME_GET_SECOND(self
) || TIME_GET_MICROSECOND(self
)) {
3362 /* Since utcoffset is in whole minutes, nothing can
3363 * alter the conclusion that this is nonzero.
3368 if (HASTZINFO(self
) && self
->tzinfo
!= Py_None
) {
3369 offset
= call_utcoffset(self
->tzinfo
, Py_None
, &none
);
3370 if (offset
== -1 && PyErr_Occurred())
3373 return (TIME_GET_MINUTE(self
) - offset
+ TIME_GET_HOUR(self
)*60) != 0;
3376 /* Pickle support, a simple use of __reduce__. */
3378 /* Let basestate be the non-tzinfo data string.
3379 * If tzinfo is None, this returns (basestate,), else (basestate, tzinfo).
3380 * So it's a tuple in any (non-error) case.
3381 * __getstate__ isn't exposed.
3384 time_getstate(PyDateTime_Time
*self
)
3386 PyObject
*basestate
;
3387 PyObject
*result
= NULL
;
3389 basestate
= PyString_FromStringAndSize((char *)self
->data
,
3390 _PyDateTime_TIME_DATASIZE
);
3391 if (basestate
!= NULL
) {
3392 if (! HASTZINFO(self
) || self
->tzinfo
== Py_None
)
3393 result
= PyTuple_Pack(1, basestate
);
3395 result
= PyTuple_Pack(2, basestate
, self
->tzinfo
);
3396 Py_DECREF(basestate
);
3402 time_reduce(PyDateTime_Time
*self
, PyObject
*arg
)
3404 return Py_BuildValue("(ON)", self
->ob_type
, time_getstate(self
));
3407 static PyMethodDef time_methods
[] = {
3409 {"isoformat", (PyCFunction
)time_isoformat
, METH_KEYWORDS
,
3410 PyDoc_STR("Return string in ISO 8601 format, HH:MM:SS[.mmmmmm]"
3413 {"strftime", (PyCFunction
)time_strftime
, METH_KEYWORDS
,
3414 PyDoc_STR("format -> strftime() style string.")},
3416 {"utcoffset", (PyCFunction
)time_utcoffset
, METH_NOARGS
,
3417 PyDoc_STR("Return self.tzinfo.utcoffset(self).")},
3419 {"tzname", (PyCFunction
)time_tzname
, METH_NOARGS
,
3420 PyDoc_STR("Return self.tzinfo.tzname(self).")},
3422 {"dst", (PyCFunction
)time_dst
, METH_NOARGS
,
3423 PyDoc_STR("Return self.tzinfo.dst(self).")},
3425 {"replace", (PyCFunction
)time_replace
, METH_KEYWORDS
,
3426 PyDoc_STR("Return time with new specified fields.")},
3428 {"__reduce__", (PyCFunction
)time_reduce
, METH_NOARGS
,
3429 PyDoc_STR("__reduce__() -> (cls, state)")},
3434 static char time_doc
[] =
3435 PyDoc_STR("time([hour[, minute[, second[, microsecond[, tzinfo]]]]]) --> a time object\n\
3437 All arguments are optional. tzinfo may be None, or an instance of\n\
3438 a tzinfo subclass. The remaining arguments may be ints or longs.\n");
3440 static PyNumberMethods time_as_number
= {
3442 0, /* nb_subtract */
3443 0, /* nb_multiply */
3445 0, /* nb_remainder */
3448 0, /* nb_negative */
3449 0, /* nb_positive */
3450 0, /* nb_absolute */
3451 (inquiry
)time_nonzero
, /* nb_nonzero */
3454 statichere PyTypeObject PyDateTime_TimeType
= {
3455 PyObject_HEAD_INIT(NULL
)
3457 "datetime.time", /* tp_name */
3458 sizeof(PyDateTime_Time
), /* tp_basicsize */
3459 0, /* tp_itemsize */
3460 (destructor
)time_dealloc
, /* tp_dealloc */
3465 (reprfunc
)time_repr
, /* tp_repr */
3466 &time_as_number
, /* tp_as_number */
3467 0, /* tp_as_sequence */
3468 0, /* tp_as_mapping */
3469 (hashfunc
)time_hash
, /* tp_hash */
3471 (reprfunc
)time_str
, /* tp_str */
3472 PyObject_GenericGetAttr
, /* tp_getattro */
3473 0, /* tp_setattro */
3474 0, /* tp_as_buffer */
3475 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_CHECKTYPES
|
3476 Py_TPFLAGS_BASETYPE
, /* tp_flags */
3477 time_doc
, /* tp_doc */
3478 0, /* tp_traverse */
3480 (richcmpfunc
)time_richcompare
, /* tp_richcompare */
3481 0, /* tp_weaklistoffset */
3483 0, /* tp_iternext */
3484 time_methods
, /* tp_methods */
3486 time_getset
, /* tp_getset */
3489 0, /* tp_descr_get */
3490 0, /* tp_descr_set */
3491 0, /* tp_dictoffset */
3493 time_alloc
, /* tp_alloc */
3494 time_new
, /* tp_new */
3499 * PyDateTime_DateTime implementation.
3502 /* Accessor properties. Properties for day, month, and year are inherited
3507 datetime_hour(PyDateTime_DateTime
*self
, void *unused
)
3509 return PyInt_FromLong(DATE_GET_HOUR(self
));
3513 datetime_minute(PyDateTime_DateTime
*self
, void *unused
)
3515 return PyInt_FromLong(DATE_GET_MINUTE(self
));
3519 datetime_second(PyDateTime_DateTime
*self
, void *unused
)
3521 return PyInt_FromLong(DATE_GET_SECOND(self
));
3525 datetime_microsecond(PyDateTime_DateTime
*self
, void *unused
)
3527 return PyInt_FromLong(DATE_GET_MICROSECOND(self
));
3531 datetime_tzinfo(PyDateTime_DateTime
*self
, void *unused
)
3533 PyObject
*result
= HASTZINFO(self
) ? self
->tzinfo
: Py_None
;
3538 static PyGetSetDef datetime_getset
[] = {
3539 {"hour", (getter
)datetime_hour
},
3540 {"minute", (getter
)datetime_minute
},
3541 {"second", (getter
)datetime_second
},
3542 {"microsecond", (getter
)datetime_microsecond
},
3543 {"tzinfo", (getter
)datetime_tzinfo
},
3551 static const char *datetime_kws
[] = {
3552 "year", "month", "day", "hour", "minute", "second",
3553 "microsecond", "tzinfo", NULL
3557 datetime_new(PyTypeObject
*type
, PyObject
*args
, PyObject
*kw
)
3559 PyObject
*self
= NULL
;
3568 PyObject
*tzinfo
= Py_None
;
3570 /* Check for invocation from pickle with __getstate__ state */
3571 if (PyTuple_GET_SIZE(args
) >= 1 &&
3572 PyTuple_GET_SIZE(args
) <= 2 &&
3573 PyString_Check(state
= PyTuple_GET_ITEM(args
, 0)) &&
3574 PyString_GET_SIZE(state
) == _PyDateTime_DATETIME_DATASIZE
&&
3575 MONTH_IS_SANE(PyString_AS_STRING(state
)[2]))
3577 PyDateTime_DateTime
*me
;
3580 if (PyTuple_GET_SIZE(args
) == 2) {
3581 tzinfo
= PyTuple_GET_ITEM(args
, 1);
3582 if (check_tzinfo_subclass(tzinfo
) < 0) {
3583 PyErr_SetString(PyExc_TypeError
, "bad "
3584 "tzinfo state arg");
3588 aware
= (char)(tzinfo
!= Py_None
);
3589 me
= (PyDateTime_DateTime
*) (type
->tp_alloc(type
, aware
));
3591 char *pdata
= PyString_AS_STRING(state
);
3593 memcpy(me
->data
, pdata
, _PyDateTime_DATETIME_DATASIZE
);
3595 me
->hastzinfo
= aware
;
3598 me
->tzinfo
= tzinfo
;
3601 return (PyObject
*)me
;
3604 if (PyArg_ParseTupleAndKeywords(args
, kw
, "iii|iiiiO", datetime_kws
,
3605 &year
, &month
, &day
, &hour
, &minute
,
3606 &second
, &usecond
, &tzinfo
)) {
3607 if (check_date_args(year
, month
, day
) < 0)
3609 if (check_time_args(hour
, minute
, second
, usecond
) < 0)
3611 if (check_tzinfo_subclass(tzinfo
) < 0)
3613 self
= new_datetime_ex(year
, month
, day
,
3614 hour
, minute
, second
, usecond
,
3620 /* TM_FUNC is the shared type of localtime() and gmtime(). */
3621 typedef struct tm
*(*TM_FUNC
)(const time_t *timer
);
3624 * Build datetime from a time_t and a distinct count of microseconds.
3625 * Pass localtime or gmtime for f, to control the interpretation of timet.
3628 datetime_from_timet_and_us(PyObject
*cls
, TM_FUNC f
, time_t timet
, int us
,
3632 PyObject
*result
= NULL
;
3636 /* The platform localtime/gmtime may insert leap seconds,
3637 * indicated by tm->tm_sec > 59. We don't care about them,
3638 * except to the extent that passing them on to the datetime
3639 * constructor would raise ValueError for a reason that
3640 * made no sense to the user.
3642 if (tm
->tm_sec
> 59)
3644 result
= PyObject_CallFunction(cls
, "iiiiiiiO",
3655 PyErr_SetString(PyExc_ValueError
,
3656 "timestamp out of range for "
3657 "platform localtime()/gmtime() function");
3662 * Build datetime from a Python timestamp. Pass localtime or gmtime for f,
3663 * to control the interpretation of the timestamp. Since a double doesn't
3664 * have enough bits to cover a datetime's full range of precision, it's
3665 * better to call datetime_from_timet_and_us provided you have a way
3666 * to get that much precision (e.g., C time() isn't good enough).
3669 datetime_from_timestamp(PyObject
*cls
, TM_FUNC f
, double timestamp
,
3676 timet
= _PyTime_DoubleToTimet(timestamp
);
3677 if (timet
== (time_t)-1 && PyErr_Occurred())
3679 fraction
= timestamp
- (double)timet
;
3680 us
= (int)round_to_long(fraction
* 1e6
);
3681 return datetime_from_timet_and_us(cls
, f
, timet
, us
, tzinfo
);
3685 * Build most accurate possible datetime for current time. Pass localtime or
3686 * gmtime for f as appropriate.
3689 datetime_best_possible(PyObject
*cls
, TM_FUNC f
, PyObject
*tzinfo
)
3691 #ifdef HAVE_GETTIMEOFDAY
3694 #ifdef GETTIMEOFDAY_NO_TZ
3697 gettimeofday(&t
, (struct timezone
*)NULL
);
3699 return datetime_from_timet_and_us(cls
, f
, t
.tv_sec
, (int)t
.tv_usec
,
3702 #else /* ! HAVE_GETTIMEOFDAY */
3703 /* No flavor of gettimeofday exists on this platform. Python's
3704 * time.time() does a lot of other platform tricks to get the
3705 * best time it can on the platform, and we're not going to do
3706 * better than that (if we could, the better code would belong
3707 * in time.time()!) We're limited by the precision of a double,
3716 dtime
= PyFloat_AsDouble(time
);
3718 if (dtime
== -1.0 && PyErr_Occurred())
3720 return datetime_from_timestamp(cls
, f
, dtime
, tzinfo
);
3721 #endif /* ! HAVE_GETTIMEOFDAY */
3724 /* Return best possible local time -- this isn't constrained by the
3725 * precision of a timestamp.
3728 datetime_now(PyObject
*cls
, PyObject
*args
, PyObject
*kw
)
3731 PyObject
*tzinfo
= Py_None
;
3732 static const char *keywords
[] = {"tz", NULL
};
3734 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "|O:now", keywords
,
3737 if (check_tzinfo_subclass(tzinfo
) < 0)
3740 self
= datetime_best_possible(cls
,
3741 tzinfo
== Py_None
? localtime
: gmtime
,
3743 if (self
!= NULL
&& tzinfo
!= Py_None
) {
3744 /* Convert UTC to tzinfo's zone. */
3745 PyObject
*temp
= self
;
3746 self
= PyObject_CallMethod(tzinfo
, "fromutc", "O", self
);
3752 /* Return best possible UTC time -- this isn't constrained by the
3753 * precision of a timestamp.
3756 datetime_utcnow(PyObject
*cls
, PyObject
*dummy
)
3758 return datetime_best_possible(cls
, gmtime
, Py_None
);
3761 /* Return new local datetime from timestamp (Python timestamp -- a double). */
3763 datetime_fromtimestamp(PyObject
*cls
, PyObject
*args
, PyObject
*kw
)
3767 PyObject
*tzinfo
= Py_None
;
3768 static const char *keywords
[] = {"timestamp", "tz", NULL
};
3770 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "d|O:fromtimestamp",
3771 keywords
, ×tamp
, &tzinfo
))
3773 if (check_tzinfo_subclass(tzinfo
) < 0)
3776 self
= datetime_from_timestamp(cls
,
3777 tzinfo
== Py_None
? localtime
: gmtime
,
3780 if (self
!= NULL
&& tzinfo
!= Py_None
) {
3781 /* Convert UTC to tzinfo's zone. */
3782 PyObject
*temp
= self
;
3783 self
= PyObject_CallMethod(tzinfo
, "fromutc", "O", self
);
3789 /* Return new UTC datetime from timestamp (Python timestamp -- a double). */
3791 datetime_utcfromtimestamp(PyObject
*cls
, PyObject
*args
)
3794 PyObject
*result
= NULL
;
3796 if (PyArg_ParseTuple(args
, "d:utcfromtimestamp", ×tamp
))
3797 result
= datetime_from_timestamp(cls
, gmtime
, timestamp
,
3802 /* Return new datetime from time.strptime(). */
3804 datetime_strptime(PyObject
*cls
, PyObject
*args
)
3806 PyObject
*result
= NULL
, *obj
, *module
;
3807 const char *string
, *format
;
3809 if (!PyArg_ParseTuple(args
, "ss:strptime", &string
, &format
))
3812 if ((module
= PyImport_ImportModule("time")) == NULL
)
3814 obj
= PyObject_CallMethod(module
, "strptime", "ss", string
, format
);
3818 int i
, good_timetuple
= 1;
3820 if (PySequence_Check(obj
) && PySequence_Size(obj
) >= 6)
3821 for (i
=0; i
< 6; i
++) {
3822 PyObject
*p
= PySequence_GetItem(obj
, i
);
3824 ia
[i
] = PyInt_AsLong(p
);
3832 result
= PyObject_CallFunction(cls
, "iiiiii",
3833 ia
[0], ia
[1], ia
[2], ia
[3], ia
[4], ia
[5]);
3835 PyErr_SetString(PyExc_ValueError
,
3836 "unexpected value from time.strptime");
3842 /* Return new datetime from date/datetime and time arguments. */
3844 datetime_combine(PyObject
*cls
, PyObject
*args
, PyObject
*kw
)
3846 static const char *keywords
[] = {"date", "time", NULL
};
3849 PyObject
*result
= NULL
;
3851 if (PyArg_ParseTupleAndKeywords(args
, kw
, "O!O!:combine", keywords
,
3852 &PyDateTime_DateType
, &date
,
3853 &PyDateTime_TimeType
, &time
)) {
3854 PyObject
*tzinfo
= Py_None
;
3856 if (HASTZINFO(time
))
3857 tzinfo
= ((PyDateTime_Time
*)time
)->tzinfo
;
3858 result
= PyObject_CallFunction(cls
, "iiiiiiiO",
3862 TIME_GET_HOUR(time
),
3863 TIME_GET_MINUTE(time
),
3864 TIME_GET_SECOND(time
),
3865 TIME_GET_MICROSECOND(time
),
3876 datetime_dealloc(PyDateTime_DateTime
*self
)
3878 if (HASTZINFO(self
)) {
3879 Py_XDECREF(self
->tzinfo
);
3881 self
->ob_type
->tp_free((PyObject
*)self
);
3885 * Indirect access to tzinfo methods.
3888 /* These are all METH_NOARGS, so don't need to check the arglist. */
3890 datetime_utcoffset(PyDateTime_DateTime
*self
, PyObject
*unused
) {
3891 return offset_as_timedelta(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3892 "utcoffset", (PyObject
*)self
);
3896 datetime_dst(PyDateTime_DateTime
*self
, PyObject
*unused
) {
3897 return offset_as_timedelta(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3898 "dst", (PyObject
*)self
);
3902 datetime_tzname(PyDateTime_DateTime
*self
, PyObject
*unused
) {
3903 return call_tzname(HASTZINFO(self
) ? self
->tzinfo
: Py_None
,
3908 * datetime arithmetic.
3911 /* factor must be 1 (to add) or -1 (to subtract). The result inherits
3912 * the tzinfo state of date.
3915 add_datetime_timedelta(PyDateTime_DateTime
*date
, PyDateTime_Delta
*delta
,
3918 /* Note that the C-level additions can't overflow, because of
3919 * invariant bounds on the member values.
3921 int year
= GET_YEAR(date
);
3922 int month
= GET_MONTH(date
);
3923 int day
= GET_DAY(date
) + GET_TD_DAYS(delta
) * factor
;
3924 int hour
= DATE_GET_HOUR(date
);
3925 int minute
= DATE_GET_MINUTE(date
);
3926 int second
= DATE_GET_SECOND(date
) + GET_TD_SECONDS(delta
) * factor
;
3927 int microsecond
= DATE_GET_MICROSECOND(date
) +
3928 GET_TD_MICROSECONDS(delta
) * factor
;
3930 assert(factor
== 1 || factor
== -1);
3931 if (normalize_datetime(&year
, &month
, &day
,
3932 &hour
, &minute
, &second
, µsecond
) < 0)
3935 return new_datetime(year
, month
, day
,
3936 hour
, minute
, second
, microsecond
,
3937 HASTZINFO(date
) ? date
->tzinfo
: Py_None
);
3941 datetime_add(PyObject
*left
, PyObject
*right
)
3943 if (PyDateTime_Check(left
)) {
3944 /* datetime + ??? */
3945 if (PyDelta_Check(right
))
3946 /* datetime + delta */
3947 return add_datetime_timedelta(
3948 (PyDateTime_DateTime
*)left
,
3949 (PyDateTime_Delta
*)right
,
3952 else if (PyDelta_Check(left
)) {
3953 /* delta + datetime */
3954 return add_datetime_timedelta((PyDateTime_DateTime
*) right
,
3955 (PyDateTime_Delta
*) left
,
3958 Py_INCREF(Py_NotImplemented
);
3959 return Py_NotImplemented
;
3963 datetime_subtract(PyObject
*left
, PyObject
*right
)
3965 PyObject
*result
= Py_NotImplemented
;
3967 if (PyDateTime_Check(left
)) {
3968 /* datetime - ??? */
3969 if (PyDateTime_Check(right
)) {
3970 /* datetime - datetime */
3972 int offset1
, offset2
;
3973 int delta_d
, delta_s
, delta_us
;
3975 if (classify_two_utcoffsets(left
, &offset1
, &n1
, left
,
3976 right
, &offset2
, &n2
,
3979 assert(n1
!= OFFSET_UNKNOWN
&& n2
!= OFFSET_UNKNOWN
);
3981 PyErr_SetString(PyExc_TypeError
,
3982 "can't subtract offset-naive and "
3983 "offset-aware datetimes");
3986 delta_d
= ymd_to_ord(GET_YEAR(left
),
3989 ymd_to_ord(GET_YEAR(right
),
3992 /* These can't overflow, since the values are
3993 * normalized. At most this gives the number of
3994 * seconds in one day.
3996 delta_s
= (DATE_GET_HOUR(left
) -
3997 DATE_GET_HOUR(right
)) * 3600 +
3998 (DATE_GET_MINUTE(left
) -
3999 DATE_GET_MINUTE(right
)) * 60 +
4000 (DATE_GET_SECOND(left
) -
4001 DATE_GET_SECOND(right
));
4002 delta_us
= DATE_GET_MICROSECOND(left
) -
4003 DATE_GET_MICROSECOND(right
);
4004 /* (left - offset1) - (right - offset2) =
4005 * (left - right) + (offset2 - offset1)
4007 delta_s
+= (offset2
- offset1
) * 60;
4008 result
= new_delta(delta_d
, delta_s
, delta_us
, 1);
4010 else if (PyDelta_Check(right
)) {
4011 /* datetime - delta */
4012 result
= add_datetime_timedelta(
4013 (PyDateTime_DateTime
*)left
,
4014 (PyDateTime_Delta
*)right
,
4019 if (result
== Py_NotImplemented
)
4024 /* Various ways to turn a datetime into a string. */
4027 datetime_repr(PyDateTime_DateTime
*self
)
4030 const char *typename
= self
->ob_type
->tp_name
;
4033 if (DATE_GET_MICROSECOND(self
)) {
4034 PyOS_snprintf(buffer
, sizeof(buffer
),
4035 "%s(%d, %d, %d, %d, %d, %d, %d)",
4037 GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
),
4038 DATE_GET_HOUR(self
), DATE_GET_MINUTE(self
),
4039 DATE_GET_SECOND(self
),
4040 DATE_GET_MICROSECOND(self
));
4042 else if (DATE_GET_SECOND(self
)) {
4043 PyOS_snprintf(buffer
, sizeof(buffer
),
4044 "%s(%d, %d, %d, %d, %d, %d)",
4046 GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
),
4047 DATE_GET_HOUR(self
), DATE_GET_MINUTE(self
),
4048 DATE_GET_SECOND(self
));
4051 PyOS_snprintf(buffer
, sizeof(buffer
),
4052 "%s(%d, %d, %d, %d, %d)",
4054 GET_YEAR(self
), GET_MONTH(self
), GET_DAY(self
),
4055 DATE_GET_HOUR(self
), DATE_GET_MINUTE(self
));
4057 baserepr
= PyString_FromString(buffer
);
4058 if (baserepr
== NULL
|| ! HASTZINFO(self
))
4060 return append_keyword_tzinfo(baserepr
, self
->tzinfo
);
4064 datetime_str(PyDateTime_DateTime
*self
)
4066 return PyObject_CallMethod((PyObject
*)self
, "isoformat", "(s)", " ");
4070 datetime_isoformat(PyDateTime_DateTime
*self
, PyObject
*args
, PyObject
*kw
)
4073 static const char *keywords
[] = {"sep", NULL
};
4078 if (!PyArg_ParseTupleAndKeywords(args
, kw
, "|c:isoformat", keywords
,
4081 cp
= isoformat_date((PyDateTime_Date
*)self
, buffer
, sizeof(buffer
));
4084 isoformat_time(self
, cp
, sizeof(buffer
) - (cp
- buffer
));
4085 result
= PyString_FromString(buffer
);
4086 if (result
== NULL
|| ! HASTZINFO(self
))
4089 /* We need to append the UTC offset. */
4090 if (format_utcoffset(buffer
, sizeof(buffer
), ":", self
->tzinfo
,
4091 (PyObject
*)self
) < 0) {
4095 PyString_ConcatAndDel(&result
, PyString_FromString(buffer
));
4100 datetime_ctime(PyDateTime_DateTime
*self
)
4102 return format_ctime((PyDateTime_Date
*)self
,
4103 DATE_GET_HOUR(self
),
4104 DATE_GET_MINUTE(self
),
4105 DATE_GET_SECOND(self
));
4108 /* Miscellaneous methods. */
4110 /* This is more natural as a tp_compare, but doesn't work then: for whatever
4111 * reason, Python's try_3way_compare ignores tp_compare unless
4112 * PyInstance_Check returns true, but these aren't old-style classes.
4115 datetime_richcompare(PyDateTime_DateTime
*self
, PyObject
*other
, int op
)
4119 int offset1
, offset2
;
4121 if (! PyDateTime_Check(other
)) {
4122 /* If other has a "timetuple" attr, that's an advertised
4123 * hook for other classes to ask to get comparison control.
4124 * However, date instances have a timetuple attr, and we
4125 * don't want to allow that comparison. Because datetime
4126 * is a subclass of date, when mixing date and datetime
4127 * in a comparison, Python gives datetime the first shot
4128 * (it's the more specific subtype). So we can stop that
4129 * combination here reliably.
4131 if (PyObject_HasAttrString(other
, "timetuple") &&
4132 ! PyDate_Check(other
)) {
4133 /* A hook for other kinds of datetime objects. */
4134 Py_INCREF(Py_NotImplemented
);
4135 return Py_NotImplemented
;
4137 if (op
== Py_EQ
|| op
== Py_NE
) {
4138 PyObject
*result
= op
== Py_EQ
? Py_False
: Py_True
;
4142 /* Stop this from falling back to address comparison. */
4143 return cmperror((PyObject
*)self
, other
);
4146 if (classify_two_utcoffsets((PyObject
*)self
, &offset1
, &n1
,
4148 other
, &offset2
, &n2
,
4151 assert(n1
!= OFFSET_UNKNOWN
&& n2
!= OFFSET_UNKNOWN
);
4152 /* If they're both naive, or both aware and have the same offsets,
4153 * we get off cheap. Note that if they're both naive, offset1 ==
4154 * offset2 == 0 at this point.
4156 if (n1
== n2
&& offset1
== offset2
) {
4157 diff
= memcmp(self
->data
, ((PyDateTime_DateTime
*)other
)->data
,
4158 _PyDateTime_DATETIME_DATASIZE
);
4159 return diff_to_bool(diff
, op
);
4162 if (n1
== OFFSET_AWARE
&& n2
== OFFSET_AWARE
) {
4163 PyDateTime_Delta
*delta
;
4165 assert(offset1
!= offset2
); /* else last "if" handled it */
4166 delta
= (PyDateTime_Delta
*)datetime_subtract((PyObject
*)self
,
4170 diff
= GET_TD_DAYS(delta
);
4172 diff
= GET_TD_SECONDS(delta
) |
4173 GET_TD_MICROSECONDS(delta
);
4175 return diff_to_bool(diff
, op
);
4179 PyErr_SetString(PyExc_TypeError
,
4180 "can't compare offset-naive and "
4181 "offset-aware datetimes");
4186 datetime_hash(PyDateTime_DateTime
*self
)
4188 if (self
->hashcode
== -1) {
4193 n
= classify_utcoffset((PyObject
*)self
, (PyObject
*)self
,
4195 assert(n
!= OFFSET_UNKNOWN
);
4196 if (n
== OFFSET_ERROR
)
4199 /* Reduce this to a hash of another object. */
4200 if (n
== OFFSET_NAIVE
)
4201 temp
= PyString_FromStringAndSize(
4203 _PyDateTime_DATETIME_DATASIZE
);
4208 assert(n
== OFFSET_AWARE
);
4209 assert(HASTZINFO(self
));
4210 days
= ymd_to_ord(GET_YEAR(self
),
4213 seconds
= DATE_GET_HOUR(self
) * 3600 +
4214 (DATE_GET_MINUTE(self
) - offset
) * 60 +
4215 DATE_GET_SECOND(self
);
4216 temp
= new_delta(days
,
4218 DATE_GET_MICROSECOND(self
),
4222 self
->hashcode
= PyObject_Hash(temp
);
4226 return self
->hashcode
;
4230 datetime_replace(PyDateTime_DateTime
*self
, PyObject
*args
, PyObject
*kw
)
4234 int y
= GET_YEAR(self
);
4235 int m
= GET_MONTH(self
);
4236 int d
= GET_DAY(self
);
4237 int hh
= DATE_GET_HOUR(self
);
4238 int mm
= DATE_GET_MINUTE(self
);
4239 int ss
= DATE_GET_SECOND(self
);
4240 int us
= DATE_GET_MICROSECOND(self
);
4241 PyObject
*tzinfo
= HASTZINFO(self
) ? self
->tzinfo
: Py_None
;
4243 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "|iiiiiiiO:replace",
4245 &y
, &m
, &d
, &hh
, &mm
, &ss
, &us
,
4248 tuple
= Py_BuildValue("iiiiiiiO", y
, m
, d
, hh
, mm
, ss
, us
, tzinfo
);
4251 clone
= datetime_new(self
->ob_type
, tuple
, NULL
);
4257 datetime_astimezone(PyDateTime_DateTime
*self
, PyObject
*args
, PyObject
*kw
)
4259 int y
, m
, d
, hh
, mm
, ss
, us
;
4264 static const char *keywords
[] = {"tz", NULL
};
4266 if (! PyArg_ParseTupleAndKeywords(args
, kw
, "O!:astimezone", keywords
,
4267 &PyDateTime_TZInfoType
, &tzinfo
))
4270 if (!HASTZINFO(self
) || self
->tzinfo
== Py_None
)
4273 /* Conversion to self's own time zone is a NOP. */
4274 if (self
->tzinfo
== tzinfo
) {
4276 return (PyObject
*)self
;
4279 /* Convert self to UTC. */
4280 offset
= call_utcoffset(self
->tzinfo
, (PyObject
*)self
, &none
);
4281 if (offset
== -1 && PyErr_Occurred())
4287 m
= GET_MONTH(self
);
4289 hh
= DATE_GET_HOUR(self
);
4290 mm
= DATE_GET_MINUTE(self
);
4291 ss
= DATE_GET_SECOND(self
);
4292 us
= DATE_GET_MICROSECOND(self
);
4295 if ((mm
< 0 || mm
>= 60) &&
4296 normalize_datetime(&y
, &m
, &d
, &hh
, &mm
, &ss
, &us
) < 0)
4299 /* Attach new tzinfo and let fromutc() do the rest. */
4300 result
= new_datetime(y
, m
, d
, hh
, mm
, ss
, us
, tzinfo
);
4301 if (result
!= NULL
) {
4302 PyObject
*temp
= result
;
4304 result
= PyObject_CallMethod(tzinfo
, "fromutc", "O", temp
);
4310 PyErr_SetString(PyExc_ValueError
, "astimezone() cannot be applied to "
4311 "a naive datetime");
4316 datetime_timetuple(PyDateTime_DateTime
*self
)
4320 if (HASTZINFO(self
) && self
->tzinfo
!= Py_None
) {
4323 dstflag
= call_dst(self
->tzinfo
, (PyObject
*)self
, &none
);
4324 if (dstflag
== -1 && PyErr_Occurred())
4329 else if (dstflag
!= 0)
4333 return build_struct_time(GET_YEAR(self
),
4336 DATE_GET_HOUR(self
),
4337 DATE_GET_MINUTE(self
),
4338 DATE_GET_SECOND(self
),
4343 datetime_getdate(PyDateTime_DateTime
*self
)
4345 return new_date(GET_YEAR(self
),
4351 datetime_gettime(PyDateTime_DateTime
*self
)
4353 return new_time(DATE_GET_HOUR(self
),
4354 DATE_GET_MINUTE(self
),
4355 DATE_GET_SECOND(self
),
4356 DATE_GET_MICROSECOND(self
),
4361 datetime_gettimetz(PyDateTime_DateTime
*self
)
4363 return new_time(DATE_GET_HOUR(self
),
4364 DATE_GET_MINUTE(self
),
4365 DATE_GET_SECOND(self
),
4366 DATE_GET_MICROSECOND(self
),
4367 HASTZINFO(self
) ? self
->tzinfo
: Py_None
);
4371 datetime_utctimetuple(PyDateTime_DateTime
*self
)
4373 int y
= GET_YEAR(self
);
4374 int m
= GET_MONTH(self
);
4375 int d
= GET_DAY(self
);
4376 int hh
= DATE_GET_HOUR(self
);
4377 int mm
= DATE_GET_MINUTE(self
);
4378 int ss
= DATE_GET_SECOND(self
);
4379 int us
= 0; /* microseconds are ignored in a timetuple */
4382 if (HASTZINFO(self
) && self
->tzinfo
!= Py_None
) {
4385 offset
= call_utcoffset(self
->tzinfo
, (PyObject
*)self
, &none
);
4386 if (offset
== -1 && PyErr_Occurred())
4389 /* Even if offset is 0, don't call timetuple() -- tm_isdst should be
4390 * 0 in a UTC timetuple regardless of what dst() says.
4393 /* Subtract offset minutes & normalize. */
4397 stat
= normalize_datetime(&y
, &m
, &d
, &hh
, &mm
, &ss
, &us
);
4399 /* At the edges, it's possible we overflowed
4400 * beyond MINYEAR or MAXYEAR.
4402 if (PyErr_ExceptionMatches(PyExc_OverflowError
))
4408 return build_struct_time(y
, m
, d
, hh
, mm
, ss
, 0);
4411 /* Pickle support, a simple use of __reduce__. */
4413 /* Let basestate be the non-tzinfo data string.
4414 * If tzinfo is None, this returns (basestate,), else (basestate, tzinfo).
4415 * So it's a tuple in any (non-error) case.
4416 * __getstate__ isn't exposed.
4419 datetime_getstate(PyDateTime_DateTime
*self
)
4421 PyObject
*basestate
;
4422 PyObject
*result
= NULL
;
4424 basestate
= PyString_FromStringAndSize((char *)self
->data
,
4425 _PyDateTime_DATETIME_DATASIZE
);
4426 if (basestate
!= NULL
) {
4427 if (! HASTZINFO(self
) || self
->tzinfo
== Py_None
)
4428 result
= PyTuple_Pack(1, basestate
);
4430 result
= PyTuple_Pack(2, basestate
, self
->tzinfo
);
4431 Py_DECREF(basestate
);
4437 datetime_reduce(PyDateTime_DateTime
*self
, PyObject
*arg
)
4439 return Py_BuildValue("(ON)", self
->ob_type
, datetime_getstate(self
));
4442 static PyMethodDef datetime_methods
[] = {
4444 /* Class methods: */
4446 {"now", (PyCFunction
)datetime_now
,
4447 METH_KEYWORDS
| METH_CLASS
,
4448 PyDoc_STR("[tz] -> new datetime with tz's local day and time.")},
4450 {"utcnow", (PyCFunction
)datetime_utcnow
,
4451 METH_NOARGS
| METH_CLASS
,
4452 PyDoc_STR("Return a new datetime representing UTC day and time.")},
4454 {"fromtimestamp", (PyCFunction
)datetime_fromtimestamp
,
4455 METH_KEYWORDS
| METH_CLASS
,
4456 PyDoc_STR("timestamp[, tz] -> tz's local time from POSIX timestamp.")},
4458 {"utcfromtimestamp", (PyCFunction
)datetime_utcfromtimestamp
,
4459 METH_VARARGS
| METH_CLASS
,
4460 PyDoc_STR("timestamp -> UTC datetime from a POSIX timestamp "
4461 "(like time.time()).")},
4463 {"strptime", (PyCFunction
)datetime_strptime
,
4464 METH_VARARGS
| METH_CLASS
,
4465 PyDoc_STR("string, format -> new datetime parsed from a string "
4466 "(like time.strptime()).")},
4468 {"combine", (PyCFunction
)datetime_combine
,
4469 METH_VARARGS
| METH_KEYWORDS
| METH_CLASS
,
4470 PyDoc_STR("date, time -> datetime with same date and time fields")},
4472 /* Instance methods: */
4474 {"date", (PyCFunction
)datetime_getdate
, METH_NOARGS
,
4475 PyDoc_STR("Return date object with same year, month and day.")},
4477 {"time", (PyCFunction
)datetime_gettime
, METH_NOARGS
,
4478 PyDoc_STR("Return time object with same time but with tzinfo=None.")},
4480 {"timetz", (PyCFunction
)datetime_gettimetz
, METH_NOARGS
,
4481 PyDoc_STR("Return time object with same time and tzinfo.")},
4483 {"ctime", (PyCFunction
)datetime_ctime
, METH_NOARGS
,
4484 PyDoc_STR("Return ctime() style string.")},
4486 {"timetuple", (PyCFunction
)datetime_timetuple
, METH_NOARGS
,
4487 PyDoc_STR("Return time tuple, compatible with time.localtime().")},
4489 {"utctimetuple", (PyCFunction
)datetime_utctimetuple
, METH_NOARGS
,
4490 PyDoc_STR("Return UTC time tuple, compatible with time.localtime().")},
4492 {"isoformat", (PyCFunction
)datetime_isoformat
, METH_KEYWORDS
,
4493 PyDoc_STR("[sep] -> string in ISO 8601 format, "
4494 "YYYY-MM-DDTHH:MM:SS[.mmmmmm][+HH:MM].\n\n"
4495 "sep is used to separate the year from the time, and "
4496 "defaults to 'T'.")},
4498 {"utcoffset", (PyCFunction
)datetime_utcoffset
, METH_NOARGS
,
4499 PyDoc_STR("Return self.tzinfo.utcoffset(self).")},
4501 {"tzname", (PyCFunction
)datetime_tzname
, METH_NOARGS
,
4502 PyDoc_STR("Return self.tzinfo.tzname(self).")},
4504 {"dst", (PyCFunction
)datetime_dst
, METH_NOARGS
,
4505 PyDoc_STR("Return self.tzinfo.dst(self).")},
4507 {"replace", (PyCFunction
)datetime_replace
, METH_KEYWORDS
,
4508 PyDoc_STR("Return datetime with new specified fields.")},
4510 {"astimezone", (PyCFunction
)datetime_astimezone
, METH_KEYWORDS
,
4511 PyDoc_STR("tz -> convert to local time in new timezone tz\n")},
4513 {"__reduce__", (PyCFunction
)datetime_reduce
, METH_NOARGS
,
4514 PyDoc_STR("__reduce__() -> (cls, state)")},
4519 static char datetime_doc
[] =
4520 PyDoc_STR("datetime(year, month, day[, hour[, minute[, second[, microsecond[,tzinfo]]]]])\n\
4522 The year, month and day arguments are required. tzinfo may be None, or an\n\
4523 instance of a tzinfo subclass. The remaining arguments may be ints or longs.\n");
4525 static PyNumberMethods datetime_as_number
= {
4526 datetime_add
, /* nb_add */
4527 datetime_subtract
, /* nb_subtract */
4528 0, /* nb_multiply */
4530 0, /* nb_remainder */
4533 0, /* nb_negative */
4534 0, /* nb_positive */
4535 0, /* nb_absolute */
4539 statichere PyTypeObject PyDateTime_DateTimeType
= {
4540 PyObject_HEAD_INIT(NULL
)
4542 "datetime.datetime", /* tp_name */
4543 sizeof(PyDateTime_DateTime
), /* tp_basicsize */
4544 0, /* tp_itemsize */
4545 (destructor
)datetime_dealloc
, /* tp_dealloc */
4550 (reprfunc
)datetime_repr
, /* tp_repr */
4551 &datetime_as_number
, /* tp_as_number */
4552 0, /* tp_as_sequence */
4553 0, /* tp_as_mapping */
4554 (hashfunc
)datetime_hash
, /* tp_hash */
4556 (reprfunc
)datetime_str
, /* tp_str */
4557 PyObject_GenericGetAttr
, /* tp_getattro */
4558 0, /* tp_setattro */
4559 0, /* tp_as_buffer */
4560 Py_TPFLAGS_DEFAULT
| Py_TPFLAGS_CHECKTYPES
|
4561 Py_TPFLAGS_BASETYPE
, /* tp_flags */
4562 datetime_doc
, /* tp_doc */
4563 0, /* tp_traverse */
4565 (richcmpfunc
)datetime_richcompare
, /* tp_richcompare */
4566 0, /* tp_weaklistoffset */
4568 0, /* tp_iternext */
4569 datetime_methods
, /* tp_methods */
4571 datetime_getset
, /* tp_getset */
4572 &PyDateTime_DateType
, /* tp_base */
4574 0, /* tp_descr_get */
4575 0, /* tp_descr_set */
4576 0, /* tp_dictoffset */
4578 datetime_alloc
, /* tp_alloc */
4579 datetime_new
, /* tp_new */
4583 /* ---------------------------------------------------------------------------
4584 * Module methods and initialization.
4587 static PyMethodDef module_methods
[] = {
4591 /* C API. Clients get at this via PyDateTime_IMPORT, defined in
4594 static PyDateTime_CAPI CAPI
= {
4595 &PyDateTime_DateType
,
4596 &PyDateTime_DateTimeType
,
4597 &PyDateTime_TimeType
,
4598 &PyDateTime_DeltaType
,
4599 &PyDateTime_TZInfoType
,
4604 datetime_fromtimestamp
,
4612 PyObject
*m
; /* a module object */
4613 PyObject
*d
; /* its dict */
4616 m
= Py_InitModule3("datetime", module_methods
,
4617 "Fast implementation of the datetime type.");
4621 if (PyType_Ready(&PyDateTime_DateType
) < 0)
4623 if (PyType_Ready(&PyDateTime_DateTimeType
) < 0)
4625 if (PyType_Ready(&PyDateTime_DeltaType
) < 0)
4627 if (PyType_Ready(&PyDateTime_TimeType
) < 0)
4629 if (PyType_Ready(&PyDateTime_TZInfoType
) < 0)
4632 /* timedelta values */
4633 d
= PyDateTime_DeltaType
.tp_dict
;
4635 x
= new_delta(0, 0, 1, 0);
4636 if (x
== NULL
|| PyDict_SetItemString(d
, "resolution", x
) < 0)
4640 x
= new_delta(-MAX_DELTA_DAYS
, 0, 0, 0);
4641 if (x
== NULL
|| PyDict_SetItemString(d
, "min", x
) < 0)
4645 x
= new_delta(MAX_DELTA_DAYS
, 24*3600-1, 1000000-1, 0);
4646 if (x
== NULL
|| PyDict_SetItemString(d
, "max", x
) < 0)
4651 d
= PyDateTime_DateType
.tp_dict
;
4653 x
= new_date(1, 1, 1);
4654 if (x
== NULL
|| PyDict_SetItemString(d
, "min", x
) < 0)
4658 x
= new_date(MAXYEAR
, 12, 31);
4659 if (x
== NULL
|| PyDict_SetItemString(d
, "max", x
) < 0)
4663 x
= new_delta(1, 0, 0, 0);
4664 if (x
== NULL
|| PyDict_SetItemString(d
, "resolution", x
) < 0)
4669 d
= PyDateTime_TimeType
.tp_dict
;
4671 x
= new_time(0, 0, 0, 0, Py_None
);
4672 if (x
== NULL
|| PyDict_SetItemString(d
, "min", x
) < 0)
4676 x
= new_time(23, 59, 59, 999999, Py_None
);
4677 if (x
== NULL
|| PyDict_SetItemString(d
, "max", x
) < 0)
4681 x
= new_delta(0, 0, 1, 0);
4682 if (x
== NULL
|| PyDict_SetItemString(d
, "resolution", x
) < 0)
4686 /* datetime values */
4687 d
= PyDateTime_DateTimeType
.tp_dict
;
4689 x
= new_datetime(1, 1, 1, 0, 0, 0, 0, Py_None
);
4690 if (x
== NULL
|| PyDict_SetItemString(d
, "min", x
) < 0)
4694 x
= new_datetime(MAXYEAR
, 12, 31, 23, 59, 59, 999999, Py_None
);
4695 if (x
== NULL
|| PyDict_SetItemString(d
, "max", x
) < 0)
4699 x
= new_delta(0, 0, 1, 0);
4700 if (x
== NULL
|| PyDict_SetItemString(d
, "resolution", x
) < 0)
4704 /* module initialization */
4705 PyModule_AddIntConstant(m
, "MINYEAR", MINYEAR
);
4706 PyModule_AddIntConstant(m
, "MAXYEAR", MAXYEAR
);
4708 Py_INCREF(&PyDateTime_DateType
);
4709 PyModule_AddObject(m
, "date", (PyObject
*) &PyDateTime_DateType
);
4711 Py_INCREF(&PyDateTime_DateTimeType
);
4712 PyModule_AddObject(m
, "datetime",
4713 (PyObject
*)&PyDateTime_DateTimeType
);
4715 Py_INCREF(&PyDateTime_TimeType
);
4716 PyModule_AddObject(m
, "time", (PyObject
*) &PyDateTime_TimeType
);
4718 Py_INCREF(&PyDateTime_DeltaType
);
4719 PyModule_AddObject(m
, "timedelta", (PyObject
*) &PyDateTime_DeltaType
);
4721 Py_INCREF(&PyDateTime_TZInfoType
);
4722 PyModule_AddObject(m
, "tzinfo", (PyObject
*) &PyDateTime_TZInfoType
);
4724 x
= PyCObject_FromVoidPtrAndDesc(&CAPI
, (void*) DATETIME_API_MAGIC
,
4728 PyModule_AddObject(m
, "datetime_CAPI", x
);
4730 /* A 4-year cycle has an extra leap day over what we'd get from
4731 * pasting together 4 single years.
4733 assert(DI4Y
== 4 * 365 + 1);
4734 assert(DI4Y
== days_before_year(4+1));
4736 /* Similarly, a 400-year cycle has an extra leap day over what we'd
4737 * get from pasting together 4 100-year cycles.
4739 assert(DI400Y
== 4 * DI100Y
+ 1);
4740 assert(DI400Y
== days_before_year(400+1));
4742 /* OTOH, a 100-year cycle has one fewer leap day than we'd get from
4743 * pasting together 25 4-year cycles.
4745 assert(DI100Y
== 25 * DI4Y
- 1);
4746 assert(DI100Y
== days_before_year(100+1));
4748 us_per_us
= PyInt_FromLong(1);
4749 us_per_ms
= PyInt_FromLong(1000);
4750 us_per_second
= PyInt_FromLong(1000000);
4751 us_per_minute
= PyInt_FromLong(60000000);
4752 seconds_per_day
= PyInt_FromLong(24 * 3600);
4753 if (us_per_us
== NULL
|| us_per_ms
== NULL
|| us_per_second
== NULL
||
4754 us_per_minute
== NULL
|| seconds_per_day
== NULL
)
4757 /* The rest are too big for 32-bit ints, but even
4758 * us_per_week fits in 40 bits, so doubles should be exact.
4760 us_per_hour
= PyLong_FromDouble(3600000000.0);
4761 us_per_day
= PyLong_FromDouble(86400000000.0);
4762 us_per_week
= PyLong_FromDouble(604800000000.0);
4763 if (us_per_hour
== NULL
|| us_per_day
== NULL
|| us_per_week
== NULL
)
4767 /* ---------------------------------------------------------------------------
4768 Some time zone algebra. For a datetime x, let
4769 x.n = x stripped of its timezone -- its naive time.
4770 x.o = x.utcoffset(), and assuming that doesn't raise an exception or
4772 x.d = x.dst(), and assuming that doesn't raise an exception or
4774 x.s = x's standard offset, x.o - x.d
4776 Now some derived rules, where k is a duration (timedelta).
4779 This follows from the definition of x.s.
4781 2. If x and y have the same tzinfo member, x.s = y.s.
4782 This is actually a requirement, an assumption we need to make about
4783 sane tzinfo classes.
4785 3. The naive UTC time corresponding to x is x.n - x.o.
4786 This is again a requirement for a sane tzinfo class.
4789 This follows from #2, and that datimetimetz+timedelta preserves tzinfo.
4791 5. (x+k).n = x.n + k
4792 Again follows from how arithmetic is defined.
4794 Now we can explain tz.fromutc(x). Let's assume it's an interesting case
4795 (meaning that the various tzinfo methods exist, and don't blow up or return
4798 The function wants to return a datetime y with timezone tz, equivalent to x.
4799 x is already in UTC.
4805 The algorithm starts by attaching tz to x.n, and calling that y. So
4806 x.n = y.n at the start. Then it wants to add a duration k to y, so that [1]
4807 becomes true; in effect, we want to solve [2] for k:
4809 (y+k).n - (y+k).o = x.n [2]
4811 By #1, this is the same as
4813 (y+k).n - ((y+k).s + (y+k).d) = x.n [3]
4815 By #5, (y+k).n = y.n + k, which equals x.n + k because x.n=y.n at the start.
4816 Substituting that into [3],
4818 x.n + k - (y+k).s - (y+k).d = x.n; the x.n terms cancel, leaving
4819 k - (y+k).s - (y+k).d = 0; rearranging,
4820 k = (y+k).s - (y+k).d; by #4, (y+k).s == y.s, so
4823 On the RHS, (y+k).d can't be computed directly, but y.s can be, and we
4824 approximate k by ignoring the (y+k).d term at first. Note that k can't be
4825 very large, since all offset-returning methods return a duration of magnitude
4826 less than 24 hours. For that reason, if y is firmly in std time, (y+k).d must
4827 be 0, so ignoring it has no consequence then.
4829 In any case, the new value is
4833 It's helpful to step back at look at [4] from a higher level: it's simply
4834 mapping from UTC to tz's standard time.
4840 we have an equivalent time, and are almost done. The insecurity here is
4841 at the start of daylight time. Picture US Eastern for concreteness. The wall
4842 time jumps from 1:59 to 3:00, and wall hours of the form 2:MM don't make good
4843 sense then. The docs ask that an Eastern tzinfo class consider such a time to
4844 be EDT (because it's "after 2"), which is a redundant spelling of 1:MM EST
4845 on the day DST starts. We want to return the 1:MM EST spelling because that's
4846 the only spelling that makes sense on the local wall clock.
4848 In fact, if [5] holds at this point, we do have the standard-time spelling,
4849 but that takes a bit of proof. We first prove a stronger result. What's the
4850 difference between the LHS and RHS of [5]? Let
4852 diff = x.n - (z.n - z.o) [6]
4857 y.n + y.s = since y.n = x.n
4858 x.n + y.s = since z and y are have the same tzinfo member,
4862 Plugging that back into [6] gives
4865 x.n - ((x.n + z.s) - z.o) = expanding
4866 x.n - x.n - z.s + z.o = cancelling
4872 If [5] is true now, diff = 0, so z.d = 0 too, and we have the standard-time
4873 spelling we wanted in the endcase described above. We're done. Contrarily,
4874 if z.d = 0, then we have a UTC equivalent, and are also done.
4876 If [5] is not true now, diff = z.d != 0, and z.d is the offset we need to
4877 add to z (in effect, z is in tz's standard time, and we need to shift the
4878 local clock into tz's daylight time).
4882 z' = z + z.d = z + diff [7]
4884 and we can again ask whether
4886 z'.n - z'.o = x.n [8]
4888 If so, we're done. If not, the tzinfo class is insane, according to the
4889 assumptions we've made. This also requires a bit of proof. As before, let's
4890 compute the difference between the LHS and RHS of [8] (and skipping some of
4891 the justifications for the kinds of substitutions we've done several times
4894 diff' = x.n - (z'.n - z'.o) = replacing z'.n via [7]
4895 x.n - (z.n + diff - z'.o) = replacing diff via [6]
4896 x.n - (z.n + x.n - (z.n - z.o) - z'.o) =
4897 x.n - z.n - x.n + z.n - z.o + z'.o = cancel x.n
4898 - z.n + z.n - z.o + z'.o = cancel z.n
4899 - z.o + z'.o = #1 twice
4900 -z.s - z.d + z'.s + z'.d = z and z' have same tzinfo
4903 So z' is UTC-equivalent to x iff z'.d = z.d at this point. If they are equal,
4904 we've found the UTC-equivalent so are done. In fact, we stop with [7] and
4905 return z', not bothering to compute z'.d.
4907 How could z.d and z'd differ? z' = z + z.d [7], so merely moving z' by
4908 a dst() offset, and starting *from* a time already in DST (we know z.d != 0),
4909 would have to change the result dst() returns: we start in DST, and moving
4910 a little further into it takes us out of DST.
4912 There isn't a sane case where this can happen. The closest it gets is at
4913 the end of DST, where there's an hour in UTC with no spelling in a hybrid
4914 tzinfo class. In US Eastern, that's 5:MM UTC = 0:MM EST = 1:MM EDT. During
4915 that hour, on an Eastern clock 1:MM is taken as being in standard time (6:MM
4916 UTC) because the docs insist on that, but 0:MM is taken as being in daylight
4917 time (4:MM UTC). There is no local time mapping to 5:MM UTC. The local
4918 clock jumps from 1:59 back to 1:00 again, and repeats the 1:MM hour in
4919 standard time. Since that's what the local clock *does*, we want to map both
4920 UTC hours 5:MM and 6:MM to 1:MM Eastern. The result is ambiguous
4921 in local time, but so it goes -- it's the way the local clock works.
4923 When x = 5:MM UTC is the input to this algorithm, x.o=0, y.o=-5 and y.d=0,
4924 so z=0:MM. z.d=60 (minutes) then, so [5] doesn't hold and we keep going.
4925 z' = z + z.d = 1:MM then, and z'.d=0, and z'.d - z.d = -60 != 0 so [8]
4926 (correctly) concludes that z' is not UTC-equivalent to x.
4928 Because we know z.d said z was in daylight time (else [5] would have held and
4929 we would have stopped then), and we know z.d != z'.d (else [8] would have held
4930 and we would have stopped then), and there are only 2 possible values dst() can
4931 return in Eastern, it follows that z'.d must be 0 (which it is in the example,
4932 but the reasoning doesn't depend on the example -- it depends on there being
4933 two possible dst() outcomes, one zero and the other non-zero). Therefore
4934 z' must be in standard time, and is the spelling we want in this case.
4936 Note again that z' is not UTC-equivalent as far as the hybrid tzinfo class is
4937 concerned (because it takes z' as being in standard time rather than the
4938 daylight time we intend here), but returning it gives the real-life "local
4939 clock repeats an hour" behavior when mapping the "unspellable" UTC hour into
4942 When the input is 6:MM, z=1:MM and z.d=0, and we stop at once, again with
4943 the 1:MM standard time spelling we want.
4945 So how can this break? One of the assumptions must be violated. Two
4948 1) [2] effectively says that y.s is invariant across all y belong to a given
4949 time zone. This isn't true if, for political reasons or continental drift,
4950 a region decides to change its base offset from UTC.
4952 2) There may be versions of "double daylight" time where the tail end of
4953 the analysis gives up a step too early. I haven't thought about that
4956 In any case, it's clear that the default fromutc() is strong enough to handle
4957 "almost all" time zones: so long as the standard offset is invariant, it
4958 doesn't matter if daylight time transition points change from year to year, or
4959 if daylight time is skipped in some years; it doesn't matter how large or
4960 small dst() may get within its bounds; and it doesn't even matter if some
4961 perverse time zone returns a negative dst()). So a breaking case must be
4962 pretty bizarre, and a tzinfo subclass can override fromutc() if it is.
4963 --------------------------------------------------------------------------- */