Dates API

This is the API reference for all functions designed to be used on dates. You can find usage examples here.

hh.reverse_date

reverse_date(input_date: date, errors: str = 'raise') -> date

Sometimes dates are incorrectly formatted by Excel such that the day and month is swapped around. This can create errors when reading the data into pandas DataFrames. This function can be used to create a 'reversed' date where the day and month are swapped around. If this creates a date which doesn't exist, the original date is returned.

Parameters:

Name	Type	Description	Default
`input_date`	`date`	The date you wish to 'reverse' (swap day and month).	required
`errors`	`str`	Defaults to 'raise' which raises errors. 'ignore' ignores errors and returns original date.	`'raise'`

Raises:

Type	Description
`TypeError`	Raised if input_date is not in the date format (or pandas datetime format.)

Returns:

Name	Type	Description
`date`	`date`	Reversed date or original date if reversed date does not exist.

hh.calculate_dob_range_from_year_group

calculate_dob_range_from_year_group(
    year_group: str | int | Series,
    start_year: int = CURRENT_ACADEMIC_YEAR_START,
    errors: str = "raise",
) -> tuple[date | None, date | None] | tuple[pd.Series, pd.Series]

Calculates the expected DOB range (Sep 1 to Aug 31) for a given year group (1 to 13) in England. Includes some logic to try to handle Reception if entered as 'Reception', 'R', or 'Year R'.

Parameters:

Name	Type	Description	Default
`year_group`	`str \| int \| Series`	The year group you want to find the date of birth range for. Examples: 'Year 10', 'Y10', 10. Note: Reception should be entered as Reception, Year R or R.	required
`start_year`	`optional`	The year in which the academic year starts for the academic year you want to calculate. Example: for 2025/2026 enter 2025. You can enter any year here and it will return the date of birth range for someone in that year group during the specified academic year. Default is start of current academic year.	`CURRENT_ACADEMIC_YEAR_START`
`errors`	`optional`	default = 'raise' which raises all errors. 'ignore' and 'coerce' returns None, None.	`'raise'`

Raises:

Type	Description
`InvalidYearGroupError`	Raised when `year_group` input cannot be parsed or is out of range.
`FELevelError`	Raised if FE Levels are in `year_group`.
`TypeError`	Raised if `year_group` cannot be parsed to a valid int.

Returns:

Type	Description
`tuple[date \| None, date \| None] \| tuple[Series, Series]`	The date of birth range. First date is start of the academic year; second date is the end of the academic year. Example: 01/09/2013, 31/08/2014.