A Python-based ballot generation sandbox, part of the OSET BallotStudio project

BallotLab

A Pythonic repo of PDF-related code to lay out EAC-compliant ballots, part of the OSET BallotStudio project. I'm testing out some ideas here, so this isn't considered production code.

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.