Developer guides – PIP packaging

We have bundled our recommerce simulation framework as a local pip package (meaning it is only available for installation if you have access to the source code, it is not available through indices such as pypi).

For guidance on how to install the package, please take a look at our README.

• Relevant files

Relevant files

The pip package is configured through three major files:

• pyproject.toml
• setup.cfg
• setup.py

pyproject.toml

Aside from various configuration for our testing and linting tools, the pyproject.toml file also contains various items needed for the build process of the pip package. Under normal circumstances, you will not have to change anything in this file when working with the package.

setup.cfg

The setup.cfg file contains most of the metadata and configuration for the installation process of the package. The items under the category [metadata] are self-explanatory, so we will not go into detail on how to change them.

Under the [options] category, the most important item is the install_requires list, which lists the dependencies of our package, including preferred and minimum versions. When adding a new dependency that is needed for running the package, you need to add it to this list. If the dependency is needed only for developers (e.g. pytest), add it to the environment.yml file instead.

The next category, [options.extras_require] defines the two versions of our package. Due to the way the pip packaging process works, users always need to choose one of these versions to be able to run the package, otherwise the framework will not work due to the torch dependency missing. The two options currently available are cpu and gpu, which should be chosen dependent on the availability of cuda on the respective machine, also see the README for more information on this topic.

The next category, [options.entry_points], defines the entrypoints for the package. Currently, we have one defined entrypoint, recommerce, which, if called through the console, will invoke the main() function of the main.py file.

Anything below this category is not important for the configuration of the package but regarding dependencies that also use this file for their configuration.

setup.py

The setup.py acts as the entrypoint for the pip build process. Aside from the standard build process, there are two tings we do on top:

• Adding default files to the package: Through the package_files() function, we make sure that not only .py files are included in the package, but all files within the recommerce/ folder. This makes sure that our default files (.json, .dat etc.) are included in the package.
• The user_path.txt: This file contains the user's datapath. Since many developers will have a locally installed copy of the package which contains their own datapath, we have decided to overwrite this file during the build process with a new, empty version of itself. This makes sure that the developer's own datapath is never included in the pip package.