iandinwoodie/pdfpop

🍡Automate PDF population with pdfpop.

---

Automate PDF population with pdfpop.

Installation

You can install pdfpop with:

pip install pdfpop

Usage

The pdfpop usage consists of two steps: (1) form configuration and (2) execution.

Step 1. Form Configuration

ℹ️ This step only needs to be run once for each unique form.

This step generates a form-specific configuration file that allows you to inform pdfpop how data should be routed from the data file to the PDF form. You can generate this file with the config command:

# Usage: pdfpop config <form>
pdfpop config examples/example-form.pdf

This will output a pdfpop- prefixed JSON file in your current working directory (e.g., pdfpop-example-form.json). By default, all fields will be assigned a value of null and, therefore, will be ignored until the null value is replaced with instructions on how to populate the field. An example of an edited configuration file is available here.

Step 2. Exectuion

Once you have a form configuration file you can populate your PDF form using the run command:

# Usage: pdfpop run <config> <data>
pdfpop run examples/example-form.json examples/example-data.xlsx

This will generate a populated PDF form at the location prescribed by the values of<output_dir>/<output_name> in the configuration file (e.g., examples/pdfpop-example-form.pdf).

License

Copyright (C) 2022 Ian Dinwoodie

• Licensed under GNU General Public License v3.0.
• Exceptions:
  • Material covered by Third Party Licenses.
  • Logo icon: Popsicle stick icons created by Freepik - Flaticon

pdfpop's Issues

Simplify user interface

Overview

The current four command interface (i.e., add, list, remove, pop) is unnecessarily complicated, especially for the target user audience. We can simply the interface to just two commands, config and run, to accomplish the same goal with less complexity.

Proposed Interface

Config Command

• Description: Generate a PDF form configuration file.
• Usage: pdfpop config <form>
• Behavior:
  • Error if <form> is not a valid path to a PDF form.
  • Write a configuration file for <form>.
    • Default output filename should be pdfpop-<name>.json where <name> is the base name of <form> less the extension.
    • Output file should be written to the current working directory.
    • Error if pdfpop-<name>.json already exists in the current working directory to avoid accidental overwrites.
    • Configuration file contents should be in JSON format containing:
      • I/O dictionary:
        • input: <form> where form is the actual file path given at creation.
      • Fields dictionary:
        • Key: PDF field
        • Value: null by default.

Run Command

• Description: Populate a PDF form with data as prescribed by the configuration file.
• Usage: pdfpop run <config> <data>.
• Behavior:
  • Error if <map> is not a valid path to a configuration JSON file.
  • Error if <data> is not a valid path to a data file.
    • Support XLSX, XLS, and CSV data files.
  • Error when a PDF field is encountered that does not exist in the configuration's fields dictionary.
  • Write a populated copy of <form>.
    • Default output filename should be <name>.pdf where <name> is the base name of <config> less the extension.
    • Output a summary of the actions taken so that the configuration and output can be iteratively adjusted without the need to open the populated PDF form to verify.

Create data directory for tests

This is a migration of tests/files to tests/data to adhere to common conventions.

Add code quality metric badge

This requires the introduction of linting workflow.

Use absolute paths in README

Convert links in README to absolute links so they point to the correct files for sites like PyPI.

Add coverage status badge

Allow execution of I/O configuration values

Values for the key-value pairs in the io section of the configuration should be executable for runtime determinism. For example, users should be able to prescribe an output filename based on information from the data file (e.g., <first>-<last>.pdf).

Add attributions

Attributions need to be added for:

• PDF form filling logic
• Popsicle SVG
• Banner font

Add system tests

Application should be system tested in addition to unit tested.

Add document explaining what types of values are supported in the form config.

Currently it is not clear to users what is supported for values in the key-value form configuration pairs (i.e., integers, strings, expressions).

No need to have return statement in IO config.

Currently the IO config entries include return which is unnecessary since they are just returning a value. Instead, we can just use the value.

Old behavior:

"io": {
    "form": "return 'form.pdf'"

New behavior:

"io": {
    "form": "form.pdf"

Collect code coverage

Code coverage should be collected to identify untested and/or unused code.

Overhaul form configuration file

Add CI testing automation.

Add support for multi-row data files.

This application needs to support data files that contain more than one row.

Add package publishing action.

Automate the publishing for the package on pypi.

Add interactive configuration mode

Add a changelog

Follow the conventions outlined via https://keepachangelog.com/en/1.0.0/