Skip to content

Audience and usage#

Audience#

This template is for people who just want a quick setup to do work with Python with a reproducible/shareable environment.

We make a few choices in this template, which are worth being aware of:

  • we avoid anything that could cause headaches for quick work like type checking with mypy or strict linting with ruff (these tools are great, but not for a quick repo that isn't intended to be long-lived)
  • we add a basic .gitignore which avoids tracking large files etc. This is worth checking as there are some trade-offs in terms of tracking (for more thoughts, see trade-offs: repository size and data distribution)
  • we add a basic README with some helpful fields. You can add whatever details you like to the README (for more thoughts on documentation, see theory: docs)
    • We explicitly choose not to add a docs folder for this simple template as the README should be sufficient (and if the project scope grows to the point that it cannot be documented in the README, you will need to change the repository's structure anyway)

Who isn't this repository for?#

This repository is for quick analysis and proto-typing. It will get you up and going fast and make it possible for you to share your environment with others (so they have a decent chance of being able to re-run your work) and to re-create your environment later if you ever need. If you are doing anything other than this, you will probably want a different solution. For example, this template won't set you up with any of the things you need for more complex work (but it also won't give you the headaches that come with these more complex tools), e.g. developing a core Python package (for that, see our core package template) or help you manage an involved analysis workflow involving handling data in a traceable, portable way (for that, see [TODO link once made]). Having said that, it may make sense to start with this structure, then migrate to a different repository structure once you have a clearer idea of what you are doing.

Usage#

Installing copier#

It is expected that copier is installed globally. pipx can be used to install copier in its own isolated environment.

pipx install copier

Creating a new repository#

Note: if any of the below doesn't work, the copier docs are here and the section specifically on creating repositories is here. If you find a mistake, please raise an issue.

To start a new repository run copier with the template:

copier copy --trust gl:openscm/copier-basic-python-repository path/to/destination/repository

Copier will ask you the required questions and then setup your repository for you.

Alternatively, if you have the template repository cloned locally, the path to the repository can be used instead of gl:openscm/copier-basic-python-repository, like so

copier copy --trust path/to/copier/template/repo path/to/destination/repository

Copier will use the latest tagged release of this template for generating a new project. If you wish to use a specific commit/tag, the --vcs-ref flag can be used (--vcs-ref HEAD will use the most recent commit of the template). For example,

copier copy --trust gl:openscm/copier-basic-python-repository --vcs-ref v1.2.1 path/to/destination

Keeping repositories up to date with updates to the copier template#

Note: if any of the below doesn't work, the copier docs are here and the section on updating repositories is here. If you find a mistake, please raise an issue.

If you need to update your repository, navigate to your repository and run:

copier update

If you don't want to go through all the questions again (the default answers are taken from last time you answered the questions), use

copier --force update

By default, copier will use the most recent tag when updating the repository. If you wish to use the current HEAD commit for your update, run

copier --vcs-ref=HEAD update

The --vcs-ref option can also be used to specify a specific tag to apply.

Handling conflicts#

When you update, there will likely be merge conflicts, particularly in pyproject.toml related to versions. We recommend simply using the .rej files as we have found these to be simpler (command-line option: --conflict rej). If you use the --conflict inline option with copier update then the diffs should be inline (this is apparently experimental though, see here). These diffs can then be resolved manually. The pre-commit config will make sure you don't miss conflicts and accidentally commit merge conflict lines. As a final option, if things get really stuck, you can use the copier recopy command. This gets rid of the smart updated done by copier update, so more work is required by you but this command cannot get stuck in the same way the smart update can (full copier docs here).

Any conflicts related to package-manager lock files can be safely ignored. Run the lock command for your selected package manager after updating to regenerate the lockfile.