`dates`

Utilities for working with dates and times.

Attention

This module has the following additional None:

pytz>=2019.1

This can be installed as follows:

python -m pip install domdf-python-tools[dates]

Data:

`months`	Mapping of 3-character shortcodes to full month names.
`month_full_names`	List of the full names for months in the Gregorian calendar.
`month_short_names`	List of the short names for months in the Gregorian calendar.

Functions:

`calc_easter`(year)	Returns the date of Easter in the given year.
`check_date`(month, day[, leap_year])	Returns `True` if the day number is valid for the given month.
`current_tzinfo`()	Returns a tzinfo object for the current timezone.
`get_month_number`(month)	Returns the number of the given month.
`get_timezone`(tz[, date])	Returns a localized `pytz.timezone` object for the given date.
`get_utc_offset`(tz[, date])	Returns the offset between UTC and the requested timezone on the given date.
`is_bst`(the_date)	Calculates whether the given day falls within British Summer Time.
`parse_month`(month)	Converts an integer or shorthand month into the full month name.
`set_timezone`(obj, tzinfo)	Sets the timezone / tzinfo of the given `datetime.datetime` object.
`utc_timestamp_to_datetime`(utc_timestamp[, ...])	Convert UTC timestamp (seconds from UNIX epoch) to a `datetime.datetime` object.

calc_easter(year)[source]

Returns the date of Easter in the given year.

New in version 1.4.0.

Parameters: year (int)
Return type: date

check_date(month, day, leap_year=True)[source]

Returns True if the day number is valid for the given month.

Note

This function will return True for the 29th Feb. If you don’t want this behaviour set leap_year to False.

Parameters

month (Union[str, int]) – The month to test.
day (int) – The day number to test.
leap_year (bool) – Whether to return True for 29th Feb. Default True.

Return type

bool

current_tzinfo()[source]

Returns a tzinfo object for the current timezone.

Return type: Optional[tzinfo]

get_month_number(month)[source]

Returns the number of the given month. If month is already a number between 1 and 12 it will be returned immediately.

Parameters: month (Union[str, int]) – The month to convert to a number
Return type: int
Returns: The number of the month

get_timezone(tz, date=None)[source]

Returns a localized pytz.timezone object for the given date.

If date is None then the current date is used.

Parameters

tz (str) – A string representing a pytz timezone
date (Optional[datetime]) – The date to obtain the timezone for. Default None.

Return type

Optional[tzinfo]

get_utc_offset(tz, date=None)[source]

Returns the offset between UTC and the requested timezone on the given date. If date is None then the current date is used.

Parameters

tz (Union[tzinfo, str]) – pytz.timezone or a string representing the timezone
date (Optional[datetime]) – The date to obtain the UTC offset for. Default None.

Return type

Optional[timedelta]

is_bst(the_date)[source]

Calculates whether the given day falls within British Summer Time.

This function should also be applicable to other timezones which change to summer time on the same date (e.g. Central European Summer Time).

Note

This function does not consider the time of day, and therefore does not handle the fact that the time changes at 1 AM GMT. It also does not account for historic deviations from the current norm.

New in version 3.5.0.

Parameters: the_date (Union[struct_time, date]) – A time.struct_time, datetime.date or datetime.datetime representing the target date.
Return type: bool
Returns: True if the date falls within British Summer Time, False otherwise.

parse_month(month)[source]

Converts an integer or shorthand month into the full month name.

Parameters: month (Union[str, int]) – The month number or shorthand name
Return type: str
Returns: The full name of the month

set_timezone(obj, tzinfo)[source]

Sets the timezone / tzinfo of the given datetime.datetime object. This will not convert the time (i.e. the hours will stay the same). Use datetime.datetime.astimezone() to accomplish that.

Parameters

obj (datetime)
tzinfo (tzinfo)

Return type

datetime

utc_timestamp_to_datetime(utc_timestamp, output_tz=None)[source]

Convert UTC timestamp (seconds from UNIX epoch) to a datetime.datetime object.

If output_tz is None the timestamp is converted to the platform’s local date and time, and the local timezone is inferred and set for the object.

If output_tz is not None, it must be an instance of a datetime.tzinfo subclass, and the timestamp is converted to output_tz’s time zone.

Parameters

utc_timestamp (Union[float, int]) – The timestamp to convert to a datetime object
output_tz (Optional[tzinfo]) – The timezone to output the datetime object for. If None it will be inferred. Default None.

Return type

datetime

Returns

The timestamp as a datetime object.

Raises

OverflowError – if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It’s common for this to be restricted to years in 1970 through 2038.

months

Type: OrderedDict[str, str]

Mapping of 3-character shortcodes to full month names.

Essentially:

months = {
    Jan="January",
    Feb="February",
    Mar="March",
    Apr="April",
    May="May",
    ...,
    Dec="December",
}

month_full_names = ('January', 'February', ..., 'December')

Type: tuple

List of the full names for months in the Gregorian calendar.

New in version 2.0.0.

month_short_names = ('Jan', 'Feb', 'Mar', ..., 'Dec')

Type: tuple

List of the short names for months in the Gregorian calendar.

New in version 2.0.0.

dates

`dates`