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 forsetup.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-fledgedsetup.cfg
to declare your package information instead of runningsetup()
.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 fromsetup.cfg
. The packaging community is moving towards favoringsetup.cfg
andpyproject.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 theinclude_package_data
keyword insetup.cfg
. This tells setuptools to install any data files it finds in your packages. The data files must be specified via theMANIFEST.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 theinstall_requires
forsetup.py
fromrequirements.txt
file to reduce redundancy. We also reuse therequirements.txt
file forreadthedocs.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 underdocs/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 atox.ini
file that should reside next to yoursetup.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 forCoverage.py
, a tool for measuring code coverage in Python. The default name for configuration files is.coveragerc
, in the same directorycoverage.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, andcodecov.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 fordiff-quality
.
versioneer : A tool for managing a recorded version number in setuptools-based python projects.
versioneer.py
: To allowsetup.py
to compute a version too, aversioneer.py
is added to the top level of your source tree, next tosetup.py
and thesetup.cfg
that configures it.
Git¶
.gitattributes
: If the attributeexport-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.