API Reference

IdBuilder

class uk_election_ids.election_ids.IdBuilder(election_type, date)

Builder object for creating Democracy Club Election Identifiers.

Constructor

Parameters

election_type (str) – May be one of ['europarl', 'gla', 'local', 'mayor', 'naw', 'nia', 'parl', 'pcc', 'sp', 'senedd', 'ref']
date (date|str) – May be either a python date object, or a string in ‘Y-m-d’ format. myid = IdBuilder('local', date(2018, 5, 3)) and myid = IdBuilder('local', '2018-05-03')) are functionally equivalent invocations.

Returns

IdBuilder

property ballot_id

Ballot ID

Type: str

property election_group_id

Election Group ID

Type: str

classmethod from_id(identifier: str) → IdBuilder

Parses a string in to an IdBuilder object. If an identifier is returned (no exception is raised) the identifier can be assumed to be valid and calls to validate() aren’t needed.

Parameters

identifier (str) – An election ID

Returns

IdBuilder

Raises

ValueError – In various cases if the ID is invalid
TypeError – if the identifier isn’t a string

property ids

All applicable IDs

Type: list[str]

property organisation_group_id

Organisation Group ID

Type: str

property subtype_group_id

Subtype Group ID

Type: str

with_contest_type(contest_type)

Add a contest_type segment

Parameters: contest_type (str) – Invoke with contest_type='by' or contest_type='by-election' to add a ‘by’ segment to the ballot_id. Invoking with contest_type='election' is valid syntax but has no effect.
Returns: IdBuilder
Raises: ValueError –

with_division(division)

Add a division segment

Parameters: division (str) – Official name of an electoral division.
Returns: IdBuilder
Raises: ValueError –

with_organisation(organisation)

Add an organisation segment.

Parameters: organisation (str) – Official name of an administrative body holding an election.
Returns: IdBuilder
Raises: ValueError –

with_subtype(subtype)

Add a subtype segment

Parameters: subtype (str) – May be one of ['a', 'c', 'r']. See the Reference Definition. for valid election type/subtype combinations.
Returns: IdBuilder
Raises: ValueError –

Usage Examples

>>> from uk_election_ids.election_ids import IdBuilder
>>> from datetime import date


# Chain method calls to build up an ID object
>>> myid = IdBuilder('local', date(2018, 5, 3))\
...     .with_organisation('Test Org')\
...     .with_division('Test Division')
# IdBuilder will deal with slugging strings for us
>>> myid.ballot_id
'local.test-org.test-division.2018-05-03'
>>> myid.ids
[
    'local.2018-05-03',
    'local.test-org.2018-05-03',
    'local.test-org.test-division.2018-05-03'
]


# IdBuilder only allows values defined in the Reference Definition
>>> myid = IdBuilder('gla', date(2018, 5, 3)).with_subtype('x')
ValueError: Allowed values for subtype are ('c', 'a')


# Group IDs can be created with partial information
>>> myid = IdBuilder('local', date(2018, 5, 3)).with_organisation('Test Org')
>>> myid.election_group_id
'local.2018-05-03'
>>> myid.organisation_group_id
'local.test-org.2018-05-03'
>>> myid.ballot_id
ValueError: election_type local must have a division in order to create a ballot id


# A Group ID object can be used to create multiple ballot IDs
>>> divisions = ["area1", "area2", "area3"]
>>> org_id = IdBuilder('local', date(2018, 5, 3)).with_organisation('Test Org')
>>> [org_id.with_division(d).ballot_id for d in divisions]
[
    'local.test-org.area1.2018-05-03',
    'local.test-org.area2.2018-05-03',
    'local.test-org.area3.2018-05-03'
]

# Create an IdBuilder class from an existing ID
>>> ballot_paper_id = "local.foo.bar.2020-01-01"
>>> parsed = IdBuilder.from_id(ballot_paper_id)
>>> parsed.election_group_id
'local.2020-01-01'

validate

uk_election_ids.election_ids.validate(identifier)

Validate an identifier. Internally calls IdBuilder.from_id() IdBuilder.from_id and returns True if the ID is built successfully.

Parameters: identifier (str) – String identifier we want to validate
Returns: bool

Usage Examples

>>> from uk_election_ids.election_ids import validate

>>> validate('local.2018-05-03')
True

>>> validate('foo.bar')
False