MxDateTime - Date/Time Library for Python

[Pages:63]mxDateTime

Date/Time Library for Python

Version 3.2

Copyright 1997-2000 by IKDS Marc-Andr? Lemburg, Langenfeld Copyright 2000-2013 by GmbH, Langenfeld

All rights reserved. No part of this work may be reproduced or used in a any form or by any means without written permission of the publisher.

All product names and logos are trademarks of their respective owners.

The product names "mxBeeBase", "mxCGIPython", "mxCounter", "mxCrypto", "mxDateTime", "mxHTMLTools", "mxIP", "mxLicenseManager", "mxLog", "mxNumber", "mxODBC", "mxODBC Connect", "mxODBC Zope DA", "mxObjectStore", "mxProxy", "mxQueue", "mxStack", "mxTextTools", "mxTidy", "mxTools", "mxUID", "mxURL", "mxXMLTools", "eGenix Application Server", "PythonHTML", "eGenix" and "" and corresponding logos are trademarks or registered trademarks of GmbH, Langenfeld

Printed in Germany.

Contents

Contents

1. Introduction .................................................................................................. 1

2. Design........................................................................................................... 2 2.1 Time Zones, Daylight Savings Time (DST) and Leap Seconds ................ 3 2.2 Calendars .............................................................................................. 3 2.3 Conversion from and to other formats................................................... 4 2.4 Rounding Errors and Roundtrip-Safety ................................................... 4 2.5 Immutability .......................................................................................... 4 2.6 UTC and GMT ....................................................................................... 5 2.7 Interaction with other Types .................................................................. 5 2.8 String formats........................................................................................ 5 2.9 Speed and Memory ............................................................................... 6 2.10 Background and Resource Information on the Web............................... 6

3. mx.DateTime.DateTime Object...................................................................... 7 3.1 DateTime Object Constructors .............................................................. 7 3.2 DateTime Object Methods .................................................................. 11 3.3 DateTime Object Attributes ................................................................. 14

4. mx.DateTime.DateTimeDelta Object ............................................................17 4.1 DateTimeDelta Object Constructors.................................................... 17 4.2 DateTimeDelta Object Methods .......................................................... 18 4.3 DateTimeDelta Object Attributes......................................................... 19

5. mx.DateTime.RelativeDateTime Object.........................................................21 5.1 RelativeDateTime Constructors ........................................................... 21 5.2 RelativeDateTime Object Methods ...................................................... 23 5.3 RelativeDateTime Object Attributes..................................................... 23

mxDateTime - Date/Time Library for Python

5.4 RelativeDateTime Object Usage........................................................... 23

6. mx.DateTime Functions ............................................................................... 26

7. mx.DateTime Constants............................................................................... 27

8. Date/Time Arithmetic................................................................................... 29 8.1 Notes:.................................................................................................. 33

9. mxDateTime Submodules ............................................................................ 34 9.1 mx.DateTime.ISO Submodule.............................................................. 34 9.1.1 Constructors & Functions .......................................................... 34 Notes......................................................................................... 36 9.1.2 ISO 8601 string formats and DateTime[Delta] instances ........... 36 9.2 mx.DateTime.ARPA Submodule ........................................................... 37 9.2.1 Constructors & Functions .......................................................... 37 Notes......................................................................................... 38 9.3 mx.DateTime.Feasts Submodule.......................................................... 38 9.3.1 Constructors & Functions .......................................................... 38 9.4 mx.DateTime.Parser Submodule.......................................................... 39 9.4.1 Constructors & Functions .......................................................... 40 9.5 mx.DateTime.NIST Submodule ............................................................ 42 9.5.1 Constructors & Functions .......................................................... 42 9.5.2 Constants .................................................................................. 44 9.5.3 Examples ................................................................................... 45

10. Examples of Use .......................................................................................... 46

11. mx.DateTime Python C-API.......................................................................... 47 11.1 Example ............................................................................................... 47 11.2 C API Import ........................................................................................ 47 11.3 C API Definition ................................................................................... 48 Binary Compatibility .................................................................. 51 Type Checking........................................................................... 51

12. mxDateTime Package Structure.................................................................... 52

Contents

13. Support ........................................................................................................53 14. Copyright & License .....................................................................................54

1. Introduction

1. Introduction

The mxDateTime package provides consistent way of transferring date and time data between Python and databases. Apart from handling dates before the Unix epoch (1.1.1970) they also correctly work with dates beyond the Unix time limit (currently with Unix time values being commonly encoded using 32bit integers, the limit is reached in 2038) and thus is Year 2000 and Year 2038 safe. The package provides three main data structures for working with date and time values. These are:

? DateTime for referring to absolute date/time values, ? DateTimeDelta for date/time spans and ? RelativeDateTime for representing variable date/time spans (these

are the TABs of date/time calculation) All object, functions and constants are available via the package namespace mx.DateTime.

1

mxDateTime - Date/Time Library for Python

2. Design

The primary absolute date/time type DateTime uses the following internal format: Absolute date

This is a C long defined as being the number of days in the Gregorian calendar since the day before January 1 in the year 1 (0001-01-01), the Gregorian Epoch, also known as the Epoch of the Common Era (CE), thus the Gregorian date 0001-01-01 corresponds to absolute date 1. Note that the Julian Epoch starts two days before the Gregorian one. Absolute time This is a C double defined as the number of seconds since midnight (0:00:00.00) of the day expressed by the above value. The Epoch used by the module is January 1st of the year 1 at midnight (0:00:00.00) in the Gregorian calendar. This date corresponds to absolute day 1 and absolute time 0. Dates before the Epoch are handled by extrapolating the calendars using negative years as basis (the year 1 BCE corresponds to the year 0, 2 BCE is represented as year -1 and so on). For the purpose of storing absolute time differences, the package provides a second type called DateTimeDelta. The internal representation for this type is seconds and stored in a signed C double. To handle relative time deltas a third object type is available: RelativeDateTime. This object is currently implemented in Python and may be used to store relative time deltas (see below for an exact description). It's main purpose is providing an intuitive way to calculate e.g. the "first of next month". Designing the types wasn't as easy as expected, since many criteria had to be taken into account. Here are some of them and their implementation:

2

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download