IsoDate class

class dt8601.IsoDate(year, month=1, day=1, country='DE', state=None)

add_days(number_of_days)

add a number of days and return a new instance of IsoDate (days may be negative)

add_workdays(number_of_days)

add a number of work day and return a new instance of IsoDate (days must be positive)

classmethod date_string(year, month, day, isoformat='YYYY-MM-DD', separator='-')

return a formatted string in ISO8601 syntax

Parameters:

• year – four-digit year
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH
• isoformat – string with ISO8601 date format
• separator – separator for elements, defaults to ‘-‘ according to ISO8601 long form

Returns:

string according to the isoformat

day_of_week()

return the day of the week as number from 1..7 (ISO) or as string when using fmt=’string’

day_of_week_name(mode='EN')

return the weekday name

depending on mode, the method return ‘MO’..’SU’ for mode ‘en’ or ‘Mon’...’Sun’ for mode ‘short’ or ‘Monday’...’Sunday’ for mode ‘long’ and the language will be detemrined by the country attribute of the IsoDate instance currently ‘DE’, ‘IT’, ‘AT’, ‘US’ :param mode: ‘en’ | ‘short’ | ‘long’ :return: weekday as string

day_of_year()

return day of the year

day_type()

type of day

Returns:‘workday’ | ‘holiday’ | ‘weekend’

days_since(start_date)

days since a second IsoDate instance

days_until(target_date)

days until a second IsoDate instance

classmethod from_iso_string(iso_string, country='DE', state=None, separator='T')

initialize an IsoDate instance from an ISO string

Parameters:

• iso_string – ISO8601 compliant string (may include time part)
• country – country to use as locale for the IsoDate
• state – state to use as locale for the IsoDate

Returns:

IsoDate instance according to data from the ISO string

Raise :

ValueError if any of the elements have invalid values

iso_string(isoformat, separator='-')

return a formatted string in ISO8601 syntax

Returns:ISO8601 long form (with separators) string according to the isoformat

julian_date()

return the corresponding julian date for the IsoDate instance

Returns:number with the julian date

classmethod parse_iso_string(iso_string, separator='T')

parse an ISO8601 string and return a dictionary with the results

Parameters:

• iso_string – ISO8601 compliant string (may include time part)
• separator – default to ‘T’ as set forth in ISO8601, use ‘ ‘ for some applications

Returns:

a dictionary with the parsing results

project(days=None, hoursperday=8, workhours=8, workdaysonly=True)

try to mimic a very simple time estimation model

Parameters:

• days – number of days of effort
• hoursperday – number of hours per workday to use for the projection
• workhours – number of working hours per day (should be less than 24 <g>)
• workdaysonly – use only workdays for the projection

Returns:

a new IsoDate instance with the calculated end date

replace(year=None, month=None, day=None)

replace certain parts of the date and return a new IsoDate instance

week_of_year()

determine the week of the year

Returns:iso calendar week (1..52 or 53 for leap years)

IsoYear class

class dt8601.IsoYear(year=None, country='DE', state=None)

easter

helper property to get the date tuple (year, month, day) for easter sunday

Returns:date tuple for easter sunday

get_month_name(the_month, mode='short')

just a helper method to get the month name according to the country attribute of the IsoYear instance :param the_month: the month from 1..12 :param mode: ‘short’ | ‘long’ :return: string with the month name

holidays

return the list of holidays for the year

Returns:list of holiday entries

is_holiday(month, day)

check if a given day in a given month is a holiday or a weekend day :param month: integer from 1..12 for the month :param day: integer from 1..DAYS_IN_MONTH for the day :return: True if the day is a holiday

iso_weeks

get the list of all iso calendar weeks for the year

this property yields the list of calendar weeks (ISO weeks starting with a monday (weekday number 1) for the year. Each entry is a dictionary with the key ‘no’ holing the week no, the key ‘start’ containing a tuple of (year, month, day). As ISO weeks starts on a monday, the weekday of every date is always a monday.

Returns:array of 52 or 52 tuples

leap_year

check if a year is a leap year

Returns:boolean True or False

primo(month)

returns the primo (first workday of the month) for a given month :param month: the month from 1..12 :return: a new instance of IsoDate with the primo for the month

ultimo(month)

returns the ultimo (last workday of the month) for a given month :param month: the month from 1..12 :return: a new instance of IsoDate with the ultimo for the month

week_count

return the number of weeks for this year

Returns:integer 52 or 53

workdays_in_month(month)

return the number of working days in the given month :param month: integer 1..12 :return: int with the number of workdays

datecore

dt8601.datecore

This module provides utility functions that are also useful for external consumption.

dt8601.datecore.add_days(year, month, day, days_to_add)

add days to a date, days_to_add can be negative also :param year: four-digit year :param month: month form 1..12 :param day: day from 1..DAYS_IN_MONTH :param days_to_add: integer days to add :returns: ymd tuple

dt8601.datecore.calc_holidays(year, country='DE', state=None)

calculate the list of holidays for a year in a location

Parameters:

• year – four-digit year
• country – ISO2 country code
• state – state code (see definitions module)

Returns:

list of holiday tuples (name, date tuple)

dt8601.datecore.calculate_base_date(year, the_base)

calculate the base date for a variable holiday

Parameters:

• year – four-digit year
• the_base – string with base: EASTER|ADVENT|JAN...DEC

Returns:

ymd tuple

dt8601.datecore.day_of_week(year, month, day, fmt='string')

calculate the day of the week

day_of_week either returns a number from 1..7 or a string from MO..SU depending on the fmt keyword parameter (numbering according to ISO8601)

Parameters:

• year – four-digit year
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH
• fmt – ‘number’ for 1..7 or ‘string’ for ‘MO’..’SU’

Returns:

weekday as integer or string

dt8601.datecore.day_of_year(year, month, day)

calculate the day number within a year (1..365/366)

Parameters:

• year – four-digit year
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH

dt8601.datecore.days_in_month(year, month)

calculate the number of days in a given month

Parameters:

• year – four digit year
• month – month from 1..12

Returns:

integer with days in month

dt8601.datecore.days_in_year(year)

helper method to get the number of days in a year

Parameters:year – four digit year Returns:365 or 366

dt8601.datecore.doy_to_ymd(year, dayofyear)

convert day within a given year to a ymd tuple

Parameters:

• dayofyear – 1..365/366
• year – four-digit year

Returns:

ymd tuple

dt8601.datecore.easter_schlyter(year)

calculate schöyter easter sunday day number

Parameters:year – the four digit year

dt8601.datecore.easter_sunday(year)

calculate easter sunday for a given year

Parameters:year – four-digit year Returns:ymd tuple for easter sunday

dt8601.datecore.get_month_name(month, country='DE', mode='short')

retrieve name of the month in various formats

Parameters:

• month – month from 1..12
• country – ISO2 code for country language
• mode – string with ‘short’ or ‘long’ (see definitions module)

Returns:

string with the month name

dt8601.datecore.gregorian_to_julian(year, month, day)

convert ymd tuple to julian day number

Parameters:

• year – four digit year from MINYEAR..MAXYEAR
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH

dt8601.datecore.is_leap_year(year)

check if year is a leap year

Parameters:year – four digit year Returns:True or False

dt8601.datecore.is_valid_time(hours, minutes, seconds)

check if a time is valid (within 00:00:00 to 24:00:00)

Parameters:

• hours – hour from 00..24 (yes, 24 is valid for 24:00:00)
• minutes – minutes form 00..59
• seconds – seconds from 00..60 (yes, lap seconds!)

dt8601.datecore.iso8601_date_parser(input_string)

parse an ISO8601 date string :param input_string: ISO8601 date string :returns: dictionary with parsing results

dt8601.datecore.iso8601_date_string(year, month, day, isoformat='YYYY-MM-DD', separator='-')

return a formatted string in ISO8601 syntax

Returns:ISO8601 long form (with separators) string according to the isoformat

dt8601.datecore.iso8601_parser(input_string, separator='T')

main wrapper method for the ISO8601 date/time parser

Parameters:

• input_string – ISO8601 date/time string
• separator – defaults to ‘T’ according to ISO8601

Returns:

dictionary with the parsing results

dt8601.datecore.iso8601_splitter(input_string, separator='T')

split an ISO8601 date/time string in date, time, tz parts

basic logic: - if it has a ‘T’ in it, it is a date and time input - if it has [‘Z’, ‘z’, ‘+’, ‘-‘] in it, it has a timezone information

Parameters:

• input_string – ISO8601 string
• separator – default to ‘T’ according to ISO8601

Returns:

tuple with datepart, timepart, tzpart

dt8601.datecore.iso8601_time_parser(input_string)

parse an ISO8601 time string

Parameters:input_string – ISO8601 time string Returns:dictionary with parsing results

dt8601.datecore.iso8601_timezone_parser(input_string)

parse ISO8601 time zone information

time zone info is ‘Z’ or (+|-)hh[[:]mm] time zone is checked against a list of valid time zones (see definitions module) :param input_string: ISO8601 timezone string :returns: dictionary with parsing results

dt8601.datecore.julian_to_gregorian(julian_number)

convert julian date number to ymd tuple :param julian_number: the julian date to convert

dt8601.datecore.julian_to_mjd(julian_number)

convert julian date to modified julian date

dt8601.datecore.load_year(year, country='DE', state=None)

load the day list (weekend, holiday or normal day) for a given year and a given location

Parameters:

• year – four-digit year
• country – ISO2 code for the coutry
• state – state code (see definitions module)

Returns:

list of day entries for every day of the year (‘’|’W’|’H’)

dt8601.datecore.mjd_to_julian(mjd_number)

convert modified julian date to julian date

dt8601.datecore.parse_fixed_holiday(year, holiday_definition)

parse a fixed holiday that always occurs on the same month and day

Parameters:

• year – four-digit year
• holiday_definition – string with the holiday definition

Returns:

tuple with date(s) of the holiday

dt8601.datecore.parse_holiday(year, holiday_definition)

parse a holiday definition and return the date

Parameters:

• year – four-digit year
• holiday_definition – a string with a holidays definition

dt8601.datecore.parse_variable_holiday(year, holiday_definition)

parse a variable holiday

Parameters:

• year – four-digit year
• holiday_definition – string with definition for a variable holiday

Returns:

tuple with date(s) of the holiday

dt8601.datecore.week_day_name(year, month, day, country='DE', mode='EN')

retrieve name of the week day in various formats

Parameters:

• year – four-digit year
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH
• country – ISO2 code for country language
• mode – string with ‘en’ or ‘short’ or ‘long’ (see definitions module)

Returns:

string with the month name

dt8601.datecore.week_of_year(year, month, day)

calculate the ISO week number (1..53) for a given date

Parameters:

• year – four-digit year
• month – month from 1..12
• day – day from 1..DAYS_IN_MONTH

Returns:

integer ISO week number

dt8601.datecore.week_to_ymd(year, week)

calculate the beginning of a ISO week number

Parameters:

• year – four-digit year
• week – ISO week number 1..53

dt8601.datecore.weeks_in_year(year)

calculate the number of week in a given year :param year: four-digit year :returns: integer 1..53