A Python web application for converting PDF forms into PDF-filling APIs.
You post an interactive PDF form, and the app will return a URL. If you post JSONs to that URL, the app will return the PDF and use the JSON to fill the form fields.
This app is a prototype. It is less than a month old. Don't use it in production.
- If you set up the project on your computer, you should be able to use it to fill pdf forms.
- It only supports a couple types of PDF form fields.
- The code base is only covered by a few integration tests.
- The app does not check for or properly handle a wide variety of errors that are likely to occur.
- It may be difficult to integrate this into an existing Flask project.
Here are the current priorities for development.
- Improve the documentation.
- Support the filling of most PDF field types.
- Increase test coverage to 100% with greater emphasis on unit tests.
- Make sure that tests cover any reasonable use cases.
This app idea originated from a common need to automatically fill PDF forms in various Code for America projects. Filling PDFs is an all-too-common need for many government and institutional services, and automatically populating forms can be a useful step in redesigning those services to better serve clients.
After an initial proof-of-concept in another project, I decided to spin this off into a separate project.
This was created by @bengolder at @CodeForAmerica with contributions from: @gauravmk, @zhoux10, @bhoeting, @samgensburg, @debrasol, and @joffemd
You need to download, install, and run the web app locally. Once the local server is running, you can upload PDFs to create APIs, and then fill those PDFs.
The following instructions assume:
- You are using a unix-based operating system, such as OS X or Linux
- You are comfortable on the command line
- Your computer has essential build tools installed
- You have git installed and configured on your command line.
This is a Python 3 app written using Flask. It has only been tested on Ubuntu 14.04 (via Travis CI) and OS X 10.11
This application depends on the itextpdf java library, by iText, offered under GNU AGPL version 3.
If your computer does not have Python 3, you can install it on OS X using Homebrew or by downloading it from python.org. Make sure that python3 is available on your PATH.
brew install python3
# check the version
python3 --version
git clone https://github.com/codeforamerica/pdfhook.git
cd pdfhook
python3 -m venv . # create the virtual environment
source bin/activate
make install
You do not need to set up a database, but you can create a custom one if you like. By default, the application will create and use an SQLite database. It only uses one database table. Upon the first request it checks if that table has been created. If not, it will create a table before processing the request.
make run
Visit http://localhost:5000/ to see the demo page. Use the API to post a PDF form to the same URL.
make test
# or if you'd like to run specific tests
make test TEST_SCOPE=tests.integration.test_sample_pdfhook:TestPDFHook.test_fill_pdf
To deploy on Heroku use the button or:
git clone https://www.github/codeforamerica/pdfhook.git
cd pdfhook
heroku login
heroku apps:create
git push heroku master
To deploy on Cloud Foundry:
git clone https://www.github/codeforamerica/pdfhook.git
cd pdfhook
cp manifest.yml.example manifest.yml
# make any changes to `manifest.yml`, if desired
cf push -f manifest.yml
To deploy on Windows or Mac via virtual machine, install Vagrant and VirtualBox then:
git clone https://www.github/codeforamerica/pdfhook.git
cd pdfhook
vagrant up