third_party/pyiso8601/README.rst

   1 Simple module to parse ISO 8601 dates
   2
   3 This module parses the most common forms of ISO 8601 date strings (e.g.
   4 2007-01-14T20:34:22+00:00) into datetime objects.
   5
   6 >>> import iso8601
   7 >>> iso8601.parse_date("2007-01-25T12:00:00Z")
   8 datetime.datetime(2007, 1, 25, 12, 0, tzinfo=<iso8601.Utc>)
   9 >>>
  10
  11 See the LICENSE file for the license this package is released under.
  12
  13 If you want more full featured parsing look at:
  14
  15 - http://labix.org/python-dateutil - python-dateutil
  16
  17 Parsed Formats
  18 ==============
  19
  20 You can parse full date + times, or just the date. In both cases a datetime instance is returned but with missing times defaulting to 0, and missing days / months defaulting to 1.
  21
  22 Dates
  23 -----
  24
  25 - YYYY-MM-DD
  26 - YYYYMMDD
  27 - YYYY-MM (defaults to 1 for the day)
  28 - YYYY (defaults to 1 for month and day)
  29
  30 Times
  31 -----
  32
  33 - hh:mm:ss.nn
  34 - hhmmss.nn
  35 - hh:mm (defaults to 0 for seconds)
  36 - hhmm (defaults to 0 for seconds)
  37 - hh (defaults to 0 for minutes and seconds)
  38
  39 Time Zones
  40 ----------
  41
  42 - Nothing, will use the default timezone given (which in turn defaults to UTC).
  43 - Z (UTC)
  44 - +/-hh:mm
  45 - +/-hhmm
  46 - +/-hh
  47
  48 Where it Differs From ISO 8601
  49 ==============================
  50
  51 Known differences from the ISO 8601 spec:
  52
  53 - You can use a " " (space) instead of T for separating date from time.
  54 - Days and months without a leading 0 (2 vs 02) will be parsed.
  55 - If time zone information is omitted the default time zone given is used (which in turn defaults to UTC). Use a default of None to yield naive datetime instances.
  56
  57 Homepage
  58 ========
  59
  60 - Documentation: http://pyiso8601.readthedocs.org/
  61 - Source: https://bitbucket.org/micktwomey/pyiso8601/
  62
  63 This was originally hosted at https://code.google.com/p/pyiso8601/
  64
  65 References
  66 ==========
  67
  68 - http://en.wikipedia.org/wiki/ISO_8601
  69
  70 - http://www.cl.cam.ac.uk/~mgk25/iso-time.html - simple overview
  71
  72 - http://hydracen.com/dx/iso8601.htm - more detailed enumeration of valid formats.
  73
  74 Testing
  75 =======
  76
  77 1. pip install -r dev-requirements.txt
  78 2. tox
  79
  80 Note that you need all the pythons installed to perform a tox run (see below). Homebrew helps a lot on the mac, however you wind up having to add cellars to your PATH or symlinking the pythonX.Y executables.
  81
  82 Alternatively, to test only with your current python:
  83
  84 1. pip install -r dev-requirements.txt
  85 2. py.test --verbose iso8601
  86
  87 Supported Python Versions
  88 =========================
  89
  90 Tested against:
  91
  92 - Python 2.6
  93 - Python 2.7
  94 - Python 3.2
  95 - Python 3.3
  96 - Python 3.4
  97 - PyPy
  98
  99 Python 3.0 and 3.1 are untested but should work (tests didn't run under them when last tried).
 100
 101 Jython is untested but should work (tests failed to run).
 102
 103 Python 2.5 is not supported (too old for the tests for the most part). It could work with some small changes but I'm not supporting it.
 104
 105 Changes
 106 =======
 107
 108 0.1.11
 109 ------
 110
 111 * Add Python 3.4 to tox test config.
 112 * Add PyPy 3 to tox test config.
 113 * Link to documentation at http://pyiso8601.readthedocs.org/
 114
 115
 116 0.1.10
 117 ------
 118
 119 * Fixes https://bitbucket.org/micktwomey/pyiso8601/issue/14/regression-yyyy-mm-no-longer-parses (thanks to Kevin Gill for reporting)
 120 * Adds YYYY as a valid date (uses 1 for both month and day)
 121 * Woo, semantic versioning, .10 at last.
 122
 123 0.1.9
 124 -----
 125
 126 * Lots of fixes tightening up parsing from jdanjou. In particular more invalid cases are treated as errors. Also includes fixes for tests (which is how these invalid cases got in in the first place).
 127 * Release addresses https://bitbucket.org/micktwomey/pyiso8601/issue/13/new-release-based-on-critical-bug-fix
 128
 129 0.1.8
 130 -----
 131
 132 * Remove +/- chars from README.rst and ensure tox tests run using LC_ALL=C. The setup.py egg_info command was failing in python 3.* on some setups (basically any where the system encoding wasn't UTF-8). (https://bitbucket.org/micktwomey/pyiso8601/issue/10/setuppy-broken-for-python-33) (thanks to klmitch)
 133
 134 0.1.7
 135 -----
 136
 137 * Fix parsing of microseconds (https://bitbucket.org/micktwomey/pyiso8601/issue/9/regression-parsing-microseconds) (Thanks to dims and bnemec)
 138
 139 0.1.6
 140 -----
 141
 142 * Correct negative timezone offsets (https://bitbucket.org/micktwomey/pyiso8601/issue/8/015-parses-negative-timezones-incorrectly) (thanks to Jonathan Lange)
 143
 144 0.1.5
 145 -----
 146
 147 * Wow, it's alive! First update since 2007
 148 * Moved over to https://bitbucket.org/micktwomey/pyiso8601
 149 * Add support for python 3. https://code.google.com/p/pyiso8601/issues/detail?id=23 (thanks to zefciu)
 150 * Switched to py.test and tox for testing
 151 * Make seconds optional in date format ("1997-07-16T19:20+01:00" now valid). https://bitbucket.org/micktwomey/pyiso8601/pull-request/1/make-the-inclusion-of-seconds-optional-in/diff (thanks to Chris Down)
 152 * Correctly raise ParseError for more invalid inputs (https://bitbucket.org/micktwomey/pyiso8601/issue/1/raise-parseerror-for-invalid-input) (thanks to manish.tomar)
 153 * Support more variations of ISO 8601 dates, times and time zone specs.
 154 * Fix microsecond rounding issues (https://bitbucket.org/micktwomey/pyiso8601/issue/2/roundoff-issues-when-parsing-decimal) (thanks to nielsenb@jetfuse.net)
 155 * Fix pickling and deepcopy of returned datetime objects (https://bitbucket.org/micktwomey/pyiso8601/issue/3/dates-returned-by-parse_date-do-not) (thanks to fogathmann and john@openlearning.com)
 156 * Fix timezone offsets without a separator (https://bitbucket.org/micktwomey/pyiso8601/issue/4/support-offsets-without-a-separator) (thanks to joe.walton.gglcd)
 157 * "Z" produces default timezone if one is specified (https://bitbucket.org/micktwomey/pyiso8601/issue/5/z-produces-default-timezone-if-one-is) (thanks to vfaronov). This one may cause problems if you've been relying on default_timezone to use that timezone instead of UTC. Strictly speaking that was wrong but this is potentially backwards incompatible.
 158 * Handle compact date format (https://bitbucket.org/micktwomey/pyiso8601/issue/6/handle-compact-date-format) (thanks to rvandolson@esri.com)
 159
 160 0.1.4
 161 -----
 162
 163 * The default_timezone argument wasn't being passed through correctly, UTC was being used in every case. Fixes issue 10.
 164
 165 0.1.3
 166 -----
 167
 168 * Fixed the microsecond handling, the generated microsecond values were way too small. Fixes issue 9.
 169
 170 0.1.2
 171 -----
 172
 173 * Adding ParseError to __all__ in iso8601 module, allows people to import it. Addresses issue 7.
 174 * Be a little more flexible when dealing with dates without leading zeroes. This violates the spec a little, but handles more dates as seen in the field. Addresses issue 6.
 175 * Allow date/time separators other than T.
 176
 177 0.1.1
 178 -----
 179
 180 * When parsing dates without a timezone the specified default is used. If no default is specified then UTC is used. Addresses issue 4.