BallotLab

Encapsulated Python software for generating EAC-compliant ballots from NIST 1500-100 election definition datasets, part of the OSET BallotStudio project.

For a version history, please see CHANGELOG.md

Getting Started

This Python project uses Poetry for dependency management. To get started:

1. Clone this repo, or create a fork, on your development workstation.
2. Install Poetry on your development workstation (if needed).
3. At the command line, use cd to go to the project's root directory in your repo.
4. Run poetry install to configure your virtual environment and add all the required python packages.
5. Run poetry shell to invoke the virtual environment.

For detailed instructions on how to work with the code in this repo, check out Getting Started with BallotLab · TrustTheVote-Project/BallotLab Wiki.

Once you've set up the virtual environment with poetry shell you can run the Python app without having to use poetry run -- like this:

ballotmaker --help        # display the CLI help text
ballotmaker --version     # display the current version number

Check the help pages for details on other sub-commands you can use with ballotmaker.

Running Tests

After you've followed the steps above in Getting Started, you can also run the pytest suite with this command:

pytest

Or, if you'd like to review coverage information and logging updates, try this command:

pytest --cov-report term-missing --cov=src/ --log-format="%(asctime)s %(levelname)s %(message)s" --log-cli-level=info

The Wiki

In addition to detailed instructions on how to get started with BallotLab, the TrustTheVote-Project/BallotLab Wiki includes the latest requirements, best practices for ballot design, and other useful information.

Project Structure

This Python project follows the current best practices for Python project organization, as specified in Packaging Python Projects — Python Packaging User Guide but also includes a few unusual folders:

• The assets folder contains the sample data files, fonts and images required to build ballots, including Roboto from Google Fonts.
• The pdfs folder contains the PDFs generated by the software. Ballot PDFs contain a date and time stamp in the file name, so you can check out the progression of the layout features from the resulting PDF files. I don't keep all of the PDFs I generate, but I try to keep representative samples that correspond to major features.
• The samplecode folder contains code snippets from other sources, typically mutateted and mangled to suit my needs. This is essentially "proof-of-concept" code that won't appear in the production version of this software package.
• The docs folder contains the two documents that serve as the offical specifications for both the input data (NIST.SP.1500-100r2.pdf) and the output PDF ballots (EAC_Effective_Election_Design.pdf). I've also converted the EAC Design doc to HTML and text file format using the pdfminer.six Python package.

Election Specifications

This software conforms to the following US Election specifications: usnistgov/ElectionResultsReporting at version2. We're also using the EAC Effective Elections Design document as our standard for ballot layout. These documents are available in the docs folder in this repo, too.