Table of Contents

Overview

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

The election timetable 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.

Usage (publishing of candidate lists)

from datetime import date
from uk_election_timetables.elections.uk_parliament import UKParliamentElection

election = UKParliamentElection(date(2019, 2, 21))

print(election.sopn_publish_date) # date(2019, 1, 25)

Installation

pip install uk_election_timetables

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)

uk_election_timetables

calendars

class uk_election_timetables.calendars.BankHolidayCalendar(dates)

Bases: object

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

static create_matcher_from_entry(entry: dict) → DateMatcher
exempted_dates()
class uk_election_timetables.calendars.Country(value)

Bases: Enum

The countries of the United Kingdom.

ENGLAND = 1
NORTHERN_IRELAND = 2
SCOTLAND = 3
WALES = 4
class uk_election_timetables.calendars.Region(value)

Bases: Enum

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 uk_election_timetables.calendars.UnitedKingdomBankHolidays

Bases: object

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() → BankHolidayCalendar
Returns:

a calendar representation of bank holidays in England and Wales

from_country(country: Country) → 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() → BankHolidayCalendar
Returns:

a calendar representation of bank holidays in Northern Ireland

scotland() → BankHolidayCalendar
Returns:

a calendar representation of bank holidays in Scotland

uk_election_timetables.calendars.working_days_before(end_date: date, days: int, calendar: BankHolidayCalendar) → 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

date

class uk_election_timetables.date.DateMatcher(day: int, month: int, year: Optional[int] = None, name: Optional[str] = None)

Bases: object

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

matches(other: date) → bool

Return whether the input date matches the attributes of this class

Parameters:

other – the date being matched against

Returns:

a boolean representing if the input date matches this class’s attributes

uk_election_timetables.date.days_before(poll_date: date, days: int, ignore: Optional[List[DateMatcher]] = None) → 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

election

class uk_election_timetables.election.Election(poll_date: date, country: Country)

Bases: object

BANK_HOLIDAY_CALENDAR = <uk_election_timetables.calendars.UnitedKingdomBankHolidays object>
property postal_vote_application_deadline: date

Calculates the postal vote application deadline for this Election

This is set out in The Representation of the People (England and Wales) Regulations 2001.

In Northern Ireland, this is set out in The Representation of the People (Northern Ireland) Regulations 2008 <https://www.legislation.gov.uk/uksi/2008/1741/regulation/61/made>

Returns:

a datetime representing the postal vote application deadline

property registration_deadline: date

Calculates the voter registration deadline for this Election

This explained in a background note from the Electoral Commission

Returns:

a datetime representing the voter registration deadline

abstract property sopn_publish_date: date
property timetable: List[Dict]

An aggregate of all known dates for the specific election type.

Returns:

a list representing the entire timetable for this particular election.

property vac_application_deadline: date

Calculates the Voter Authority Certificate (VAC) application deadline for this Election

This is set out by the Electoral Commission here: https://www.electoralcommission.org.uk/cy/node/25624

Returns:

datetime.date representing the VAC application deadline

election_ids

exception uk_election_timetables.election_ids.AmbiguousElectionIdError(election_id: str)

Bases: BaseException

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 uk_election_timetables.election_ids.InvalidElectionIdError(election_id: str)

Bases: BaseException

An exception type to represent when an election id does not confirm to DemocracyClub’s uk-election-ids format

exception uk_election_timetables.election_ids.NoSuchElectionTypeError(election_type: str)

Bases: BaseException

An exception type to represent when an election type doesn’t actually represent a valid election.

uk_election_timetables.election_ids.from_election_id(election_id: str, country: Optional[Country] = None) → Election

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).

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

uk_election_timetables.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)

elections package

Submodules

elections.greater_london_assembly

class uk_election_timetables.elections.greater_london_assembly.GreaterLondonAssemblyElection(poll_date: date)

Bases: Election

property sopn_publish_date: 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

elections.local

class uk_election_timetables.elections.local.LocalElection(poll_date: date, country: Country)

Bases: Election

property sopn_publish_date: date

Calculate the publish date for a local election.

This is set out in:

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

elections.mayor

class uk_election_timetables.elections.mayor.MayoralElection(poll_date: date)

Bases: Election

property sopn_publish_date: 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

elections.northern_ireland_assembly

class uk_election_timetables.elections.northern_ireland_assembly.NorthernIrelandAssemblyElection(poll_date: date)

Bases: Election

property sopn_publish_date: 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

elections.police_and_crime_commissioner

class uk_election_timetables.elections.police_and_crime_commissioner.PoliceAndCrimeCommissionerElection(poll_date: date)

Bases: Election

property sopn_publish_date: 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

elections.scottish_parliament

class uk_election_timetables.elections.scottish_parliament.ScottishParliamentElection(poll_date: date)

Bases: Election

property postal_vote_application_deadline: date

Calculates the postal vote application deadline for this Election

This is set out in Scottish General Election (Coronavirus) Act 2021.

Returns:

a datetime representing the postal vote application deadline

property sopn_publish_date: 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

elections.senedd_cymru

class uk_election_timetables.elections.senedd_cymru.SeneddCymruElection(poll_date: date)

Bases: Election

property sopn_publish_date: date

Calculate the publish date for an election to the Senedd Cymru / Welsh Parliament

This is set out in Senedd and Elections (Wales) Act 2020 <https://www.legislation.gov.uk/anaw/2020/1/contents> and 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

elections.uk_parliament

class uk_election_timetables.elections.uk_parliament.UKParliamentElection(poll_date: date, country: Optional[Country] = None)

Bases: Election

date_for_country(country: Country) → date
property sopn_publish_date: date

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

Module contents