API¶

sopn_publish_date¶

class sopn_publish_date.StatementPublishDate¶

european_parliament(poll_date: datetime.date, region: sopn_publish_date.calendars.Region) → datetime.date¶

Calculate the publish date for an election to the European Parliament

This is set out in The European Parliamentary Elections (Amendment) Regulations 2009

As Gibraltar is included within South West England but has a different bank holiday calendar, it’s plausible that the SoPN date for South West England will differ from the rest of England.

Parameters:	poll_date – a datetime representing the date of the poll region – the region of the UK and Gibraltar where the poll is being run
Returns:	a datetime representing the expected publish date

for_id(election_id: str, country: sopn_publish_date.calendars.Country = None) → datetime.date¶

Calculate the publish date for an election given in uk-election-ids format and an optional country if necessary (for example, local or parliamentary elections).

This function returns None for elections to the European Parliament, and will raise an exception if the election id is ambiguous (could correspond to elections in multiple countries with different electoral legislation).

Parameters:	election_id – a string representing an election id in uk-election-ids format country – an optional Country representing the country where the election will be held
Returns:	a datetime representing the expected publish date

greater_london_assembly(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the Greater London Assembly

This is set out in The Greater London Authority Elections (Amendment) Rules 2016

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

local(poll_date: datetime.date, country: sopn_publish_date.calendars.Country)¶

Calculate the publish date for a local election.

This is set out in:

The Local Elections (Principal Areas) (England and Wales) (Amendment) Rules 2014

The Local Elections (Northern Ireland) Order 2010

The Scottish Local Government Elections Order 2011

Parameters:	poll_date – a datetime representing the date of the poll country – the country in which the election is being run
Returns:	a datetime representing the expected publish date

mayor(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the position of Mayor in England and Wales

This is set out in The Local Authorities (Mayoral Elections) (England and Wales) (Amendment) Regulations 2014

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

national_assembly_for_wales(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the National Assembly for Wales

This is set out in The National Assembly for Wales (Representation of the People) (Amendment) Order 2016

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

northern_ireland_assembly(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the Northern Ireland Assembly

This is set out by Schedule 5, Rules 1 and 2 of The Northern Ireland Assembly (Elections) (Amendment) Order 2009

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

police_and_crime_commissioner(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the position of Police and Crime Commissioner

This is set out in The Police and Crime Commissioner Elections (Amendment) Order 2014

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

scottish_parliament(poll_date: datetime.date) → datetime.date¶

Calculate the publish date for an election to the Scottish Parliament

This is set out in The Scottish Parliament (Elections etc.) Order 2015

Parameters:	poll_date – a datetime representing the date of the poll
Returns:	a datetime representing the expected publish date

uk_parliament(poll_date: datetime.date, country: sopn_publish_date.calendars.Country = None)¶

Calculate the publish date for an election to the Parliament of the United Kingdom

This is set out in Representation of the People Act 1983 and its amendments.

Parameters:	poll_date – a datetime representing the date of the poll country – an optional Country representing the country where the election will be held
Returns:	a datetime representing the expected publish date

sopn_publish_date.calendars¶

class sopn_publish_date.calendars.BankHolidayCalendar(dates)¶

A calendar that honours the standard 5-day week in addition to the input list of dates.

static create_matcher_from_entry(entry: dict) → sopn_publish_date.date.DateMatcher¶

exempted_dates()¶

class sopn_publish_date.calendars.Country¶

The countries of the United Kingdom.

ENGLAND = 1¶

NORTHERN_IRELAND = 2¶

SCOTLAND = 3¶

WALES = 4¶

class sopn_publish_date.calendars.FixedDates¶

A set of fixed dates used in other calculations by this library.

EUROPARL_GIBRALTAR_2019 = datetime.date(2019, 4, 24)¶

class sopn_publish_date.calendars.Region¶

The regions of the United Kingdom and Gibraltar as elected in the EU Parliament

EAST_MIDLANDS = 1¶

EAST_OF_ENGLAND = 2¶

LONDON = 3¶

NORTHERN_IRELAND = 6¶

NORTH_EAST_ENGLAND = 4¶

NORTH_WEST_ENGLAND = 5¶

SCOTLAND = 7¶

SOUTH_EAST_ENGLAND = 8¶

SOUTH_WEST_ENGLAND = 9¶

WALES = 10¶

WEST_MIDLANDS = 11¶

YORKSHIRE_AND_THE_HUMBER = 12¶

class sopn_publish_date.calendars.UnitedKingdomBankHolidays¶

A representation of the bank holiday calendars in the United Kingdom.

This class exposes a function for each unique calendar: England & Wales, Northern Ireland, and Scotland.

england_and_wales() → sopn_publish_date.calendars.BankHolidayCalendar¶

Returns:	a calendar representation of bank holidays in England and Wales

from_country(country: sopn_publish_date.calendars.Country) → sopn_publish_date.calendars.BankHolidayCalendar¶

Return the bank holiday calendar for the input country.

Parameters:	country – the country to retrieve the calendar for
Returns:	the corresponding calendar

northern_ireland() → sopn_publish_date.calendars.BankHolidayCalendar¶

Returns:	a calendar representation of bank holidays in Northern Ireland

scotland() → sopn_publish_date.calendars.BankHolidayCalendar¶

Returns:	a calendar representation of bank holidays in Scotland

sopn_publish_date.calendars.working_days_before(end_date: datetime.date, days: int, calendar: sopn_publish_date.calendars.BankHolidayCalendar) → datetime.date¶

Return date corresponding to count working days before poll_date according to the given bank holiday calendar

Parameters:	end_date – the date of the poll days – the number of days before the poll date calendar – the bank holiday calendar used in the calculation
Returns:	the calculated date

sopn_publish_date.election_ids¶

exception sopn_publish_date.election_ids.AmbiguousElectionIdError(election_id: str)¶: An exception type to represent when an election id (usually a group such as local.2019-05-02) can correspond to elections in multiple countries with different legislation governing the publish date of Statements of Persons Nominated.

exception sopn_publish_date.election_ids.InvalidElectionIdError(election_id: str)¶: An exception type to represent when an election id does not confirm to DemocracyClub’s uk-election-ids format

exception sopn_publish_date.election_ids.NoSuchElectionTypeError(election_type: str)¶: An exception type to represent when an election type doesn’t actually represent a valid election.

sopn_publish_date.election_ids.type_and_poll_date(election_id: str) -> (<class 'str'>, <class 'datetime.date'>)¶

Extract election_type (e.g. parl, local, mayor) and poll_date from an election id.

Parameters:	election_id – a string representing an election id in uk-election-ids format
Returns:	a tuple (election_type: str, poll_date: date)

sopn_publish_date.date¶

class sopn_publish_date.date.DateMatcher(day: int, month: int, year: int = None, name: str = None)¶

An object that represents a matcher against datetime.date objects, given a day, a month, and an optional year.

matches(other: datetime.date) → bool¶

Return whether the input date matches the attributes of this class

Parameters:	other – the date being matched against

:return a boolean representing whether the input matched against this class’s attributes

sopn_publish_date.date.days_before(poll_date: datetime.date, days: int, ignore: List[sopn_publish_date.date.DateMatcher] = None) → datetime.date¶

Return date corresponding to days working days before poll_date, not counting the list of provided exemptions

Parameters:	poll_date – the date of the poll days – the number of days before the poll date ignore – the list of DateMatchers to ignore in the look-back calculation
Returns:	the calculated date