Skip to content

Latest commit

 

History

History
82 lines (60 loc) · 3.43 KB

HACKING.md

File metadata and controls

82 lines (60 loc) · 3.43 KB
Raw

email2pdf - Hacking

This document talks about hacking/developing on email2pdf - for more information on email2pdf and how to use it, please see README.md.

In general, bug reports/enhancement requests as well as pull requests are welcome; please note the license conditions. If you are trying to report an issue, please try running email2pdf with the -vv option to maximise the debugging output first.

Building & Packaging

All the supplied build and packaging is based on a Makefile. You'll need make if you don't have it (sudo apt-get install make on Ubuntu/Debian, brew install make on OS X).

Design & Coding Principles

  • Follow PEP-8. Running make analysis will check against this and run other static code analysis checks also.

  • Try to keep email2pdf as "safe" as possible by default. Without supplying any potentially harmful command-line options, email2pdf will not ignore parts of the email it shouldn't, and will fail in the standard UNIX way with an error code if it has any significant doubts about the integrity of the email it's reading, or any other serious error occurs.

Unit Tests

All the unit tests are in the tests/ directory. You can run them from the Makefile using the unittest or unittest_test targets (the second is more verbose, and stops on failing tests).

All new code should be covered by a test. There is a code coverage checker target in the Makefile - run make coverage. You'll need to have the coverage and nose Python modules installed (pip3 install coverage nose) to run them.

In addition to the standard dependencies from the standard install documentation, there are some additional dependencies which will be needed to make the tests work:

OS X

Just run pip3 install -r requirements_hacking.txt.

Debian/Ubuntu

  • python3-freezegun - only available in Ubuntu 14.10 onwards - see http://packages.ubuntu.com/search?keywords=python3-freezegun. If you are on an earlier version, you can download the .deb manually and install with dpkg -i.

  • python3-reportlab - install with apt-get install python3-reportlab.

  • python3-pdfminer3k (not a standard Debian/Ubuntu package, but there is a supplied Makefile target which will create it for you using a Docker container - run make rundocker_getdebs, then dpkg -i the package when you are done).

Docker

There is some experimental packaging for Docker also. Of course, you need to have Docker installed for this to work, which is outside the scope of this document. You can run the following make targets:

  • rundocker_interactive - build and start a Docker image, at the bash prompt. Can be used to interactively test email2pdf.

  • rundocker_testing - build and start the Docker image, run the entire unit testing and style testing suites, and exit.

  • rundocker_getdebs - build and start the Docker image, and copy out various .debs, including the .deb for email2pdf itself, and various dependencies that are harder to come by or need to be built manually.