Table of Contents¶

Overview¶

Given the polling day of an election in the UK, when should the Statement of Persons Nominated (SoPN) be published?

When an election is called in the United Kingdom, the voting public must have access to the list of candidates who have been nominated to that post.

These documents are called Statements of Persons Nominated, and must be published a set number of working days ahead of the actual election date. The number varies based on:

Type of Post - Parliamentary, Local, devolved Government, etc.
Country - The United Kingdom has up to four different rules for the same type of election, one for each country.
Calendar - each country has their own unique set of Bank Holidays.

This library encapsulates timetable legislation for elections run in the United Kingdom and its devolved administrations.

Usage¶

from sopn_publish_date import StatementPublishDate
from datetime import date

publish_date = StatementPublishDate()

print(publish_date.national_assembly_for_wales(date(2016, 5, 5)))

# datetime.date(2016, 4, 7)

Installation¶

pip install sopn_publish_date

Third-Party Sources¶

The bank holidays JSON used in this project is provided by gov.uk under the Open Government Licence

Legislation¶

Below are the types of election supported by this library and their corresponding pieces of legislation.

United Kingdom¶

Election type	Legislation
UK Parliament	https://www.legislation.gov.uk/ukpga/1983/2/contents (Schedule 1, rules 1 & 2), two amendments outstanding: https://www.legislation.gov.uk/ukpga/2011/14 and https://www.legislation.gov.uk/ukpga/2013/6/section/14

England¶

Election type	Legislation
Greater London Authority	https://www.legislation.gov.uk/uksi/2007/3541/made (Rule 7 and Schedules 1/2/3/5/6/7, rules 3 & 4), amended by https://www.legislation.gov.uk/uksi/2016/24/article/6/made
Police & Crime Commissioner	https://www.legislation.gov.uk/uksi/2012/1917/made (Schedule 3, rules 1 & 3), amended by https://www.legislation.gov.uk/uksi/2014/921/article/31/made and https://www.legislation.gov.uk/uksi/2016/300/article/11/made
Combined Authority Mayors	https://www.legislation.gov.uk/uksi/2017/67/made (Schedules 1/3, rules 3 & 4)
Local (Principal Areas), England & Wales	https://www.legislation.gov.uk/uksi/2006/3304/made (Schedules 2/3, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2014/494/made (Rules 3(2) and 4(2))
Local Mayors, England & Wales	https://www.legislation.gov.uk/uksi/2007/1024/made (Schedules 1/3, rules 3 & 4), amended by https://www.legislation.gov.uk/uksi/2014/370/made (Regulations 5(2) and 7(2))
Parishes & Communities, England & Wales	https://www.legislation.gov.uk/uksi/2006/3305/made (Schedules 2/3, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2014/492/made (Rules 3(2) and 4(2))
City of London	https://www.cityoflondon.gov.uk/about-the-city/voting-elections/Documents/wardmote-book-june-2014.pdf (Section 4, paragraph 20))

Wales¶

Election type	Legislation
National Assembly of Wales	https://www.legislation.gov.uk/uksi/2007/236/made (Schedule 5, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2016/272/article/18/made
Local (Principal Areas), England & Wales	https://www.legislation.gov.uk/uksi/2006/3304/made (Schedules 2/3, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2014/494/made (Rules 3(2) and 4(2))
Local Mayors, England & Wales	https://www.legislation.gov.uk/uksi/2007/1024/made (Schedules 1/3, rules 3 & 4), amended by https://www.legislation.gov.uk/uksi/2014/370/made (Regulations 5(2) and 7(2))
Parishes & Communities, England & Wales	https://www.legislation.gov.uk/uksi/2006/3305/made (Schedules 2/3, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2014/492/made (Rules 3(2) and 4(2))

Scotland¶

Election type	Legislation
Scottish Parliament	https://www.legislation.gov.uk/ssi/2015/425/made (Schedule 2, rules 1 & 2)
Local (Scotland)	https://www.legislation.gov.uk/ssi/2011/399/made (Schedule 1, rules 1 & 2)

Northern Ireland¶

Election type	Legislation
Northern Ireland Assembly	https://www.legislation.gov.uk/uksi/2009/256/made (Schedule 1)
Local (Northern Ireland)	https://www.legislation.gov.uk/apni/1962/14 (Schedule 5, rules 1 & 2), amended by https://www.legislation.gov.uk/uksi/2010/2977/schedule/1/part/4/made

Tests¶

Writing tests for code that represents legislation is a bit fiddly.

Ideally we’d have perfect test cases but as noted in Overview there are concrete examples of a candidate rejecting their nomination, pushing back the publishing of the SoPN papers.

This project has two sets of tests:

Unit tests, with single-specified examples
Approval tests, with test data sourced from parsing historic SoPNs (provided by Democracy Club, who maintain a database of candidates and elections)

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