BallotLab

A Pythonic repo of PDF-related code to lay out EAC-compliant ballots, part of the OSET BallotStudio project. This project has been moved to TrustTheVote-Project/BallotLab: Encapsulated software for generating ballots from NIST 1500-100 election definition datasets., and is archived here for historical purposes. Please go to TrustTheVote-Project/BallotLab if you'd like to contribute.

Getting Started

First, clone this repo into your a folder on your development computer. Then, follow these steps to set up your development environment: How to set up a perfect Python project

TL;DR: here's a summary listing of the bash commands:

cd [vour/repo/directory]
# install pipenv (system-wide)
pip install pipenv
# set up pipenv with python 3.9
pipenv install --python 3.9
# install development tools
pipenv install isort --dev
# currently, black is pre-release so use the --pre flag
pipenv install black --pre --dev  
pipenv install flake8 --dev
pipenv install mypy --dev
pipenv install pytest pytest-cov --dev

Install Required Python Packages

Once you've set up your development environment, install the required Python packages:

# Create PDF ballot files
pipenv install reportlab
# Add images to PDF files (replaces deprecated PIL)
pipenv install pillow
# (optional) extract text from PDFs
pipenv install pdfminer.six

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 will conform 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.