hdx.utilities.dateparse

module hdx.utilities.dateparse

Date parsing utilities.

Classes

DateParser

Functions

get_tzinfos — Get tzinfos dictionary used by dateutil from timezone information string.
parse — Parse the date/time string into a :class:datetime.datetime object.
now_utc — Return now with UTC timezone.
now_utc_notz — Return now in UTC but with timezone removed.
parse_date_range — Parse date from string using specified date_format if given and return datetime date range in dictionary keys startdate and enddate. If no date_format is supplied, the function will guess, which for unambiguous formats, should work fine.
parse_date — Parse date from string using specified date_format and return a datetime object. Raises exception for dates that are missing year, month or day. If no date_format is supplied, the function will guess, which for unambiguous formats, should work fine.
get_timestamp_from_datetime — Convert datetime to timestamp.
get_datetime_from_timestamp — Convert timestamp to datetime.
iso_string_from_datetime — Convert datetime to ISO formatted date without any time elements
get_quarter — Get the quarter of the given date
get_quarter_start — Get the first day of the quarter in which a given date is contained
get_quarter_end — Get the last day of the quarter in which a given date is contained

get_tzinfos(timezone_info: str) → dict[str, int]

Get tzinfos dictionary used by dateutil from timezone information string.

Parameters

timezone_info : str — Timezones information string

Returns

dict[str, int] — tzinfos dictionary

class DateParser(info=None)

Bases : dateutil.parser.parser

parse(timestr, default=None, ignoretz=False, tzinfos=None, **kwargs)

Parse the date/time string into a :class:datetime.datetime object.

:param timestr: Any date/time string using the supported formats.

:param default: The default datetime object, if this is a datetime object and not None, elements specified in timestr replace elements in the default object.

:param ignoretz: If set True, time zones in parsed strings are ignored and a naive :class:datetime.datetime object is returned.

:param tzinfos: Additional time zone names / aliases which may be present in the string. This argument maps time zone names (and optionally offsets from those time zones) to time zones. This parameter can be a dictionary with timezone aliases mapping time zone names to time zones or a function taking two parameters (tzname and tzoffset) and returning a time zone.

The timezones to which the names are mapped can be an integer
offset from UTC in seconds or a :class:`tzinfo` object.

.. doctest::
   :options: +NORMALIZE_WHITESPACE

    ```{.python .mkapi-example-input}
    from dateutil.parser import parse
    from dateutil.tz import gettz
    tzinfos = {"BRST": -7200, "CST": gettz("America/Chicago")}
    parse("2012-01-19 17:21:00 BRST", tzinfos=tzinfos)
    ```

    ```{.text .mkapi-example-output}
    datetime.datetime(2012, 1, 19, 17, 21, tzinfo=tzoffset(u'BRST', -7200))
    ```

    ```{.python .mkapi-example-input}
    parse("2012-01-19 17:21:00 CST", tzinfos=tzinfos)
    ```

    ```{.text .mkapi-example-output}
    datetime.datetime(2012, 1, 19, 17, 21,
                      tzinfo=tzfile('/usr/share/zoneinfo/America/Chicago'))
    ```

This parameter is ignored if ``ignoretz`` is set.

:param **kwargs: Keyword arguments as passed to _parse().

:return: Returns a :class:datetime.datetime object or, if the fuzzy_with_tokens option is True, returns a tuple, the first element being a :class:datetime.datetime object, the second a tuple containing the fuzzy tokens.

:raises ParserError: Raised for invalid or unknown string format, if the provided :class:tzinfo is not in a valid format, or if an invalid date would be created.

:raises TypeError: Raised for non-string or character stream input.

:raises OverflowError: Raised if the parsed date exceeds the largest valid C integer on your system.

Raises

ParserError

now_utc() → datetime

Return now with UTC timezone.

Returns

datetime — Now with UTC timezone

now_utc_notz() → datetime

Return now in UTC but with timezone removed.

Returns

datetime — Now in UTC but with timezone removed

parse_date_range(string: str, date_format: str | None = None, timezone_handling: int = 0, fuzzy: dict | None = None, include_microseconds: bool = False, zero_time: bool = False, max_starttime: bool = False, max_endtime: bool = False, default_timezones: str | None = None) → tuple[datetime, datetime]

Parse date from string using specified date_format if given and return datetime date range in dictionary keys startdate and enddate. If no date_format is supplied, the function will guess, which for unambiguous formats, should work fine.

By default, no timezone information will be parsed and the returned datetime will have timezone UTC. To change this behaviour, timezone_handling should be changed from its default of 0. If it is 1, then no timezone information will be parsed and a naive datetime will be returned. If it is 2 or more, then timezone information will be parsed. For 2, failure to parse timezone will result in a naive datetime. For 3, failure to parse timezone will result in the timezone being set to UTC. For 4 and 5, the time will be converted from whatever timezone is identified to UTC. For 4, failure to parse timezone will result in a naive (local) datetime converted to UTC. For 5, failure to parse timezone will result in the timezone being set to UTC.

To parse a date within a string containing other text, you can supply a dictionary in the fuzzy parameter. In this case, dateutil's fuzzy parsing is used and the results returned in the dictionary in keys startdate, enddate, date (the string elements used to make the date) and nondate (the non date part of the string).

By default, microseconds are ignored (set to 0), but can be included by setting include_microseconds to True. Any time elements are set to 0 if zero_time is True. If max_starttime is True, then the start date's time is set to 23:59:59. If max_endtime is True, then the end date's time is set to 23:59:59.

When inferring time zones, a default set of time zones will be used unless overridden by passing in default_timezones which is a string of the form:

-11 X NUT SST
-10 W CKT HAST HST TAHT TKT

Parameters

string : str — Dataset date string
date_format : str | None — Date format. If None is given, will attempt to guess. Defaults to None.
timezone_handling : int — Timezone handling. See description. Defaults to 0 (ignore timezone, return UTC).
fuzzy : dict | None — If dict supplied, fuzzy matching will be used and results returned in dict
include_microseconds : bool — Includes microseconds if True. Defaults to False.
zero_time : bool — Zero time elements of datetime if True. Defaults to False.
max_starttime : bool — Make start date time component 23:59:59:999999. Defaults to False.
max_endtime : bool — Make end date time component 23:59:59:999999. Defaults to False.
default_timezones : str | None — Timezone information. Defaults to None. (Internal default).

Returns

tuple[datetime, datetime] — Tuple containing start date and end date

Raises

ParserError

parse_date(string: str, date_format: str | None = None, timezone_handling: int = 0, fuzzy: dict | None = None, include_microseconds: bool = False, zero_time: bool = False, max_time: bool = False, default_timezones: str | None = None) → datetime

Parse date from string using specified date_format and return a datetime object. Raises exception for dates that are missing year, month or day. If no date_format is supplied, the function will guess, which for unambiguous formats, should work fine.

By default, no timezone information will be parsed and the returned datetime will have timezone UTC. To change this behaviour, timezone_handling should be changed from its default of 0. If it is 1, then no timezone information will be parsed and a naive datetime will be returned. If it is 2 or more, then timezone information will be parsed. For 2, failure to parse timezone will result in a naive datetime. For 3, failure to parse timezone will result in the timezone being set to UTC. For 4 and 5, the time will be converted from whatever timezone is identified to UTC. For 4, failure to parse timezone will result in a naive (local) datetime converted to UTC. For 5, failure to parse timezone will result in the timezone being set to UTC.

To parse a date within a string containing other text, you can supply a dictionary in the fuzzy parameter. In this case, dateutil's fuzzy parsing is used and the results returned in the dictionary in keys startdate, enddate, date (the string elements used to make the date) and nondate (the non date part of the string).

By default, microseconds are ignored (set to 0), but can be included by setting include_microseconds to True. Any time elements are set to 0 if zero_time is True. If max_starttime is True, then the start date's time is set to 23:59:59. If max_endtime is True, then the end date's time is set to 23:59:59.

When inferring time zones, a default set of time zones will be used unless overridden by passing in default_timezones which is a string of the form:

-11 X NUT SST
-10 W CKT HAST HST TAHT TKT

Parameters

string : str — Dataset date string
date_format : str | None — Date format. If None is given, will attempt to guess. Defaults to None.
timezone_handling : int — Timezone handling. See description. Defaults to 0 (ignore timezone, return UTC).
fuzzy : dict | None — If dict supplied, fuzzy matching will be used and results returned in dict
include_microseconds : bool — Includes microseconds if True. Defaults to False.
zero_time : bool — Zero time elements of datetime if True. Defaults to False.
max_time : bool — Make date time component 23:59:59:999999. Defaults to False.
default_timezones : str | None — Timezone information. Defaults to None. (Internal default).

Returns

datetime — The parsed date

Raises

ParserError

get_timestamp_from_datetime(date: datetime) → float

Convert datetime to timestamp.

Parameters

date : datetime — Date to convert

Returns

float — Timestamp

get_datetime_from_timestamp(timestamp: float, timezone: datetime.tzinfo = timezone.utc, today: datetime = now_utc()) → datetime

Convert timestamp to datetime.

Parameters

timestamp : float — Timestamp to convert
timezone : datetime.tzinfo — Timezone to use
today : datetime — Today's date. Defaults to now_utc.

Returns

datetime — Date of timestamp

iso_string_from_datetime(date: datetime) → str

Convert datetime to ISO formatted date without any time elements

Parameters

date : datetime — Date to convert to string

Returns

str — ISO formatted date without any time elements

get_quarter(date: datetime) → int

Get the quarter of the given date

Parameters

date : datetime — Date

Returns

int — Quarter in which the given date is contained

get_quarter_start(year: int, quarter: int) → datetime

Get the first day of the quarter in which a given date is contained

Parameters

year : int — Year
quarter : int — Quarter

Returns

datetime — First day of quarter

get_quarter_end(year: int, quarter: int, max_time: bool = True, include_microseconds: bool = False)

Get the last day of the quarter in which a given date is contained

Parameters

year : int — Year
quarter : int — Quarter
max_time : bool — Make date time component 23:59:59:999999. Defaults to True.
include_microseconds : bool — Includes microseconds if True. Defaults to False.

Returns

First day of quarter