This repository collects the UCL ARC recommendations for a research software
project in Python. It contains a template for new Python packages and a
website documenting our recommendations. We've turned on
discussions for this
repo, and we welcome questions there or in the #helpme
channel on the
UCL research programming hub Slack.
πͺ Our template is a cookiecutter template which automatically creates new Python packages with our recommended tooling set up and ready to go.
Note If you're making a package within a community that has an existing package template (e.g.,
scikit-hep
), we recommend using their template instead of this one.
Some quick instructions for using our template are below. We also have a detailed tutorial that has been given in a couple of workshops geared towards researchers at UCL. The tutorial goes into much more pedagogical detail, it both describes using the template to create a package and how to use the newly created package with some of the tools included.
Install cookiecutter in a Conda or venv
environment (commented lines for
Conda example).
# conda create --channel conda-forge --name new-env-name
# conda activate new-env-name
# conda install pip
pip install cookiecutter
Run cookiecutter in the desired directory
cookiecutter gh:ucl-arc/python-tooling
If you have this repo locally (this may be the case if you are developing), you can run the following:
cookiecutter /path/to/your/checkout/of/python-tooling
A series of questions will pop up to configure the project. Type the answer or hit return to use the default option (shown in parenthesis).
Note that these project variables are defined in the cookiecutter.json
file.
This will create a specific directory structure.
For example, for a project with the following variables:
project_name [Python Template]: PROJECT_NAME
project_slug [python-template]: PROJECT_SLUG
package_name [python_template]: PACKAGE_NAME
we will get a project folder named PROJECT_SLUG
, structured like this:
PROJECT_SLUG
βββ ...
βββ README.md
βββ pyproject.toml
βββ src
β βββ PACKAGE_NAME
β βββ __init__.py
βββ tests
βββ test_dummy.py
And the PROJECT_NAME
will appear in the README.md as the human-readable
name of the project.
cat PROJECT_SLUG/README.md
# PROJECT_NAME
...
To work on your project, initialise a Git repository and install it in editable mode.
cd PROJECT_SLUG
git init
python -m pip install -e ".[dev]"
Build your package
python -m build