Skip to content

UCL-ARC/python-tooling

Repository files navigation

UCL ARC Python tooling logo

UCL ARC Python Recommendations

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.

Contributors

Patrick J. Roddy
Patrick J. Roddy

πŸ€” πŸ› πŸ’» πŸ–‹ πŸ“– πŸ“‹ πŸ“† πŸ’¬ πŸ‘€ πŸ“’ ⚠️
Sam Cunliffe
Sam Cunliffe

πŸ€” πŸ› πŸ’» πŸ–‹ πŸ“– πŸ“‹ πŸ“† πŸ’¬ πŸ‘€ πŸ“’ ⚠️
David Stansby
David Stansby

πŸ€” πŸ› πŸ’» πŸ–‹ πŸ“– πŸ“‹ πŸ“† πŸ‘€ ⚠️
Matt Graham
Matt Graham

πŸ› πŸ’» πŸ–‹ πŸ“– 🎨 πŸ“‹ πŸ‘€ πŸ“’ ⚠️
sfmig
sfmig

πŸ› πŸ’» πŸ–‹ πŸ‘€ ⚠️
Paul Smith
Paul Smith

πŸ› πŸ’» πŸ–‹ πŸ“– πŸ’¬ πŸ‘€ ⚠️
Renovate Bot
Renovate Bot

🚧
ruaridhg
ruaridhg

πŸ› πŸ’» πŸ–‹ πŸ‘€
Miguel Xochicale, PhD
Miguel Xochicale, PhD

πŸ› πŸ’» πŸ–‹ 🎨 πŸ“– πŸ‘€
yidilozdemir
yidilozdemir

πŸ“– ⚠️
Mosè Giordano
Mosè Giordano

πŸ› πŸ“– πŸ‘€
Tom Young
Tom Young

πŸ› πŸ–‹ πŸ‘€
Alessandro Felder
Alessandro Felder

πŸ› πŸ–‹
Adam Tyson
Adam Tyson

πŸ–‹
Will Graham
Will Graham

πŸ–‹ πŸ‘€
nikk-nikaznan
nikk-nikaznan

πŸ–‹
Katie Buntic
Katie Buntic

πŸ–‹
Robert Vickerstaff
Robert Vickerstaff

πŸ“–
David PΓ©rez-SuΓ‘rez
David PΓ©rez-SuΓ‘rez

πŸ’» πŸ’¬
llapira
llapira

πŸ›
pre-commit.ci
pre-commit.ci

🚧

Using this template

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.

  1. Install cookiecutter in a uv venv or conda environment (commented lines for uv venv example).

    # uv venv  # creates a .venv directory wherever you are
    # source ./.venv/bin/activate
    uv pip install cookiecutter
  2. Run cookiecutter in the desired directory

    cookiecutter gh:ucl-arc/python-tooling --checkout latest

    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 --checkout latest
  3. 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.

  4. 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
  5. To work on your project, initialise a Git repository and install it in editable mode.

    cd PROJECT_SLUG
    git init
    uv pip install -e ".[dev]"
  6. Build your package

    python -m build

Notes for developers

Click to expand...

First, clone repository

  • (Optional) Generate your SSH keys as suggested here
  • (Optional) GitHub CLI as suggested here
  • Clone the repository by typing (or copying) the following line in a terminal at your selected path in your machine:
git clone git@github.com:UCL-ARC/python-tooling.git
cd python-tooling

Developing the cookiecutter template

  • To create and remove your virtual environment

    uv venv
    source .venv/bin/activate
    # do your work
    deactivate
  • To run template in the same path of this repo. We do a test cookiecut of a dummy package and install it to ensure the template setup works.

    cookiecutter .
    cd python-template
    git init
    uv pip install -e ".[dev]"
  • To run cookiecutter using a specific branch of the template:

    cookiecutter https://github.com/UCL-ARC/python-tooling --checkout <branch-name>
  • To run the tests locally:

    pytest -s

Developing the recommended tooling pages

Pages all live in the docs/pages sub-directory, and are written in markdown.

To build the webpage locally (for testing)

  1. Install jekyll
  2. Run bundle install from the docs/ directory of this repository to install dependencies.
  3. Run bundle exec jekyll serve from the root directory of this repository. This should fire up a local web server and tell you its address. By default the server will automatically refresh the HTML pages if any changes are made to the markdown sources.

See the jekyll docs for more info.