Year Groups API

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

hh.clean_year_group

clean_year_group(
    year_group: str | int, errors: str = "raise"
) -> str | None

Takes school year groups and cleans them to have the consistent format 'Year i'.

Parameters:

Name	Type	Description	Default
`year_group`	`str \| int`	Text you wish to clean. Numbers entered will be cast to strings if possible.	required
`errors`	`str`	default = 'raise' which raises all errors. 'ignore' returns original value, 'coerce' returns None.	`'raise'`

Raises:

Type	Description
`InvalidYearGroupError`	Raised when `year group` input cannot be parsed or is out of range.
`TypeError`	Raised when `year group` input cannot be parsed to a valid int.

Returns:

Type	Description
`str \| None`	Cleaned year group in the format 'Year i'.

hh.calculate_year_group_from_date

calculate_year_group_from_date(
    input_date: date,
    start_of_academic_year: int = CURRENT_ACADEMIC_YEAR_START,
    errors: str = "raise",
) -> str | None

Calculates school year group from date of birth for the English school system. Returns 'Year i' or 'Reception', or 'Student too young for school' if date of birth is not of school age.

Parameters:

Name	Type	Description	Default
`input_date`	`date`	Date of birth you wish to know the school year for.	required
`start_of_academic_year`	`optional`	The school year in which you want to calculate the year group for. Allows you to calculate a year group for any academic year not just current e.g. for 2025/26 school year enter 2025. Default is start of current academic year.	`CURRENT_ACADEMIC_YEAR_START`
`errors`	`optional`	default = 'raise' which raises all errors. 'ignore' returns None.	`'raise'`

Raises:

Type	Description
`TypeError`	Raised if input_date is not a date.
`InvalidYearGroupError`	Raised when the calculated year group is out of range (greater than Year 13).

Returns:

Type	Description
`str \| None`	Returns 'Year i', 'Reception', 'Student too young for school' or None if errors='ignore'.