Mercurial > repos > rliterman > csp2

comparison CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/DateTime-5.5.dist-info/METADATA @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
comparison
equal deleted inserted replaced
67:0e9998148a16 69:33d812a61356
1 Metadata-Version: 2.1
2 Name: DateTime
3 Version: 5.5
4 Summary: This package provides a DateTime data type, as known from Zope. Unless you need to communicate with Zope APIs, you're probably better off using Python's built-in datetime module.
5 Home-page: https://github.com/zopefoundation/DateTime
6 Author: Zope Foundation and Contributors
7 Author-email: zope-dev@zope.org
8 License: ZPL 2.1
9 Classifier: Development Status :: 6 - Mature
10 Classifier: Environment :: Web Environment
11 Classifier: Framework :: Zope :: 4
12 Classifier: License :: OSI Approved :: Zope Public License
13 Classifier: Operating System :: OS Independent
14 Classifier: Programming Language :: Python
15 Classifier: Programming Language :: Python :: 3
16 Classifier: Programming Language :: Python :: 3.7
17 Classifier: Programming Language :: Python :: 3.8
18 Classifier: Programming Language :: Python :: 3.9
19 Classifier: Programming Language :: Python :: 3.10
20 Classifier: Programming Language :: Python :: 3.11
21 Classifier: Programming Language :: Python :: 3.12
22 Classifier: Programming Language :: Python :: Implementation :: CPython
23 Classifier: Programming Language :: Python :: Implementation :: PyPy
24 Requires-Python: >=3.7
25 License-File: LICENSE.txt
26 Requires-Dist: zope.interface
27 Requires-Dist: pytz
28
29 .. image:: https://github.com/zopefoundation/DateTime/workflows/tests/badge.svg
30 :target: https://github.com/zopefoundation/DateTime/actions?query=workflow%3Atests
31 :alt: CI status
32
33 .. image:: https://img.shields.io/pypi/v/DateTime.svg
34 :target: https://pypi.org/project/DateTime/
35 :alt: Current version on PyPI
36
37 .. image:: https://img.shields.io/pypi/pyversions/DateTime.svg
38 :target: https://pypi.org/project/DateTime/
39 :alt: Supported Python versions
40
41
42 DateTime
43 ========
44
45 This package provides a DateTime data type, as known from Zope.
46
47 Unless you need to communicate with Zope APIs, you're probably better
48 off using Python's built-in datetime module.
49
50 For further documentation, please have a look at `src/DateTime/DateTime.txt`.
51
52
53 .. contents::
54
55 The DateTime package
56 ====================
57
58 Encapsulation of date/time values.
59
60
61 Function Timezones()
62 --------------------
63
64 Returns the list of recognized timezone names:
65
66 >>> from DateTime import Timezones
67 >>> zones = set(Timezones())
68
69 Almost all of the standard pytz timezones are included, with the exception
70 of some commonly-used but ambiguous abbreviations, where historical Zope
71 usage conflicts with the name used by pytz:
72
73 >>> import pytz
74 >>> [x for x in pytz.all_timezones if x not in zones]
75 ['CET', 'EET', 'EST', 'MET', 'MST', 'WET']
76
77 Class DateTime
78 --------------
79
80 DateTime objects represent instants in time and provide interfaces for
81 controlling its representation without affecting the absolute value of
82 the object.
83
84 DateTime objects may be created from a wide variety of string or
85 numeric data, or may be computed from other DateTime objects.
86 DateTimes support the ability to convert their representations to many
87 major timezones, as well as the ability to create a DateTime object
88 in the context of a given timezone.
89
90 DateTime objects provide partial numerical behavior:
91
92 * Two date-time objects can be subtracted to obtain a time, in days
93 between the two.
94
95 * A date-time object and a positive or negative number may be added to
96 obtain a new date-time object that is the given number of days later
97 than the input date-time object.
98
99 * A positive or negative number and a date-time object may be added to
100 obtain a new date-time object that is the given number of days later
101 than the input date-time object.
102
103 * A positive or negative number may be subtracted from a date-time
104 object to obtain a new date-time object that is the given number of
105 days earlier than the input date-time object.
106
107 DateTime objects may be converted to integer, long, or float numbers
108 of days since January 1, 1901, using the standard int, long, and float
109 functions (Compatibility Note: int, long and float return the number
110 of days since 1901 in GMT rather than local machine timezone).
111 DateTime objects also provide access to their value in a float format
112 usable with the Python time module, provided that the value of the
113 object falls in the range of the epoch-based time module.
114
115 A DateTime object should be considered immutable; all conversion and numeric
116 operations return a new DateTime object rather than modify the current object.
117
118 A DateTime object always maintains its value as an absolute UTC time,
119 and is represented in the context of some timezone based on the
120 arguments used to create the object. A DateTime object's methods
121 return values based on the timezone context.
122
123 Note that in all cases the local machine timezone is used for
124 representation if no timezone is specified.
125
126 Constructor for DateTime
127 ------------------------
128
129 DateTime() returns a new date-time object. DateTimes may be created
130 with from zero to seven arguments:
131
132 * If the function is called with no arguments, then the current date/
133 time is returned, represented in the timezone of the local machine.
134
135 * If the function is invoked with a single string argument which is a
136 recognized timezone name, an object representing the current time is
137 returned, represented in the specified timezone.
138
139 * If the function is invoked with a single string argument
140 representing a valid date/time, an object representing that date/
141 time will be returned.
142
143 As a general rule, any date-time representation that is recognized
144 and unambiguous to a resident of North America is acceptable. (The
145 reason for this qualification is that in North America, a date like:
146 2/1/1994 is interpreted as February 1, 1994, while in some parts of
147 the world, it is interpreted as January 2, 1994.) A date/ time
148 string consists of two components, a date component and an optional
149 time component, separated by one or more spaces. If the time
150 component is omitted, 12:00am is assumed.
151
152 Any recognized timezone name specified as the final element of the
153 date/time string will be used for computing the date/time value.
154 (If you create a DateTime with the string,
155 "Mar 9, 1997 1:45pm US/Pacific", the value will essentially be the
156 same as if you had captured time.time() at the specified date and
157 time on a machine in that timezone). If no timezone is passed, then
158 the timezone configured on the local machine will be used, **except**
159 that if the date format matches ISO 8601 ('YYYY-MM-DD'), the instance
160 will use UTC / GMT+0 as the timezone.
161
162 o Returns current date/time, represented in US/Eastern:
163
164 >>> from DateTime import DateTime
165 >>> e = DateTime('US/Eastern')
166 >>> e.timezone()
167 'US/Eastern'
168
169 o Returns specified time, represented in local machine zone:
170
171 >>> x = DateTime('1997/3/9 1:45pm')
172 >>> x.parts() # doctest: +ELLIPSIS
173 (1997, 3, 9, 13, 45, ...)
174
175 o Specified time in local machine zone, verbose format:
176
177 >>> y = DateTime('Mar 9, 1997 13:45:00')
178 >>> y.parts() # doctest: +ELLIPSIS
179 (1997, 3, 9, 13, 45, ...)
180 >>> y == x
181 True
182
183 o Specified time in UTC via ISO 8601 rule:
184
185 >>> z = DateTime('2014-03-24')
186 >>> z.parts() # doctest: +ELLIPSIS
187 (2014, 3, 24, 0, 0, ...)
188 >>> z.timezone()
189 'GMT+0'
190
191 The date component consists of year, month, and day values. The
192 year value must be a one-, two-, or four-digit integer. If a one-
193 or two-digit year is used, the year is assumed to be in the
194 twentieth century. The month may an integer, from 1 to 12, a month
195 name, or a month abbreviation, where a period may optionally follow
196 the abbreviation. The day must be an integer from 1 to the number of
197 days in the month. The year, month, and day values may be separated
198 by periods, hyphens, forward slashes, or spaces. Extra spaces are
199 permitted around the delimiters. Year, month, and day values may be
200 given in any order as long as it is possible to distinguish the
201 components. If all three components are numbers that are less than
202 13, then a month-day-year ordering is assumed.
203
204 The time component consists of hour, minute, and second values
205 separated by colons. The hour value must be an integer between 0
206 and 23 inclusively. The minute value must be an integer between 0
207 and 59 inclusively. The second value may be an integer value
208 between 0 and 59.999 inclusively. The second value or both the
209 minute and second values may be omitted. The time may be followed
210 by am or pm in upper or lower case, in which case a 12-hour clock is
211 assumed.
212
213 * If the DateTime function is invoked with a single numeric argument,
214 the number is assumed to be either a floating point value such as
215 that returned by time.time(), or a number of days after January 1,
216 1901 00:00:00 UTC.
217
218 A DateTime object is returned that represents either the GMT value
219 of the time.time() float represented in the local machine's
220 timezone, or that number of days after January 1, 1901. Note that
221 the number of days after 1901 need to be expressed from the
222 viewpoint of the local machine's timezone. A negative argument will
223 yield a date-time value before 1901.
224
225 * If the function is invoked with two numeric arguments, then the
226 first is taken to be an integer year and the second argument is
227 taken to be an offset in days from the beginning of the year, in the
228 context of the local machine timezone. The date-time value returned
229 is the given offset number of days from the beginning of the given
230 year, represented in the timezone of the local machine. The offset
231 may be positive or negative. Two-digit years are assumed to be in
232 the twentieth century.
233
234 * If the function is invoked with two arguments, the first a float
235 representing a number of seconds past the epoch in GMT (such as
236 those returned by time.time()) and the second a string naming a
237 recognized timezone, a DateTime with a value of that GMT time will
238 be returned, represented in the given timezone.
239
240 >>> import time
241 >>> t = time.time()
242
243 Time t represented as US/Eastern:
244
245 >>> now_east = DateTime(t, 'US/Eastern')
246
247 Time t represented as US/Pacific:
248
249 >>> now_west = DateTime(t, 'US/Pacific')
250
251 Only their representations are different:
252
253 >>> now_east.equalTo(now_west)
254 True
255
256 * If the function is invoked with three or more numeric arguments,
257 then the first is taken to be an integer year, the second is taken
258 to be an integer month, and the third is taken to be an integer day.
259 If the combination of values is not valid, then a DateTimeError is
260 raised. One- or two-digit years up to 69 are assumed to be in the
261 21st century, whereas values 70-99 are assumed to be 20th century.
262 The fourth, fifth, and sixth arguments are floating point, positive
263 or negative offsets in units of hours, minutes, and days, and
264 default to zero if not given. An optional string may be given as
265 the final argument to indicate timezone (the effect of this is as if
266 you had taken the value of time.time() at that time on a machine in
267 the specified timezone).
268
269 If a string argument passed to the DateTime constructor cannot be
270 parsed, it will raise SyntaxError. Invalid date, time, or
271 timezone components will raise a DateTimeError.
272
273 The module function Timezones() will return a list of the timezones
274 recognized by the DateTime module. Recognition of timezone names is
275 case-insensitive.
276
277 Instance Methods for DateTime (IDateTime interface)
278 ---------------------------------------------------
279
280 Conversion and comparison methods
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282
283 * ``timeTime()`` returns the date/time as a floating-point number in
284 UTC, in the format used by the Python time module. Note that it is
285 possible to create date /time values with DateTime that have no
286 meaningful value to the time module, and in such cases a
287 DateTimeError is raised. A DateTime object's value must generally
288 be between Jan 1, 1970 (or your local machine epoch) and Jan 2038 to
289 produce a valid time.time() style value.
290
291 >>> dt = DateTime('Mar 9, 1997 13:45:00 US/Eastern')
292 >>> dt.timeTime()
293 857933100.0
294
295 >>> DateTime('2040/01/01 UTC').timeTime()
296 2208988800.0
297
298 >>> DateTime('1900/01/01 UTC').timeTime()
299 -2208988800.0
300
301 * ``toZone(z)`` returns a DateTime with the value as the current
302 object, represented in the indicated timezone:
303
304 >>> dt.toZone('UTC')
305 DateTime('1997/03/09 18:45:00 UTC')
306
307 >>> dt.toZone('UTC').equalTo(dt)
308 True
309
310 * ``isFuture()`` returns true if this object represents a date/time
311 later than the time of the call:
312
313 >>> dt.isFuture()
314 False
315 >>> DateTime('Jan 1 3000').isFuture() # not time-machine safe!
316 True
317
318 * ``isPast()`` returns true if this object represents a date/time
319 earlier than the time of the call:
320
321 >>> dt.isPast()
322 True
323 >>> DateTime('Jan 1 3000').isPast() # not time-machine safe!
324 False
325
326 * ``isCurrentYear()`` returns true if this object represents a
327 date/time that falls within the current year, in the context of this
328 object's timezone representation:
329
330 >>> dt.isCurrentYear()
331 False
332 >>> DateTime().isCurrentYear()
333 True
334
335 * ``isCurrentMonth()`` returns true if this object represents a
336 date/time that falls within the current month, in the context of
337 this object's timezone representation:
338
339 >>> dt.isCurrentMonth()
340 False
341 >>> DateTime().isCurrentMonth()
342 True
343
344 * ``isCurrentDay()`` returns true if this object represents a
345 date/time that falls within the current day, in the context of this
346 object's timezone representation:
347
348 >>> dt.isCurrentDay()
349 False
350 >>> DateTime().isCurrentDay()
351 True
352
353 * ``isCurrentHour()`` returns true if this object represents a
354 date/time that falls within the current hour, in the context of this
355 object's timezone representation:
356
357 >>> dt.isCurrentHour()
358 False
359
360 >>> DateTime().isCurrentHour()
361 True
362
363 * ``isCurrentMinute()`` returns true if this object represents a
364 date/time that falls within the current minute, in the context of
365 this object's timezone representation:
366
367 >>> dt.isCurrentMinute()
368 False
369 >>> DateTime().isCurrentMinute()
370 True
371
372 * ``isLeapYear()`` returns true if the current year (in the context of
373 the object's timezone) is a leap year:
374
375 >>> dt.isLeapYear()
376 False
377 >>> DateTime('Mar 8 2004').isLeapYear()
378 True
379
380 * ``earliestTime()`` returns a new DateTime object that represents the
381 earliest possible time (in whole seconds) that still falls within
382 the current object's day, in the object's timezone context:
383
384 >>> dt.earliestTime()
385 DateTime('1997/03/09 00:00:00 US/Eastern')
386
387 * ``latestTime()`` return a new DateTime object that represents the
388 latest possible time (in whole seconds) that still falls within the
389 current object's day, in the object's timezone context
390
391 >>> dt.latestTime()
392 DateTime('1997/03/09 23:59:59 US/Eastern')
393
394 Component access
395 ~~~~~~~~~~~~~~~~
396
397 * ``parts()`` returns a tuple containing the calendar year, month,
398 day, hour, minute second and timezone of the object
399
400 >>> dt.parts() # doctest: +ELLIPSIS
401 (1997, 3, 9, 13, 45, ... 'US/Eastern')
402
403 * ``timezone()`` returns the timezone in which the object is represented:
404
405 >>> dt.timezone() in Timezones()
406 True
407
408 * ``tzoffset()`` returns the timezone offset for the objects timezone:
409
410 >>> dt.tzoffset()
411 -18000
412
413 * ``year()`` returns the calendar year of the object:
414
415 >>> dt.year()
416 1997
417
418 * ``month()`` returns the month of the object as an integer:
419
420 >>> dt.month()
421 3
422
423 * ``Month()`` returns the full month name:
424
425 >>> dt.Month()
426 'March'
427
428 * ``aMonth()`` returns the abbreviated month name:
429
430 >>> dt.aMonth()
431 'Mar'
432
433 * ``pMonth()`` returns the abbreviated (with period) month name:
434
435 >>> dt.pMonth()
436 'Mar.'
437
438 * ``day()`` returns the integer day:
439
440 >>> dt.day()
441 9
442
443 * ``Day()`` returns the full name of the day of the week:
444
445 >>> dt.Day()
446 'Sunday'
447
448 * ``dayOfYear()`` returns the day of the year, in context of the
449 timezone representation of the object:
450
451 >>> dt.dayOfYear()
452 68
453
454 * ``aDay()`` returns the abbreviated name of the day of the week:
455
456 >>> dt.aDay()
457 'Sun'
458
459 * ``pDay()`` returns the abbreviated (with period) name of the day of
460 the week:
461
462 >>> dt.pDay()
463 'Sun.'
464
465 * ``dow()`` returns the integer day of the week, where Sunday is 0:
466
467 >>> dt.dow()
468 0
469
470 * ``dow_1()`` returns the integer day of the week, where sunday is 1:
471
472 >>> dt.dow_1()
473 1
474
475 * ``h_12()`` returns the 12-hour clock representation of the hour:
476
477 >>> dt.h_12()
478 1
479
480 * ``h_24()`` returns the 24-hour clock representation of the hour:
481
482 >>> dt.h_24()
483 13
484
485 * ``ampm()`` returns the appropriate time modifier (am or pm):
486
487 >>> dt.ampm()
488 'pm'
489
490 * ``hour()`` returns the 24-hour clock representation of the hour:
491
492 >>> dt.hour()
493 13
494
495 * ``minute()`` returns the minute:
496
497 >>> dt.minute()
498 45
499
500 * ``second()`` returns the second:
501
502 >>> dt.second() == 0
503 True
504
505 * ``millis()`` returns the milliseconds since the epoch in GMT.
506
507 >>> dt.millis() == 857933100000
508 True
509
510 strftime()
511 ~~~~~~~~~~
512
513 See ``tests/test_datetime.py``.
514
515 General formats from previous DateTime
516 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
517
518 * ``Date()`` return the date string for the object:
519
520 >>> dt.Date()
521 '1997/03/09'
522
523 * ``Time()`` returns the time string for an object to the nearest
524 second:
525
526 >>> dt.Time()
527 '13:45:00'
528
529 * ``TimeMinutes()`` returns the time string for an object not showing
530 seconds:
531
532 >>> dt.TimeMinutes()
533 '13:45'
534
535 * ``AMPM()`` returns the time string for an object to the nearest second:
536
537 >>> dt.AMPM()
538 '01:45:00 pm'
539
540 * ``AMPMMinutes()`` returns the time string for an object not showing
541 seconds:
542
543 >>> dt.AMPMMinutes()
544 '01:45 pm'
545
546 * ``PreciseTime()`` returns the time string for the object:
547
548 >>> dt.PreciseTime()
549 '13:45:00.000'
550
551 * ``PreciseAMPM()`` returns the time string for the object:
552
553 >>> dt.PreciseAMPM()
554 '01:45:00.000 pm'
555
556 * ``yy()`` returns the calendar year as a 2 digit string
557
558 >>> dt.yy()
559 '97'
560
561 * ``mm()`` returns the month as a 2 digit string
562
563 >>> dt.mm()
564 '03'
565
566 * ``dd()`` returns the day as a 2 digit string:
567
568 >>> dt.dd()
569 '09'
570
571 * ``rfc822()`` returns the date in RFC 822 format:
572
573 >>> dt.rfc822()
574 'Sun, 09 Mar 1997 13:45:00 -0500'
575
576 New formats
577 ~~~~~~~~~~~
578
579 * ``fCommon()`` returns a string representing the object's value in
580 the format: March 9, 1997 1:45 pm:
581
582 >>> dt.fCommon()
583 'March 9, 1997 1:45 pm'
584
585 * ``fCommonZ()`` returns a string representing the object's value in
586 the format: March 9, 1997 1:45 pm US/Eastern:
587
588 >>> dt.fCommonZ()
589 'March 9, 1997 1:45 pm US/Eastern'
590
591 * ``aCommon()`` returns a string representing the object's value in
592 the format: Mar 9, 1997 1:45 pm:
593
594 >>> dt.aCommon()
595 'Mar 9, 1997 1:45 pm'
596
597 * ``aCommonZ()`` return a string representing the object's value in
598 the format: Mar 9, 1997 1:45 pm US/Eastern:
599
600 >>> dt.aCommonZ()
601 'Mar 9, 1997 1:45 pm US/Eastern'
602
603 * ``pCommon()`` returns a string representing the object's value in
604 the format Mar. 9, 1997 1:45 pm:
605
606 >>> dt.pCommon()
607 'Mar. 9, 1997 1:45 pm'
608
609 * ``pCommonZ()`` returns a string representing the object's value in
610 the format: Mar. 9, 1997 1:45 pm US/Eastern:
611
612 >>> dt.pCommonZ()
613 'Mar. 9, 1997 1:45 pm US/Eastern'
614
615 * ``ISO()`` returns a string with the date/time in ISO format. Note:
616 this is not ISO 8601-format! See the ISO8601 and HTML4 methods below
617 for ISO 8601-compliant output. Dates are output as: YYYY-MM-DD HH:MM:SS
618
619 >>> dt.ISO()
620 '1997-03-09 13:45:00'
621
622 * ``ISO8601()`` returns the object in ISO 8601-compatible format
623 containing the date, time with seconds-precision and the time zone
624 identifier - see http://www.w3.org/TR/NOTE-datetime. Dates are
625 output as: YYYY-MM-DDTHH:MM:SSTZD (T is a literal character, TZD is
626 Time Zone Designator, format +HH:MM or -HH:MM).
627
628 The ``HTML4()`` method below offers the same formatting, but
629 converts to UTC before returning the value and sets the TZD"Z"
630
631 >>> dt.ISO8601()
632 '1997-03-09T13:45:00-05:00'
633
634
635 * ``HTML4()`` returns the object in the format used in the HTML4.0
636 specification, one of the standard forms in ISO8601. See
637 http://www.w3.org/TR/NOTE-datetime. Dates are output as:
638 YYYY-MM-DDTHH:MM:SSZ (T, Z are literal characters, the time is in
639 UTC.):
640
641 >>> dt.HTML4()
642 '1997-03-09T18:45:00Z'
643
644 * ``JulianDay()`` returns the Julian day according to
645 http://www.tondering.dk/claus/cal/node3.html#sec-calcjd
646
647 >>> dt.JulianDay()
648 2450517
649
650 * ``week()`` returns the week number according to ISO
651 see http://www.tondering.dk/claus/cal/node6.html#SECTION00670000000000000000
652
653 >>> dt.week()
654 10
655
656 Deprecated API
657 ~~~~~~~~~~~~~~
658
659 * DayOfWeek(): see Day()
660
661 * Day_(): see pDay()
662
663 * Mon(): see aMonth()
664
665 * Mon_(): see pMonth
666
667 General Services Provided by DateTime
668 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
669
670 DateTimes can be repr()'ed; the result will be a string indicating how
671 to make a DateTime object like this:
672
673 >>> repr(dt)
674 "DateTime('1997/03/09 13:45:00 US/Eastern')"
675
676 When we convert them into a string, we get a nicer string that could
677 actually be shown to a user:
678
679 >>> str(dt)
680 '1997/03/09 13:45:00 US/Eastern'
681
682 The hash value of a DateTime is based on the date and time and is
683 equal for different representations of the DateTime:
684
685 >>> hash(dt)
686 3618678
687 >>> hash(dt.toZone('UTC'))
688 3618678
689
690 DateTime objects can be compared to other DateTime objects OR floating
691 point numbers such as the ones which are returned by the Python time
692 module by using the equalTo method. Using this API, True is returned if the
693 object represents a date/time equal to the specified DateTime or time module
694 style time:
695
696 >>> dt.equalTo(dt)
697 True
698 >>> dt.equalTo(dt.toZone('UTC'))
699 True
700 >>> dt.equalTo(dt.timeTime())
701 True
702 >>> dt.equalTo(DateTime())
703 False
704
705 Same goes for inequalities:
706
707 >>> dt.notEqualTo(dt)
708 False
709 >>> dt.notEqualTo(dt.toZone('UTC'))
710 False
711 >>> dt.notEqualTo(dt.timeTime())
712 False
713 >>> dt.notEqualTo(DateTime())
714 True
715
716 Normal equality operations only work with DateTime objects and take the
717 timezone setting into account:
718
719 >>> dt == dt
720 True
721 >>> dt == dt.toZone('UTC')
722 False
723 >>> dt == DateTime()
724 False
725
726 >>> dt != dt
727 False
728 >>> dt != dt.toZone('UTC')
729 True
730 >>> dt != DateTime()
731 True
732
733 But the other comparison operations compare the referenced moment in time and
734 not the representation itself:
735
736 >>> dt > dt
737 False
738 >>> DateTime() > dt
739 True
740 >>> dt > DateTime().timeTime()
741 False
742 >>> DateTime().timeTime() > dt
743 True
744
745 >>> dt.greaterThan(dt)
746 False
747 >>> DateTime().greaterThan(dt)
748 True
749 >>> dt.greaterThan(DateTime().timeTime())
750 False
751
752 >>> dt >= dt
753 True
754 >>> DateTime() >= dt
755 True
756 >>> dt >= DateTime().timeTime()
757 False
758 >>> DateTime().timeTime() >= dt
759 True
760
761 >>> dt.greaterThanEqualTo(dt)
762 True
763 >>> DateTime().greaterThanEqualTo(dt)
764 True
765 >>> dt.greaterThanEqualTo(DateTime().timeTime())
766 False
767
768 >>> dt < dt
769 False
770 >>> DateTime() < dt
771 False
772 >>> dt < DateTime().timeTime()
773 True
774 >>> DateTime().timeTime() < dt
775 False
776
777 >>> dt.lessThan(dt)
778 False
779 >>> DateTime().lessThan(dt)
780 False
781 >>> dt.lessThan(DateTime().timeTime())
782 True
783
784 >>> dt <= dt
785 True
786 >>> DateTime() <= dt
787 False
788 >>> dt <= DateTime().timeTime()
789 True
790 >>> DateTime().timeTime() <= dt
791 False
792
793 >>> dt.lessThanEqualTo(dt)
794 True
795 >>> DateTime().lessThanEqualTo(dt)
796 False
797 >>> dt.lessThanEqualTo(DateTime().timeTime())
798 True
799
800 Numeric Services Provided by DateTime
801 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
802
803 A DateTime may be added to a number and a number may be added to a
804 DateTime:
805
806 >>> dt + 5
807 DateTime('1997/03/14 13:45:00 US/Eastern')
808 >>> 5 + dt
809 DateTime('1997/03/14 13:45:00 US/Eastern')
810
811 Two DateTimes cannot be added:
812
813 >>> from DateTime.interfaces import DateTimeError
814 >>> try:
815 ... dt + dt
816 ... print('fail')
817 ... except DateTimeError:
818 ... print('ok')
819 ok
820
821 Either a DateTime or a number may be subtracted from a DateTime,
822 however, a DateTime may not be subtracted from a number:
823
824 >>> DateTime('1997/03/10 13:45 US/Eastern') - dt
825 1.0
826 >>> dt - 1
827 DateTime('1997/03/08 13:45:00 US/Eastern')
828 >>> 1 - dt
829 Traceback (most recent call last):
830 ...
831 TypeError: unsupported operand type(s) for -: 'int' and 'DateTime'
832
833 DateTimes can also be converted to integers (number of seconds since
834 the epoch) and floats:
835
836 >>> int(dt)
837 857933100
838 >>> float(dt)
839 857933100.0
840
841
842 Changelog
843 =========
844
845 5.5 (2024-03-21)
846 ----------------
847
848 - Change pickle format to export the microseconds as an int, to
849 solve a problem with dates after 2038.
850 (`#56 <https://github.com/zopefoundation/DateTime/issues/56>`_)
851
852
853 5.4 (2023-12-15)
854 ----------------
855
856 - Fix ``UnknownTimeZoneError`` when unpickling ``DateTime.DateTime().asdatetime()``.
857 (`#58 <https://github.com/zopefoundation/DateTime/issues/58>`_)
858
859 - Repair equality comparison between DateTime instances and other types.
860 (`#60 <https://github.com/zopefoundation/DateTime/issues/60>`_)
861
862
863 5.3 (2023-11-14)
864 ----------------
865
866 - Add support for Python 3.12.
867
868 - Add preliminary support for Python 3.13a2.
869
870
871 5.2 (2023-07-19)
872 ----------------
873
874 - Cast int to float in compare methods.
875 - Fix compare methods between DateTime instances and None.
876 (`#52 <https://github.com/zopefoundation/DateTime/issues/52>`_)
877
878
879 5.1 (2023-03-14)
880 ----------------
881
882 - Add missing ``python_requires`` to ``setup.py``.
883
884
885 5.0 (2023-01-12)
886 ----------------
887
888 - Drop support for Python 2.7, 3.5, 3.6.
889
890
891 4.8 (2022-12-16)
892 ----------------
893
894 - Fix insidious buildout configuration bug that prevented tests on Python 2.7
895 and 3.5, and fix test code that was incompatible with Python 3.5.
896 (`#44 <https://github.com/zopefoundation/DateTime/issues/44>`_)
897
898 - Add support for Python 3.11.
899
900
901 4.7 (2022-09-14)
902 ----------------
903
904 - Fix rounding problem with `DateTime` addition beyond the year 2038
905 (`#41 <https://github.com/zopefoundation/DateTime/issues/41>`_)
906
907
908 4.6 (2022-09-10)
909 ----------------
910
911 - Fix ``__format__`` method for DateTime objects
912 (`#39 <https://github.com/zopefoundation/DateTime/issues/39>`_)
913
914
915 4.5 (2022-07-04)
916 ----------------
917
918 - Add ``__format__`` method for DateTime objects
919 (`#35 <https://github.com/zopefoundation/DateTime/issues/35>`_)
920
921
922 4.4 (2022-02-11)
923 ----------------
924
925 - Fix WAT definition
926 `#31 <https://github.com/zopefoundation/DateTime/issues/31>`_.
927
928 - Add support for Python 3.8, 3.9, and 3.10.
929
930 - Drop support for Python 3.4.
931
932 4.3 (2018-10-05)
933 ----------------
934
935 - Add support for Python 3.7.
936
937 4.2 (2017-04-26)
938 ----------------
939
940 - Add support for Python 3.6, drop support for Python 3.3.
941
942 4.1.1 (2016-04-30)
943 ------------------
944
945 - Support unpickling instances having a numeric timezone like `+0430`.
946
947 4.1 (2016-04-03)
948 ----------------
949
950 - Add support for Python 3.4 and 3.5.
951
952 - Drop support for Python 2.6 and 3.2.
953
954 4.0.1 (2013-10-15)
955 ------------------
956
957 - Provide more backward compatible timezones.
958 [vangheem]
959
960 4.0 (2013-02-23)
961 ----------------
962
963 - Added support for Python 3.2 and 3.3 in addition to 2.6 and 2.7.
964
965 - Removed unused legacy pytz tests and the DateTimeZone module and renamed
966 some test internals.
967
968 3.0.3 (2013-01-22)
969 ------------------
970
971 - Allow timezone argument to be a Unicode string while creating a DateTime
972 object using two arguments.
973
974 3.0.2 (2012-10-21)
975 ------------------
976
977 - LP #1045233: Respect date format setting for parsing dates like `11-01-2001`.
978
979 3.0.1 (2012-09-23)
980 ------------------
981
982 - Add `_dt_reconstructor` function introduced in DateTime 2.12.7 to provide
983 forward compatibility with pickles that might reference this function.
984
985 3.0 (2011-12-09)
986 ----------------
987
988 - No changes.
989
990 Backwards compatibility of DateTime 3
991 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
992
993 DateTime 3 changes its pickle representation. DateTime instances pickled with
994 former versions of DateTime can be read, but older DateTime versions cannot read
995 DateTime instances pickled with version 3.
996
997 DateTime 3 changes DateTime to be a new-style class with slots instead of being
998 an old-style class.
999
1000 DateTime 3 tries to preserve microsecond resolution throughout most of its API's
1001 while former versions were often only accurate to millisecond resolution. Due to
1002 the representation of float values in Python versions before Python 2.7 you
1003 shouldn't compare string or float representations of DateTime instances if you
1004 want high accuracy. The same is true for calculated values returned by methods
1005 like `timeTime()`. You get the highest accuracy of comparing DateTime values by
1006 calling its `micros()` methods. DateTime is not particular well suited to be
1007 used in comparing timestamps of file systems - use the time and datetime objects
1008 from the Python standard library instead.
1009
1010 3.0b3 (2011-10-19)
1011 ------------------
1012
1013 - Allow comparison of DateTime objects against None.
1014
1015 3.0b2 (2011-10-19)
1016 ------------------
1017
1018 - Reverted the single argument `None` special case handling for unpickling and
1019 continue to treat it as meaning `now`.
1020
1021 3.0b1 (2011-05-07)
1022 ------------------
1023
1024 - Restored `strftimeFormatter` as a class.
1025
1026 - Added tests for read-only class attributes and interface.
1027
1028 3.0a2 (2011-05-07)
1029 ------------------
1030
1031 - Added back support for reading old DateTime pickles without a `_micros` value.
1032
1033 - Avoid storing `_t` representing the time as a float in seconds since the
1034 epoch, as we already have `_micros` doing the same as a long. Memory use is
1035 down to about 300 bytes per DateTime instance.
1036
1037 - Updated exception raising syntax to current style.
1038
1039 - Avoid storing `_aday`, `_fday`, `_pday`, `_amon`, `_fmon`, `_pmon`, `_pmhour`
1040 and `_pm` in memory for every instance but look them up dynamically based on
1041 `_dayoffset`, `_month` and `_hour`. This saves another 150 bytes of memory
1042 per DateTime instance.
1043
1044 - Moved various internal parsing related class variables to module constants.
1045
1046 - No longer provide the `DateError`, `DateTimeError`, `SyntaxError` and
1047 `TimeError` exceptions as class attributes, import them from their canonical
1048 `DateTime.interfaces` location instead.
1049
1050 - Removed deprecated `_isDST` and `_localzone` class variables.
1051
1052 - Moved pytz cache from `DateTime._tzinfo` to a module global `_TZINFO`.
1053
1054 - Make DateTime a new-style class and limit its available attributes via a
1055 slots definition. The pickle size increases to 110 bytes thanks to the
1056 `ccopy_reg\n_reconstructor` stanza. But the memory size drops from 3kb to
1057 500 bytes for each instance.
1058
1059 3.0a1 (2011-05-06)
1060 ------------------
1061
1062 - Reordered some calculations in `_calcIndependentSecondEtc` to preserve more
1063 floating point precision.
1064
1065 - Optimized the pickled data, by only storing a tuple of `_micros` and time
1066 zone information - this reduces the pickle size from an average of 300 bytes
1067 to just 60 bytes.
1068
1069 - Optimized un-pickling, by avoiding the creation of an intermediate DateTime
1070 value representing the current time.
1071
1072 - Removed in-place migration of old DateTime pickles without a `_micros` value.
1073
1074 - Removed deprecated support for using `DateTime.__cmp__`.
1075
1076 - Take time zone settings into account when comparing two date times for
1077 (non-) equality.
1078
1079 - Fixed (possibly unused) _parse_iso8601 function.
1080
1081 - Removed unused import of legacy DateTimeZone, strftime and re.
1082 Remove trailing whitespace.
1083
1084 - Removed reference to missing version section from buildout.
1085
1086 2.12.7 (2012-08-11)
1087 -------------------
1088
1089 - Added forward compatibility with DateTime 3 pickle format. DateTime
1090 instances constructed under version 3 can be read and unpickled by this
1091 version. The pickled data is converted to the current versions format
1092 (old-style class / no slots). Once converted it will be stored again in the
1093 old format. This should allow for a transparent upgrade/downgrade path
1094 between DateTime 2 and 3.
1095
1096 2.12.6 (2010-10-17)
1097 -------------------
1098
1099 - Changed ``testDayOfWeek`` test to be independent of OS locale.
1100
1101 2.12.5 (2010-07-29)
1102 -------------------
1103
1104 - Launchpad #143269: Corrected the documentation for year value
1105 behavior when constructing a DateTime object with three numeric
1106 arguments.
1107
1108 - Launchpad #142521: Removed confusing special case in
1109 DateTime.__str__ where DateTime instances for midnight
1110 (e.g. '2010-07-27 00:00:00 US/Eastern') values would
1111 render only their date and nothing else.
1112
1113 2.12.4 (2010-07-12)
1114 -------------------
1115
1116 - Fixed mapping of EDT (was -> 'GMT-0400', now 'GMT-4').
1117
1118 2.12.3 (2010-07-09)
1119 -------------------
1120
1121 - Added EDT timezone support. Addresses bug #599856.
1122 [vangheem]
1123
1124 2.12.2 (2010-05-05)
1125 -------------------
1126
1127 - Launchpad #572715: Relaxed pin on pytz, after applying a patch from
1128 Marius Gedminus which fixes the apparent API breakage.
1129
1130 2.12.1 (2010-04-30)
1131 -------------------
1132
1133 - Removed an undeclared testing dependency on zope.testing.doctest in favor of
1134 the standard libraries doctest module.
1135
1136 - Added a maximum version requirement on pytz <= 2010b. Later versions produce
1137 test failures related to timezone changes.
1138
1139 2.12.0 (2009-03-04)
1140 -------------------
1141
1142 - Launchpad #290254: Forward-ported fix for '_micros'-less pickles from
1143 the Zope 2.11 branch version.
1144
1145 2.11.2 (2009-02-02)
1146 -------------------
1147
1148 - Include *all* pytz zone names, not just "common" ones.
1149
1150 - Fix one fragile doctest, band-aid another.
1151
1152 - Fix for launchpad #267545: DateTime(DateTime()) should preserve the
1153 correct hour.
1154
1155 2.11.1 (2008-08-05)
1156 -------------------
1157
1158 - DateTime conversion of datetime objects with non-pytz tzinfo. Timezones()
1159 returns a copy of the timezone list (allows tests to run).
1160
1161 - Merged the slinkp-datetime-200007 branch: fix the DateTime(anotherDateTime)
1162 constructor to preserve timezones.
1163
1164 2.11.0b1 (2008-01-06)
1165 ---------------------
1166
1167 - Split off from the Zope2 main source code tree.