Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/lib/python3.8/site-packages/DateTime/DateTime.txt @ 68:5028fdace37b

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 16:23:26 -0400
parents
children
rev   line source
jpayne@68 1 The DateTime package
jpayne@68 2 ====================
jpayne@68 3
jpayne@68 4 Encapsulation of date/time values.
jpayne@68 5
jpayne@68 6
jpayne@68 7 Function Timezones()
jpayne@68 8 --------------------
jpayne@68 9
jpayne@68 10 Returns the list of recognized timezone names:
jpayne@68 11
jpayne@68 12 >>> from DateTime import Timezones
jpayne@68 13 >>> zones = set(Timezones())
jpayne@68 14
jpayne@68 15 Almost all of the standard pytz timezones are included, with the exception
jpayne@68 16 of some commonly-used but ambiguous abbreviations, where historical Zope
jpayne@68 17 usage conflicts with the name used by pytz:
jpayne@68 18
jpayne@68 19 >>> import pytz
jpayne@68 20 >>> [x for x in pytz.all_timezones if x not in zones]
jpayne@68 21 ['CET', 'EET', 'EST', 'MET', 'MST', 'WET']
jpayne@68 22
jpayne@68 23 Class DateTime
jpayne@68 24 --------------
jpayne@68 25
jpayne@68 26 DateTime objects represent instants in time and provide interfaces for
jpayne@68 27 controlling its representation without affecting the absolute value of
jpayne@68 28 the object.
jpayne@68 29
jpayne@68 30 DateTime objects may be created from a wide variety of string or
jpayne@68 31 numeric data, or may be computed from other DateTime objects.
jpayne@68 32 DateTimes support the ability to convert their representations to many
jpayne@68 33 major timezones, as well as the ability to create a DateTime object
jpayne@68 34 in the context of a given timezone.
jpayne@68 35
jpayne@68 36 DateTime objects provide partial numerical behavior:
jpayne@68 37
jpayne@68 38 * Two date-time objects can be subtracted to obtain a time, in days
jpayne@68 39 between the two.
jpayne@68 40
jpayne@68 41 * A date-time object and a positive or negative number may be added to
jpayne@68 42 obtain a new date-time object that is the given number of days later
jpayne@68 43 than the input date-time object.
jpayne@68 44
jpayne@68 45 * A positive or negative number and a date-time object may be added to
jpayne@68 46 obtain a new date-time object that is the given number of days later
jpayne@68 47 than the input date-time object.
jpayne@68 48
jpayne@68 49 * A positive or negative number may be subtracted from a date-time
jpayne@68 50 object to obtain a new date-time object that is the given number of
jpayne@68 51 days earlier than the input date-time object.
jpayne@68 52
jpayne@68 53 DateTime objects may be converted to integer, long, or float numbers
jpayne@68 54 of days since January 1, 1901, using the standard int, long, and float
jpayne@68 55 functions (Compatibility Note: int, long and float return the number
jpayne@68 56 of days since 1901 in GMT rather than local machine timezone).
jpayne@68 57 DateTime objects also provide access to their value in a float format
jpayne@68 58 usable with the Python time module, provided that the value of the
jpayne@68 59 object falls in the range of the epoch-based time module.
jpayne@68 60
jpayne@68 61 A DateTime object should be considered immutable; all conversion and numeric
jpayne@68 62 operations return a new DateTime object rather than modify the current object.
jpayne@68 63
jpayne@68 64 A DateTime object always maintains its value as an absolute UTC time,
jpayne@68 65 and is represented in the context of some timezone based on the
jpayne@68 66 arguments used to create the object. A DateTime object's methods
jpayne@68 67 return values based on the timezone context.
jpayne@68 68
jpayne@68 69 Note that in all cases the local machine timezone is used for
jpayne@68 70 representation if no timezone is specified.
jpayne@68 71
jpayne@68 72 Constructor for DateTime
jpayne@68 73 ------------------------
jpayne@68 74
jpayne@68 75 DateTime() returns a new date-time object. DateTimes may be created
jpayne@68 76 with from zero to seven arguments:
jpayne@68 77
jpayne@68 78 * If the function is called with no arguments, then the current date/
jpayne@68 79 time is returned, represented in the timezone of the local machine.
jpayne@68 80
jpayne@68 81 * If the function is invoked with a single string argument which is a
jpayne@68 82 recognized timezone name, an object representing the current time is
jpayne@68 83 returned, represented in the specified timezone.
jpayne@68 84
jpayne@68 85 * If the function is invoked with a single string argument
jpayne@68 86 representing a valid date/time, an object representing that date/
jpayne@68 87 time will be returned.
jpayne@68 88
jpayne@68 89 As a general rule, any date-time representation that is recognized
jpayne@68 90 and unambiguous to a resident of North America is acceptable. (The
jpayne@68 91 reason for this qualification is that in North America, a date like:
jpayne@68 92 2/1/1994 is interpreted as February 1, 1994, while in some parts of
jpayne@68 93 the world, it is interpreted as January 2, 1994.) A date/ time
jpayne@68 94 string consists of two components, a date component and an optional
jpayne@68 95 time component, separated by one or more spaces. If the time
jpayne@68 96 component is omitted, 12:00am is assumed.
jpayne@68 97
jpayne@68 98 Any recognized timezone name specified as the final element of the
jpayne@68 99 date/time string will be used for computing the date/time value.
jpayne@68 100 (If you create a DateTime with the string,
jpayne@68 101 "Mar 9, 1997 1:45pm US/Pacific", the value will essentially be the
jpayne@68 102 same as if you had captured time.time() at the specified date and
jpayne@68 103 time on a machine in that timezone). If no timezone is passed, then
jpayne@68 104 the timezone configured on the local machine will be used, **except**
jpayne@68 105 that if the date format matches ISO 8601 ('YYYY-MM-DD'), the instance
jpayne@68 106 will use UTC / GMT+0 as the timezone.
jpayne@68 107
jpayne@68 108 o Returns current date/time, represented in US/Eastern:
jpayne@68 109
jpayne@68 110 >>> from DateTime import DateTime
jpayne@68 111 >>> e = DateTime('US/Eastern')
jpayne@68 112 >>> e.timezone()
jpayne@68 113 'US/Eastern'
jpayne@68 114
jpayne@68 115 o Returns specified time, represented in local machine zone:
jpayne@68 116
jpayne@68 117 >>> x = DateTime('1997/3/9 1:45pm')
jpayne@68 118 >>> x.parts() # doctest: +ELLIPSIS
jpayne@68 119 (1997, 3, 9, 13, 45, ...)
jpayne@68 120
jpayne@68 121 o Specified time in local machine zone, verbose format:
jpayne@68 122
jpayne@68 123 >>> y = DateTime('Mar 9, 1997 13:45:00')
jpayne@68 124 >>> y.parts() # doctest: +ELLIPSIS
jpayne@68 125 (1997, 3, 9, 13, 45, ...)
jpayne@68 126 >>> y == x
jpayne@68 127 True
jpayne@68 128
jpayne@68 129 o Specified time in UTC via ISO 8601 rule:
jpayne@68 130
jpayne@68 131 >>> z = DateTime('2014-03-24')
jpayne@68 132 >>> z.parts() # doctest: +ELLIPSIS
jpayne@68 133 (2014, 3, 24, 0, 0, ...)
jpayne@68 134 >>> z.timezone()
jpayne@68 135 'GMT+0'
jpayne@68 136
jpayne@68 137 The date component consists of year, month, and day values. The
jpayne@68 138 year value must be a one-, two-, or four-digit integer. If a one-
jpayne@68 139 or two-digit year is used, the year is assumed to be in the
jpayne@68 140 twentieth century. The month may an integer, from 1 to 12, a month
jpayne@68 141 name, or a month abbreviation, where a period may optionally follow
jpayne@68 142 the abbreviation. The day must be an integer from 1 to the number of
jpayne@68 143 days in the month. The year, month, and day values may be separated
jpayne@68 144 by periods, hyphens, forward slashes, or spaces. Extra spaces are
jpayne@68 145 permitted around the delimiters. Year, month, and day values may be
jpayne@68 146 given in any order as long as it is possible to distinguish the
jpayne@68 147 components. If all three components are numbers that are less than
jpayne@68 148 13, then a month-day-year ordering is assumed.
jpayne@68 149
jpayne@68 150 The time component consists of hour, minute, and second values
jpayne@68 151 separated by colons. The hour value must be an integer between 0
jpayne@68 152 and 23 inclusively. The minute value must be an integer between 0
jpayne@68 153 and 59 inclusively. The second value may be an integer value
jpayne@68 154 between 0 and 59.999 inclusively. The second value or both the
jpayne@68 155 minute and second values may be omitted. The time may be followed
jpayne@68 156 by am or pm in upper or lower case, in which case a 12-hour clock is
jpayne@68 157 assumed.
jpayne@68 158
jpayne@68 159 * If the DateTime function is invoked with a single numeric argument,
jpayne@68 160 the number is assumed to be either a floating point value such as
jpayne@68 161 that returned by time.time(), or a number of days after January 1,
jpayne@68 162 1901 00:00:00 UTC.
jpayne@68 163
jpayne@68 164 A DateTime object is returned that represents either the GMT value
jpayne@68 165 of the time.time() float represented in the local machine's
jpayne@68 166 timezone, or that number of days after January 1, 1901. Note that
jpayne@68 167 the number of days after 1901 need to be expressed from the
jpayne@68 168 viewpoint of the local machine's timezone. A negative argument will
jpayne@68 169 yield a date-time value before 1901.
jpayne@68 170
jpayne@68 171 * If the function is invoked with two numeric arguments, then the
jpayne@68 172 first is taken to be an integer year and the second argument is
jpayne@68 173 taken to be an offset in days from the beginning of the year, in the
jpayne@68 174 context of the local machine timezone. The date-time value returned
jpayne@68 175 is the given offset number of days from the beginning of the given
jpayne@68 176 year, represented in the timezone of the local machine. The offset
jpayne@68 177 may be positive or negative. Two-digit years are assumed to be in
jpayne@68 178 the twentieth century.
jpayne@68 179
jpayne@68 180 * If the function is invoked with two arguments, the first a float
jpayne@68 181 representing a number of seconds past the epoch in GMT (such as
jpayne@68 182 those returned by time.time()) and the second a string naming a
jpayne@68 183 recognized timezone, a DateTime with a value of that GMT time will
jpayne@68 184 be returned, represented in the given timezone.
jpayne@68 185
jpayne@68 186 >>> import time
jpayne@68 187 >>> t = time.time()
jpayne@68 188
jpayne@68 189 Time t represented as US/Eastern:
jpayne@68 190
jpayne@68 191 >>> now_east = DateTime(t, 'US/Eastern')
jpayne@68 192
jpayne@68 193 Time t represented as US/Pacific:
jpayne@68 194
jpayne@68 195 >>> now_west = DateTime(t, 'US/Pacific')
jpayne@68 196
jpayne@68 197 Only their representations are different:
jpayne@68 198
jpayne@68 199 >>> now_east.equalTo(now_west)
jpayne@68 200 True
jpayne@68 201
jpayne@68 202 * If the function is invoked with three or more numeric arguments,
jpayne@68 203 then the first is taken to be an integer year, the second is taken
jpayne@68 204 to be an integer month, and the third is taken to be an integer day.
jpayne@68 205 If the combination of values is not valid, then a DateTimeError is
jpayne@68 206 raised. One- or two-digit years up to 69 are assumed to be in the
jpayne@68 207 21st century, whereas values 70-99 are assumed to be 20th century.
jpayne@68 208 The fourth, fifth, and sixth arguments are floating point, positive
jpayne@68 209 or negative offsets in units of hours, minutes, and days, and
jpayne@68 210 default to zero if not given. An optional string may be given as
jpayne@68 211 the final argument to indicate timezone (the effect of this is as if
jpayne@68 212 you had taken the value of time.time() at that time on a machine in
jpayne@68 213 the specified timezone).
jpayne@68 214
jpayne@68 215 If a string argument passed to the DateTime constructor cannot be
jpayne@68 216 parsed, it will raise SyntaxError. Invalid date, time, or
jpayne@68 217 timezone components will raise a DateTimeError.
jpayne@68 218
jpayne@68 219 The module function Timezones() will return a list of the timezones
jpayne@68 220 recognized by the DateTime module. Recognition of timezone names is
jpayne@68 221 case-insensitive.
jpayne@68 222
jpayne@68 223 Instance Methods for DateTime (IDateTime interface)
jpayne@68 224 ---------------------------------------------------
jpayne@68 225
jpayne@68 226 Conversion and comparison methods
jpayne@68 227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@68 228
jpayne@68 229 * ``timeTime()`` returns the date/time as a floating-point number in
jpayne@68 230 UTC, in the format used by the Python time module. Note that it is
jpayne@68 231 possible to create date /time values with DateTime that have no
jpayne@68 232 meaningful value to the time module, and in such cases a
jpayne@68 233 DateTimeError is raised. A DateTime object's value must generally
jpayne@68 234 be between Jan 1, 1970 (or your local machine epoch) and Jan 2038 to
jpayne@68 235 produce a valid time.time() style value.
jpayne@68 236
jpayne@68 237 >>> dt = DateTime('Mar 9, 1997 13:45:00 US/Eastern')
jpayne@68 238 >>> dt.timeTime()
jpayne@68 239 857933100.0
jpayne@68 240
jpayne@68 241 >>> DateTime('2040/01/01 UTC').timeTime()
jpayne@68 242 2208988800.0
jpayne@68 243
jpayne@68 244 >>> DateTime('1900/01/01 UTC').timeTime()
jpayne@68 245 -2208988800.0
jpayne@68 246
jpayne@68 247 * ``toZone(z)`` returns a DateTime with the value as the current
jpayne@68 248 object, represented in the indicated timezone:
jpayne@68 249
jpayne@68 250 >>> dt.toZone('UTC')
jpayne@68 251 DateTime('1997/03/09 18:45:00 UTC')
jpayne@68 252
jpayne@68 253 >>> dt.toZone('UTC').equalTo(dt)
jpayne@68 254 True
jpayne@68 255
jpayne@68 256 * ``isFuture()`` returns true if this object represents a date/time
jpayne@68 257 later than the time of the call:
jpayne@68 258
jpayne@68 259 >>> dt.isFuture()
jpayne@68 260 False
jpayne@68 261 >>> DateTime('Jan 1 3000').isFuture() # not time-machine safe!
jpayne@68 262 True
jpayne@68 263
jpayne@68 264 * ``isPast()`` returns true if this object represents a date/time
jpayne@68 265 earlier than the time of the call:
jpayne@68 266
jpayne@68 267 >>> dt.isPast()
jpayne@68 268 True
jpayne@68 269 >>> DateTime('Jan 1 3000').isPast() # not time-machine safe!
jpayne@68 270 False
jpayne@68 271
jpayne@68 272 * ``isCurrentYear()`` returns true if this object represents a
jpayne@68 273 date/time that falls within the current year, in the context of this
jpayne@68 274 object's timezone representation:
jpayne@68 275
jpayne@68 276 >>> dt.isCurrentYear()
jpayne@68 277 False
jpayne@68 278 >>> DateTime().isCurrentYear()
jpayne@68 279 True
jpayne@68 280
jpayne@68 281 * ``isCurrentMonth()`` returns true if this object represents a
jpayne@68 282 date/time that falls within the current month, in the context of
jpayne@68 283 this object's timezone representation:
jpayne@68 284
jpayne@68 285 >>> dt.isCurrentMonth()
jpayne@68 286 False
jpayne@68 287 >>> DateTime().isCurrentMonth()
jpayne@68 288 True
jpayne@68 289
jpayne@68 290 * ``isCurrentDay()`` returns true if this object represents a
jpayne@68 291 date/time that falls within the current day, in the context of this
jpayne@68 292 object's timezone representation:
jpayne@68 293
jpayne@68 294 >>> dt.isCurrentDay()
jpayne@68 295 False
jpayne@68 296 >>> DateTime().isCurrentDay()
jpayne@68 297 True
jpayne@68 298
jpayne@68 299 * ``isCurrentHour()`` returns true if this object represents a
jpayne@68 300 date/time that falls within the current hour, in the context of this
jpayne@68 301 object's timezone representation:
jpayne@68 302
jpayne@68 303 >>> dt.isCurrentHour()
jpayne@68 304 False
jpayne@68 305
jpayne@68 306 >>> DateTime().isCurrentHour()
jpayne@68 307 True
jpayne@68 308
jpayne@68 309 * ``isCurrentMinute()`` returns true if this object represents a
jpayne@68 310 date/time that falls within the current minute, in the context of
jpayne@68 311 this object's timezone representation:
jpayne@68 312
jpayne@68 313 >>> dt.isCurrentMinute()
jpayne@68 314 False
jpayne@68 315 >>> DateTime().isCurrentMinute()
jpayne@68 316 True
jpayne@68 317
jpayne@68 318 * ``isLeapYear()`` returns true if the current year (in the context of
jpayne@68 319 the object's timezone) is a leap year:
jpayne@68 320
jpayne@68 321 >>> dt.isLeapYear()
jpayne@68 322 False
jpayne@68 323 >>> DateTime('Mar 8 2004').isLeapYear()
jpayne@68 324 True
jpayne@68 325
jpayne@68 326 * ``earliestTime()`` returns a new DateTime object that represents the
jpayne@68 327 earliest possible time (in whole seconds) that still falls within
jpayne@68 328 the current object's day, in the object's timezone context:
jpayne@68 329
jpayne@68 330 >>> dt.earliestTime()
jpayne@68 331 DateTime('1997/03/09 00:00:00 US/Eastern')
jpayne@68 332
jpayne@68 333 * ``latestTime()`` return a new DateTime object that represents the
jpayne@68 334 latest possible time (in whole seconds) that still falls within the
jpayne@68 335 current object's day, in the object's timezone context
jpayne@68 336
jpayne@68 337 >>> dt.latestTime()
jpayne@68 338 DateTime('1997/03/09 23:59:59 US/Eastern')
jpayne@68 339
jpayne@68 340 Component access
jpayne@68 341 ~~~~~~~~~~~~~~~~
jpayne@68 342
jpayne@68 343 * ``parts()`` returns a tuple containing the calendar year, month,
jpayne@68 344 day, hour, minute second and timezone of the object
jpayne@68 345
jpayne@68 346 >>> dt.parts() # doctest: +ELLIPSIS
jpayne@68 347 (1997, 3, 9, 13, 45, ... 'US/Eastern')
jpayne@68 348
jpayne@68 349 * ``timezone()`` returns the timezone in which the object is represented:
jpayne@68 350
jpayne@68 351 >>> dt.timezone() in Timezones()
jpayne@68 352 True
jpayne@68 353
jpayne@68 354 * ``tzoffset()`` returns the timezone offset for the objects timezone:
jpayne@68 355
jpayne@68 356 >>> dt.tzoffset()
jpayne@68 357 -18000
jpayne@68 358
jpayne@68 359 * ``year()`` returns the calendar year of the object:
jpayne@68 360
jpayne@68 361 >>> dt.year()
jpayne@68 362 1997
jpayne@68 363
jpayne@68 364 * ``month()`` returns the month of the object as an integer:
jpayne@68 365
jpayne@68 366 >>> dt.month()
jpayne@68 367 3
jpayne@68 368
jpayne@68 369 * ``Month()`` returns the full month name:
jpayne@68 370
jpayne@68 371 >>> dt.Month()
jpayne@68 372 'March'
jpayne@68 373
jpayne@68 374 * ``aMonth()`` returns the abbreviated month name:
jpayne@68 375
jpayne@68 376 >>> dt.aMonth()
jpayne@68 377 'Mar'
jpayne@68 378
jpayne@68 379 * ``pMonth()`` returns the abbreviated (with period) month name:
jpayne@68 380
jpayne@68 381 >>> dt.pMonth()
jpayne@68 382 'Mar.'
jpayne@68 383
jpayne@68 384 * ``day()`` returns the integer day:
jpayne@68 385
jpayne@68 386 >>> dt.day()
jpayne@68 387 9
jpayne@68 388
jpayne@68 389 * ``Day()`` returns the full name of the day of the week:
jpayne@68 390
jpayne@68 391 >>> dt.Day()
jpayne@68 392 'Sunday'
jpayne@68 393
jpayne@68 394 * ``dayOfYear()`` returns the day of the year, in context of the
jpayne@68 395 timezone representation of the object:
jpayne@68 396
jpayne@68 397 >>> dt.dayOfYear()
jpayne@68 398 68
jpayne@68 399
jpayne@68 400 * ``aDay()`` returns the abbreviated name of the day of the week:
jpayne@68 401
jpayne@68 402 >>> dt.aDay()
jpayne@68 403 'Sun'
jpayne@68 404
jpayne@68 405 * ``pDay()`` returns the abbreviated (with period) name of the day of
jpayne@68 406 the week:
jpayne@68 407
jpayne@68 408 >>> dt.pDay()
jpayne@68 409 'Sun.'
jpayne@68 410
jpayne@68 411 * ``dow()`` returns the integer day of the week, where Sunday is 0:
jpayne@68 412
jpayne@68 413 >>> dt.dow()
jpayne@68 414 0
jpayne@68 415
jpayne@68 416 * ``dow_1()`` returns the integer day of the week, where sunday is 1:
jpayne@68 417
jpayne@68 418 >>> dt.dow_1()
jpayne@68 419 1
jpayne@68 420
jpayne@68 421 * ``h_12()`` returns the 12-hour clock representation of the hour:
jpayne@68 422
jpayne@68 423 >>> dt.h_12()
jpayne@68 424 1
jpayne@68 425
jpayne@68 426 * ``h_24()`` returns the 24-hour clock representation of the hour:
jpayne@68 427
jpayne@68 428 >>> dt.h_24()
jpayne@68 429 13
jpayne@68 430
jpayne@68 431 * ``ampm()`` returns the appropriate time modifier (am or pm):
jpayne@68 432
jpayne@68 433 >>> dt.ampm()
jpayne@68 434 'pm'
jpayne@68 435
jpayne@68 436 * ``hour()`` returns the 24-hour clock representation of the hour:
jpayne@68 437
jpayne@68 438 >>> dt.hour()
jpayne@68 439 13
jpayne@68 440
jpayne@68 441 * ``minute()`` returns the minute:
jpayne@68 442
jpayne@68 443 >>> dt.minute()
jpayne@68 444 45
jpayne@68 445
jpayne@68 446 * ``second()`` returns the second:
jpayne@68 447
jpayne@68 448 >>> dt.second() == 0
jpayne@68 449 True
jpayne@68 450
jpayne@68 451 * ``millis()`` returns the milliseconds since the epoch in GMT.
jpayne@68 452
jpayne@68 453 >>> dt.millis() == 857933100000
jpayne@68 454 True
jpayne@68 455
jpayne@68 456 strftime()
jpayne@68 457 ~~~~~~~~~~
jpayne@68 458
jpayne@68 459 See ``tests/test_datetime.py``.
jpayne@68 460
jpayne@68 461 General formats from previous DateTime
jpayne@68 462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@68 463
jpayne@68 464 * ``Date()`` return the date string for the object:
jpayne@68 465
jpayne@68 466 >>> dt.Date()
jpayne@68 467 '1997/03/09'
jpayne@68 468
jpayne@68 469 * ``Time()`` returns the time string for an object to the nearest
jpayne@68 470 second:
jpayne@68 471
jpayne@68 472 >>> dt.Time()
jpayne@68 473 '13:45:00'
jpayne@68 474
jpayne@68 475 * ``TimeMinutes()`` returns the time string for an object not showing
jpayne@68 476 seconds:
jpayne@68 477
jpayne@68 478 >>> dt.TimeMinutes()
jpayne@68 479 '13:45'
jpayne@68 480
jpayne@68 481 * ``AMPM()`` returns the time string for an object to the nearest second:
jpayne@68 482
jpayne@68 483 >>> dt.AMPM()
jpayne@68 484 '01:45:00 pm'
jpayne@68 485
jpayne@68 486 * ``AMPMMinutes()`` returns the time string for an object not showing
jpayne@68 487 seconds:
jpayne@68 488
jpayne@68 489 >>> dt.AMPMMinutes()
jpayne@68 490 '01:45 pm'
jpayne@68 491
jpayne@68 492 * ``PreciseTime()`` returns the time string for the object:
jpayne@68 493
jpayne@68 494 >>> dt.PreciseTime()
jpayne@68 495 '13:45:00.000'
jpayne@68 496
jpayne@68 497 * ``PreciseAMPM()`` returns the time string for the object:
jpayne@68 498
jpayne@68 499 >>> dt.PreciseAMPM()
jpayne@68 500 '01:45:00.000 pm'
jpayne@68 501
jpayne@68 502 * ``yy()`` returns the calendar year as a 2 digit string
jpayne@68 503
jpayne@68 504 >>> dt.yy()
jpayne@68 505 '97'
jpayne@68 506
jpayne@68 507 * ``mm()`` returns the month as a 2 digit string
jpayne@68 508
jpayne@68 509 >>> dt.mm()
jpayne@68 510 '03'
jpayne@68 511
jpayne@68 512 * ``dd()`` returns the day as a 2 digit string:
jpayne@68 513
jpayne@68 514 >>> dt.dd()
jpayne@68 515 '09'
jpayne@68 516
jpayne@68 517 * ``rfc822()`` returns the date in RFC 822 format:
jpayne@68 518
jpayne@68 519 >>> dt.rfc822()
jpayne@68 520 'Sun, 09 Mar 1997 13:45:00 -0500'
jpayne@68 521
jpayne@68 522 New formats
jpayne@68 523 ~~~~~~~~~~~
jpayne@68 524
jpayne@68 525 * ``fCommon()`` returns a string representing the object's value in
jpayne@68 526 the format: March 9, 1997 1:45 pm:
jpayne@68 527
jpayne@68 528 >>> dt.fCommon()
jpayne@68 529 'March 9, 1997 1:45 pm'
jpayne@68 530
jpayne@68 531 * ``fCommonZ()`` returns a string representing the object's value in
jpayne@68 532 the format: March 9, 1997 1:45 pm US/Eastern:
jpayne@68 533
jpayne@68 534 >>> dt.fCommonZ()
jpayne@68 535 'March 9, 1997 1:45 pm US/Eastern'
jpayne@68 536
jpayne@68 537 * ``aCommon()`` returns a string representing the object's value in
jpayne@68 538 the format: Mar 9, 1997 1:45 pm:
jpayne@68 539
jpayne@68 540 >>> dt.aCommon()
jpayne@68 541 'Mar 9, 1997 1:45 pm'
jpayne@68 542
jpayne@68 543 * ``aCommonZ()`` return a string representing the object's value in
jpayne@68 544 the format: Mar 9, 1997 1:45 pm US/Eastern:
jpayne@68 545
jpayne@68 546 >>> dt.aCommonZ()
jpayne@68 547 'Mar 9, 1997 1:45 pm US/Eastern'
jpayne@68 548
jpayne@68 549 * ``pCommon()`` returns a string representing the object's value in
jpayne@68 550 the format Mar. 9, 1997 1:45 pm:
jpayne@68 551
jpayne@68 552 >>> dt.pCommon()
jpayne@68 553 'Mar. 9, 1997 1:45 pm'
jpayne@68 554
jpayne@68 555 * ``pCommonZ()`` returns a string representing the object's value in
jpayne@68 556 the format: Mar. 9, 1997 1:45 pm US/Eastern:
jpayne@68 557
jpayne@68 558 >>> dt.pCommonZ()
jpayne@68 559 'Mar. 9, 1997 1:45 pm US/Eastern'
jpayne@68 560
jpayne@68 561 * ``ISO()`` returns a string with the date/time in ISO format. Note:
jpayne@68 562 this is not ISO 8601-format! See the ISO8601 and HTML4 methods below
jpayne@68 563 for ISO 8601-compliant output. Dates are output as: YYYY-MM-DD HH:MM:SS
jpayne@68 564
jpayne@68 565 >>> dt.ISO()
jpayne@68 566 '1997-03-09 13:45:00'
jpayne@68 567
jpayne@68 568 * ``ISO8601()`` returns the object in ISO 8601-compatible format
jpayne@68 569 containing the date, time with seconds-precision and the time zone
jpayne@68 570 identifier - see http://www.w3.org/TR/NOTE-datetime. Dates are
jpayne@68 571 output as: YYYY-MM-DDTHH:MM:SSTZD (T is a literal character, TZD is
jpayne@68 572 Time Zone Designator, format +HH:MM or -HH:MM).
jpayne@68 573
jpayne@68 574 The ``HTML4()`` method below offers the same formatting, but
jpayne@68 575 converts to UTC before returning the value and sets the TZD"Z"
jpayne@68 576
jpayne@68 577 >>> dt.ISO8601()
jpayne@68 578 '1997-03-09T13:45:00-05:00'
jpayne@68 579
jpayne@68 580
jpayne@68 581 * ``HTML4()`` returns the object in the format used in the HTML4.0
jpayne@68 582 specification, one of the standard forms in ISO8601. See
jpayne@68 583 http://www.w3.org/TR/NOTE-datetime. Dates are output as:
jpayne@68 584 YYYY-MM-DDTHH:MM:SSZ (T, Z are literal characters, the time is in
jpayne@68 585 UTC.):
jpayne@68 586
jpayne@68 587 >>> dt.HTML4()
jpayne@68 588 '1997-03-09T18:45:00Z'
jpayne@68 589
jpayne@68 590 * ``JulianDay()`` returns the Julian day according to
jpayne@68 591 http://www.tondering.dk/claus/cal/node3.html#sec-calcjd
jpayne@68 592
jpayne@68 593 >>> dt.JulianDay()
jpayne@68 594 2450517
jpayne@68 595
jpayne@68 596 * ``week()`` returns the week number according to ISO
jpayne@68 597 see http://www.tondering.dk/claus/cal/node6.html#SECTION00670000000000000000
jpayne@68 598
jpayne@68 599 >>> dt.week()
jpayne@68 600 10
jpayne@68 601
jpayne@68 602 Deprecated API
jpayne@68 603 ~~~~~~~~~~~~~~
jpayne@68 604
jpayne@68 605 * DayOfWeek(): see Day()
jpayne@68 606
jpayne@68 607 * Day_(): see pDay()
jpayne@68 608
jpayne@68 609 * Mon(): see aMonth()
jpayne@68 610
jpayne@68 611 * Mon_(): see pMonth
jpayne@68 612
jpayne@68 613 General Services Provided by DateTime
jpayne@68 614 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@68 615
jpayne@68 616 DateTimes can be repr()'ed; the result will be a string indicating how
jpayne@68 617 to make a DateTime object like this:
jpayne@68 618
jpayne@68 619 >>> repr(dt)
jpayne@68 620 "DateTime('1997/03/09 13:45:00 US/Eastern')"
jpayne@68 621
jpayne@68 622 When we convert them into a string, we get a nicer string that could
jpayne@68 623 actually be shown to a user:
jpayne@68 624
jpayne@68 625 >>> str(dt)
jpayne@68 626 '1997/03/09 13:45:00 US/Eastern'
jpayne@68 627
jpayne@68 628 The hash value of a DateTime is based on the date and time and is
jpayne@68 629 equal for different representations of the DateTime:
jpayne@68 630
jpayne@68 631 >>> hash(dt)
jpayne@68 632 3618678
jpayne@68 633 >>> hash(dt.toZone('UTC'))
jpayne@68 634 3618678
jpayne@68 635
jpayne@68 636 DateTime objects can be compared to other DateTime objects OR floating
jpayne@68 637 point numbers such as the ones which are returned by the Python time
jpayne@68 638 module by using the equalTo method. Using this API, True is returned if the
jpayne@68 639 object represents a date/time equal to the specified DateTime or time module
jpayne@68 640 style time:
jpayne@68 641
jpayne@68 642 >>> dt.equalTo(dt)
jpayne@68 643 True
jpayne@68 644 >>> dt.equalTo(dt.toZone('UTC'))
jpayne@68 645 True
jpayne@68 646 >>> dt.equalTo(dt.timeTime())
jpayne@68 647 True
jpayne@68 648 >>> dt.equalTo(DateTime())
jpayne@68 649 False
jpayne@68 650
jpayne@68 651 Same goes for inequalities:
jpayne@68 652
jpayne@68 653 >>> dt.notEqualTo(dt)
jpayne@68 654 False
jpayne@68 655 >>> dt.notEqualTo(dt.toZone('UTC'))
jpayne@68 656 False
jpayne@68 657 >>> dt.notEqualTo(dt.timeTime())
jpayne@68 658 False
jpayne@68 659 >>> dt.notEqualTo(DateTime())
jpayne@68 660 True
jpayne@68 661
jpayne@68 662 Normal equality operations only work with DateTime objects and take the
jpayne@68 663 timezone setting into account:
jpayne@68 664
jpayne@68 665 >>> dt == dt
jpayne@68 666 True
jpayne@68 667 >>> dt == dt.toZone('UTC')
jpayne@68 668 False
jpayne@68 669 >>> dt == DateTime()
jpayne@68 670 False
jpayne@68 671
jpayne@68 672 >>> dt != dt
jpayne@68 673 False
jpayne@68 674 >>> dt != dt.toZone('UTC')
jpayne@68 675 True
jpayne@68 676 >>> dt != DateTime()
jpayne@68 677 True
jpayne@68 678
jpayne@68 679 But the other comparison operations compare the referenced moment in time and
jpayne@68 680 not the representation itself:
jpayne@68 681
jpayne@68 682 >>> dt > dt
jpayne@68 683 False
jpayne@68 684 >>> DateTime() > dt
jpayne@68 685 True
jpayne@68 686 >>> dt > DateTime().timeTime()
jpayne@68 687 False
jpayne@68 688 >>> DateTime().timeTime() > dt
jpayne@68 689 True
jpayne@68 690
jpayne@68 691 >>> dt.greaterThan(dt)
jpayne@68 692 False
jpayne@68 693 >>> DateTime().greaterThan(dt)
jpayne@68 694 True
jpayne@68 695 >>> dt.greaterThan(DateTime().timeTime())
jpayne@68 696 False
jpayne@68 697
jpayne@68 698 >>> dt >= dt
jpayne@68 699 True
jpayne@68 700 >>> DateTime() >= dt
jpayne@68 701 True
jpayne@68 702 >>> dt >= DateTime().timeTime()
jpayne@68 703 False
jpayne@68 704 >>> DateTime().timeTime() >= dt
jpayne@68 705 True
jpayne@68 706
jpayne@68 707 >>> dt.greaterThanEqualTo(dt)
jpayne@68 708 True
jpayne@68 709 >>> DateTime().greaterThanEqualTo(dt)
jpayne@68 710 True
jpayne@68 711 >>> dt.greaterThanEqualTo(DateTime().timeTime())
jpayne@68 712 False
jpayne@68 713
jpayne@68 714 >>> dt < dt
jpayne@68 715 False
jpayne@68 716 >>> DateTime() < dt
jpayne@68 717 False
jpayne@68 718 >>> dt < DateTime().timeTime()
jpayne@68 719 True
jpayne@68 720 >>> DateTime().timeTime() < dt
jpayne@68 721 False
jpayne@68 722
jpayne@68 723 >>> dt.lessThan(dt)
jpayne@68 724 False
jpayne@68 725 >>> DateTime().lessThan(dt)
jpayne@68 726 False
jpayne@68 727 >>> dt.lessThan(DateTime().timeTime())
jpayne@68 728 True
jpayne@68 729
jpayne@68 730 >>> dt <= dt
jpayne@68 731 True
jpayne@68 732 >>> DateTime() <= dt
jpayne@68 733 False
jpayne@68 734 >>> dt <= DateTime().timeTime()
jpayne@68 735 True
jpayne@68 736 >>> DateTime().timeTime() <= dt
jpayne@68 737 False
jpayne@68 738
jpayne@68 739 >>> dt.lessThanEqualTo(dt)
jpayne@68 740 True
jpayne@68 741 >>> DateTime().lessThanEqualTo(dt)
jpayne@68 742 False
jpayne@68 743 >>> dt.lessThanEqualTo(DateTime().timeTime())
jpayne@68 744 True
jpayne@68 745
jpayne@68 746 Numeric Services Provided by DateTime
jpayne@68 747 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
jpayne@68 748
jpayne@68 749 A DateTime may be added to a number and a number may be added to a
jpayne@68 750 DateTime:
jpayne@68 751
jpayne@68 752 >>> dt + 5
jpayne@68 753 DateTime('1997/03/14 13:45:00 US/Eastern')
jpayne@68 754 >>> 5 + dt
jpayne@68 755 DateTime('1997/03/14 13:45:00 US/Eastern')
jpayne@68 756
jpayne@68 757 Two DateTimes cannot be added:
jpayne@68 758
jpayne@68 759 >>> from DateTime.interfaces import DateTimeError
jpayne@68 760 >>> try:
jpayne@68 761 ... dt + dt
jpayne@68 762 ... print('fail')
jpayne@68 763 ... except DateTimeError:
jpayne@68 764 ... print('ok')
jpayne@68 765 ok
jpayne@68 766
jpayne@68 767 Either a DateTime or a number may be subtracted from a DateTime,
jpayne@68 768 however, a DateTime may not be subtracted from a number:
jpayne@68 769
jpayne@68 770 >>> DateTime('1997/03/10 13:45 US/Eastern') - dt
jpayne@68 771 1.0
jpayne@68 772 >>> dt - 1
jpayne@68 773 DateTime('1997/03/08 13:45:00 US/Eastern')
jpayne@68 774 >>> 1 - dt
jpayne@68 775 Traceback (most recent call last):
jpayne@68 776 ...
jpayne@68 777 TypeError: unsupported operand type(s) for -: 'int' and 'DateTime'
jpayne@68 778
jpayne@68 779 DateTimes can also be converted to integers (number of seconds since
jpayne@68 780 the epoch) and floats:
jpayne@68 781
jpayne@68 782 >>> int(dt)
jpayne@68 783 857933100
jpayne@68 784 >>> float(dt)
jpayne@68 785 857933100.0