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
This Python project uses Poetry for dependency management. To get started:
- Clone this repo, or create a fork, on your development workstation.
- Install Poetry on your development workstation (if needed).
- At the command line, use
cd
to go to the project's root directory in your repo. - Run
poetry install
to configure your virtual environment and add all the required python packages. - 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.
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
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.
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.
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.