Generating a Repository using a Template

Last updated on 2025-04-14 | Edit this page

Estimated time: 12 minutes

Overview

Questions

  • What is the fastest way to set up a new Python repository that suits your needs?
  • How do you make sure this repository follows best practices?

Objectives

  • Explain why you should use a template to start a new repository
  • Demonstrate how to create a repository using the NLeSC Python Template
  • Demonstrate how to use the upgrade feature of [copier] to extend your repository with extra features

Why use a template?

No matter how (in)experienced a programmer you are, using a template when starting a new project is always a good idea. Templates let you easily make use of the latest and greatest in best practices, without having to reinvent the wheel for every project.

As someone who is new to programming, employing a template can help you to setup your first projects and help you adhere to coding standards such that your software can be understood by others. In general employing templates saves time and helps to prevent confusion when copy pasting from old repositories. E.g. parameters and specific configurations are easily overlooked and not being edited.

In both cases, using a trusted template will save you time, worries and make sure your new projects are never outdated from the start.

Using pipx to install copier is recommended, so it doesn’t pollute the global environment of the user, and so they don’t have to install it in their (not-yet-existant) project space. It’s only recommended to let participants deviate from this advice and directly pip install copier if they (confidently) know what they’re doing.

A popular tool for using and applying templates is the Python tool [copier]. Using copier, you can create a project based on a template made by yourself or someone else. Templates can be configured to ask you some questions for details that copier will then fill in throughout the files to personalize it to suit your needs.

The recommended way to install copier as a local tool is using pipx:

BASH 

python3 -m pip install --user pipx
python3 -m pipx --ensurepath
pipx install copier

Now you can use copier as a standalone tool to create new projects.

Challenge 1: Use the NLeSC Python Template

Create a new project based on the Python template by the Netherlands eScience Center:

BASH 

copier copy gh:nlesc/python-template path/for/your/project

Challenge 1: Use the NLeSC Python Template (continued)

Callout

Copier can create a project from a local folder and from a remote git repository URL such as https://github.com/nlesc/python-template.git. The following shortcut URLs are also supported:

  • GitHub: gh:namespace/project
  • GitLab: gl:namespace/project

Notice how you are asked to answer a lot of basic information that you already filled in for the SMP in the previous episode.

Challenge 2: Reuse machine readable SMP tool output

The SMP tool provides a machine readable yaml file with all relevant answers for creating a new project using this template. First remove the previous project to make sure everything stays clean:

BASH 

rm -rf path/to/destination

BASH 

copier copy --answers-file smp_answers.yaml gh:nlesc/python-template path/for/your/project

Challenge 1: Use the NLeSC Python Template (continued)

Note how you were asked a lot fewer questions this time! Part of this is simply filling in the information you already entered in the SMP. For the other questions you weren’t asked, the SMP tool has already suggested which set of optional features best suit your project.

Due to the limitation how copier handles the answer files, you cannot review choices you made in the SMP. In the next section, you will see how you can add or change features of your code repository.

Challenge 3: Add more features to your project

Move to your project folder and use copier’s update functionality to change your email address. - What do you have to do to your project before you can use copier update? - Why is this useful/needed? - Which questions are you asked this time? - How are the changes applied and how can you manage which ones to accept?

As mentioned, you must first move to your project folder before copier update can work.

BASH 

cd path/for/your/project

If you then immediately try to update your project, you will run into an error:

BASH 

$ copier update

Updating is only supported in git-tracked subprojects.

  1. So, what you must do is place your project under version control using git. You can do so with the following commands, assuming you already have your name and email configured.

BASH 

git init
git add .  # add everthing for the first commit
git commit -m "Initial commit"
  1. When updating, copier will overwrite any of your local files with new information. With your project under version control, you can safely update your project and easily ignore any updates by restoring the old contents of your files.

BASH 

copier update

  1. Note that you are asked the full set of questions again, but all your previous answers are already filled in.

  2. After completing the questions, you can use git status to see which files have been changed, and git diff to inspect the exact changes.

Key Points

  • Use a template to implement best practices for you from the start
  • Create a new repository using copier copy gh:nlesc/python-template path/for/your/project
  • Re-use the information from your SMP with the additional --answers-file smp_answers.yaml argument
  • Change answers or extra features to your project using copier update