Adding and modifying dependencies¶
Finesse manages its dependencies via pip using
requirements
files. These files work in conjunction with the Conda environment
file to allow ease-of-use through Conda environments, with a single set of requirements
held in the requirements files to allow other package management tools to be used if you
so wish.
There are four requirements files in total:
requirements.txt — core packages needed to run Finesse.
requirements-build.txt — packages required to build Finesse C extensions.
requirements-doc.txt — packages required to build the documentation.
requirements-test.txt — packages required to run the Finesse test suite.
requirements-dev.txt — all of the above plus some extra formatting and version control related packages for working with Finesse source code.
In addition to the above requirements files, Finesse uses separate
install_requires
and extras_require
keyword arguments in setup.py
. This is
based on following the best practices recommended in the Python packaging guides.
Adding a package to the requirements¶
The process outlined below should be adhered to when adding a package to any of the requirements categories.
Identify the package needed and consider why it is needed in addition to the current requirements. If it is a large package or involves many source code changes to accommodate it, then submit an issue to the Issue Tracker before continuing.
Determine the minimum / maximum version of the package required to run the code that you are adding / changing. You should verify that tests pass with the additional package on your local machine - see Running and writing tests.
Ascertain the category that the requirement falls under - i.e. if it is a package needed for a new documentation feature then it should be added to the
requirements-doc.txt
file.Add the package name and pinned version to the relevant requirements file. For example, if the package is called
foo
and the version you want people to use isv1.1.0
then add the line:foo == 1.1.0
to the associated requirements file.
Add the package name without the pinned version to
the
REQUIRES
list insetup.py
if it is a core package required to run Finesse ORthe
EXTRAS
dict insetup.py
if it is any other type of package.
Changing the pinned version of a requirement¶
Follow the process below to modify the version of an existing requirement.
Identify the package version to modify and consider why you need to change the required version. If it is a core package used frequently (e.g.
NumPy
) then submit an issue to the Issue Tracker before continuing.Determine the version you want to change the requirement to. This can be a minimum version, maximum version or pinned at some specific version number.
Find the package name in the correct requirements file and modify the version number and condition to the value determined from the previous step. For example, if the package is called
foo
and the current pinned version isv1.1.0
then the line in the requirements file will be:foo == 1.1.0
If you want to change this to a minimum version of
v1.3.0
then this line should be changed to:foo >= 1.3.0
Verify that the test suites pass with the package version changed on your local machine - see Running and writing tests - before attempting to merge the changes.
Removing a required package¶
Occasionally, we may want to remove a package from the requirements if it is no longer used (typically when a better solution to some problem has been found using a new / existing package). In this case, the process outlined here should be followed for removing the package.
Identify the package to remove and consider why it should be removed. If it is a large package or involves many source code changes to accommodate it, then submit an issue to the Issue Tracker before continuing.
Ascertain the category that the requirement falls under - i.e. if it was a package needed for a feature of Finesse itself then it should be removed from the
requirements.txt
file.Remove the line containing the package name from the relevant requirements file.
Delete the line containing the package name from
the
REQUIRES
list insetup.py
if it is a core package required to run Finesse ORthe
EXTRAS
dict insetup.py
if it is any other type of package.
Verify that the test suites pass with the package removed from your local machine - see Running and writing tests - before attempting to merge the changes.