Tools

For clarity and understanding, here is a list of the tools utilized for this project.

Setuptools

Setuptools is a fully-featured, actively-maintained, and stable library designed to facilitate packaging Python projects.

  • setup.py: Setuptools offers first class support for setup.py files as a configuration mechanism. The file is a sort of “recipe” that includes information like the name of your project, the version, and any packages or modules it needs to work properly.

  • setup.cfg: To avoid executing arbitrary scripts and boilerplate code, we are transitioning into a full-fledged setup.cfg to declare your package information instead of running setup().

  • setup.py is a Python script used to define setup details and can execute arbitrary code. setup.cfg is a configuration file in INI format that also defines setup details, but in a safer, static way. If both files are present, setup.py can read from setup.cfg. The packaging community is moving towards favoring setup.cfg and pyproject.toml for a more standardized process.

  • MANIFEST.in: Setuptools offers three ways to specify data files to be included in your packages. For the simplest use, you can simply use the include_package_data keyword in setup.cfg. This tells setuptools to install any data files it finds in your packages. The data files must be specified via the MANIFEST.in file or automatically added by a Revision Control System plugin.

  • requirements.txt: Specifies the set of dependencies needed for the Python project. It can be created manually, but it is recommended to use pipreqs to generate it automatically. In this project, we directly get the install_requires for setup.py from requirements.txt file to reduce redundancy. We also reuse the requirements.txt file for readthedocs.xml.

Documentation

Sphinx

Sphinx makes it easy to create intelligent and beautiful documentation.

  • docs: The source documentation files in reStructuredText format. To generate docs in html format, simply run: sphinx-build -b html docs/source docs/build and you can find the generated html files under docs/build.

Read the Docs

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you.

  • readthedocs.yml: Read the Docs supports configuring your documentation builds with a YAML file. The configuration file must be in the root directory of your project and be named .readthedocs.yaml.

  • numpydoc : Numpy’s Sphinx extensions.

  • sphinx-rtd-theme : Read the Docs theme for Sphinx.

Design Diagrams

  • Pyreverse: Part of the PyLint tool, Pyreverse analyzes your Python code and generates UML diagrams from it. Simply run pyreverse -o plantuml -d assets/diagrams pdpbox to generate the UML diagrams.

  • PlantText: PlantText is an online tool that quickly generates images from text. Primarily, it is used to generate UML (Unified Modeling Language) diagrams.

Test & CI

Tox

Tox aims to automate and standardize testing in Python.

  • tox.ini: Put basic information about your project and the test environments you want your project to run in into a tox.ini file that should reside next to your setup.py file.

Travis CI

Travis CI is a continuous integration tool that test and deploy your projects with ease.

  • .travis.yml: Builds on Travis CI are configured mostly through the build configuration stored in the file .travis.yml in your repository. This allows your configuration to be version controlled and flexible.

GitHub Action

GitHub Actions is a feature of GitHub that allows you to automate software workflows. It’s effectively a CI/CD system that’s built into GitHub. In the latest refactor, I migrated from Travis CI to GitHub Actions.

  • .github/workflows/tox-test.yml: Workflows configuration. Workflows are custom automated processes that you can set up in your repository to build, test, package, release, or deploy any code project on GitHub.

Others

  • pipconflictchecker : A tool that checks installed packages against all package requirements to ensure that there are no dependency version conflicts.

  • coverage : A tool for measuring code coverage of Python programs.

    • .coveragerc: A configuration file for Coverage.py, a tool for measuring code coverage in Python. The default name for configuration files is .coveragerc, in the same directory coverage.py is being run in.

    • codecov.yml: A configuration file for Codecov, a tool that collects coverage reports and provides visualizations, analytics, and various other features.

    • In other words, .coveragerc is used to control how coverage data is collected, and codecov.yml is used to control how that data is interpreted and presented.

  • diff-cover : Automatically find diff lines that need test coverage. Also finds diff lines that have violations (according to tools such as pycodestyle, pyflakes, flake8, or pylint). This is used as a code quality metric during code reviews.

    • .flake8: flake8 config for diff-quality.

  • versioneer : A tool for managing a recorded version number in setuptools-based python projects.

    • versioneer.py: To allow setup.py to compute a version too, a versioneer.py is added to the top level of your source tree, next to setup.py and the setup.cfg that configures it.

Git

  • .gitattributes: If the attribute export-subst is set for a file then Git will expand several placeholders when adding this file to an archive.

  • .gitignore: Specifies intentionally untracked files to ignore.