Parse strings to objects of datetime.
This module intends to make string-parsing to datetime-objects as easy as possible while allowing a fine configuration about which kind of formats are supported:
Parsing any kind of string is as easy as:
>>> date = parsedate('3 Jan 2013')
datetime.date(2013, 1, 3)
Now suppose you don’t want to allow parsing strings with literal month-names:
>>> DateFormats.config(allow_month_name=False)
>>> date = parsedate('3 Jan 2013')
ValueError: couldn't parse '3 Jan 2013' as date
Most of the time you will use format-classes only to alter their configuration. The parser-functions (except parsetimedelta()) use the format-classes to recieve a list of format-strings and try to parse the string with them using datetime.datetime.strptime().
parsetimedelta() breaks with that concept. It don’t need format-strings at all and has his own logic.
To create a list with an altered configuration you can either pass keyword- arguments to the constructor:
>>> formats = TimeFormats(seps=['-', ':', ';'], allow_microsec=True)
or change the default-configuration on class-level:
>>> TimeFormats.config(seps=['-', ':', ';'], allow_microsec=True)
>>> formats = TimeFormats()
Both will result in the same list of formats, but the former way doesn’t touch the default-configuration.
If you just call the constructor the format-class will produce a list of all formats for the actual configuration:
>>> formats = DateFormats()
>>> len(formats)
77
But if you look for formats for a specific string you can pass the string to the constructor:
>>> DateFormats('3 Jan 2013')
['%d %b %Y']
That is what the parser-functions do to minimize the amount of formats they have to try to parse the string with.
Producing formats for a specific string also respects the current setting:
>>> set(DateFormats('3 Jan 2013')) < set(DateFormats())
True
>>> DateFormats.config(allow_month_name=False)
>>> DateFormats('3 jan 2013')
ValueError: no proper format for '3 jan 2013'
Parse a string to a datetime.time -object.
| Parameters: | |
|---|---|
| Return type: | |
| Raises : | ValueError, if string couldn’t been parsed |
The string is tried to be parsed with every format of formats. If formats not given TimeFormats(string) is used.
Parse a string to a datetime.date-object.
| Parameters: |
|
|---|---|
| Return type: | |
| Raises : | ValueError, if string couldn’t been parsed |
string is tried to be parsed with every format of formats. If formats not given DateFormats(string) is used.
If string is parsed with an incomplete format (missing year or year and month), the date will be completed by today or timeparser.TODAY.
Parse a string to a datetime.datetime-object.
| Parameters: |
|
|---|---|
| Return type: | |
| Raises : | ValueError, if string couldn’t been parsed |
string is tried to be parsed with every format of formats. If formats not given DatetimeFormats(string) is used.
If string is parsed with an incomplete format (missing year or year and month), the date will be completed by today or timeparser.TODAY.
Parse a string to a datetime.timedelta-object.
| Parameters: | |
|---|---|
| Return type: | |
| Raises : | ValueError, if string couldn’t been parsed |
parsetimedelta looks for digits in string, that could be seperated. These digits will be the arguments for datetime.timedelta. Thereby key is used to determine the unit of the first argument, which could be one of the keywords for datetime.timedelta (‘weeks’, ‘days’, ‘hours’, ‘minutes’, ‘seconds’). The following arguments get each the next lesser unit:
>>> parsetimedelta('1, 2, 3', 'h') == datetime.timedelta(hours=1, minutes=2, seconds=3)
True
Another way is to just place keyword-matching literals within the string:
>>> parsetimedelta('1h 2m 3s') == datetime.timedelta(hours=1, minutes=2, seconds=3)
True
A list of time-string-formats that generates himself.
| Parameters: | |
|---|---|
| Raises : | ValueError if no format could be produced for string. |
A list of separators, formats are produced with.
Allows formats without any separator (‘%H%M%S’).
List of four booleans that predicts how many digits formats are allowed to have:
A list of date-string-formats that generates himself.
| Parameters: |
|
|---|---|
| Raises : | ValueError if no format could be produced for string. |
A list of separators, formats are produced with.
Allows formats without any separator (‘%d%m%y’).
List of three booleans that predicts how many digits formats are allowed to have:
Modify class-configuration.
| Parameters: |
|
|---|
A list of datetime-string-formats that generates himself.
| Parameters: |
|
|---|---|
| Raises : | ValueError if no format could be produced for string. |
A list of separators, formats are produced with.
Allows formats without any separator (‘%H%M%S’).
Modify class-configuration.
| Parameters: |
|
|---|
ENDIAN is an instance of Endian and defines the order that should be applied:
>>> ENDIAN
('day', 'month', 'year')
>>> parsedate('26/4/13')
datetime.date(2013, 4, 26)
On creation a local-default-order is guessed, but could be changed through Endian.set():
>>> ENDIAN.set('big')
>>> ENDIAN
('year', 'month', 'day')
>>> parsedate('26/4/13')
datetime.date(2026, 4, 13)
Warning
Guessing the local default is in a provisional state and a middle-endian- order is not regarded at all.
Endian emulates a tuple, which represents the order of a date.
Dates can be ordered in three different ways:
- little-endian: ('day', 'month', 'year')
- big-endian: ('year', 'month', 'day')
- middle-endian: ('month', 'day', 'year')
On creation a local default-order is guessed (either little- or big-endian). To change it use set().
Set ENDIAN to little-, big- or middle-endian.
| Parameters: | key (str or None) – A string matching ‘little’, ‘big’ or ‘middle’. |
|---|
If key is None the local-default-order is guessed.
TODAY is an instance of Today and is used to complement dates that were parsed with an incomplete format-string:
>>> TODAY
TODAY(2013, 5, 9)
>>> parsedate('20 Apr')
datetime.date(2013, 4, 20)
or even:
>>> TODAY
TODAY(2013, 5, 9)
>>> parsedate('20')
datetime.date(2013, 5, 20)
TODAY defaults to datetime.date.today(), but can be changed through Today.set():
>>> TODAY.set(2000, 1, 1)
>>> parsedate('20')
datetime.date(2000, 1, 20)
Today emulates a datetime.date-object that could be changed through set().
On creation Today will be set to datetime.date.today().
Because datetime.date-objects are not mutable (but Today-instance has to be), Today imitates a datetime.date just saving one as Today.dateobj and let Today.year, Today.month and Today.day returning its values.