Netherlands eScience Center Python Template

Spend less time setting up and configuring your new Python packages and comply with the Netherlands eScience Center Software Development Guide from the start.

Use this Copier template to generate an empty Python package. Features include:

• Boilerplate unit tests and documentation,
• Python static setup configuration,
• Open source software license,
• Continuous integration with GitHub action workflows for building, testing, link checking and linting,
• Code style checking with ruff,
• Editorconfig,
• Usage and contribution documents:
  • README.md for package users,
  • README.dev.md for package developer,
  • project_setup.md with extensive documentation about project setup,
  • Change log,
  • Code of Conduct,
  • Contributing guidelines,
• Continuous code quality and code coverage reporting using Sonarcloud,
• Automatic creation of issues with instructions how to pass all GitHub action workflows and integrate with services like Zenodo and Read the Docs,
• Instructions how to make package citable
• FAIR software recommendation badge,
• Optional pre commit hook to catch lint errors early

Badges

fair-software.nl recommendations
(1/5) code repository
(2/5) license
(3/5) community registry
(4/5) citation
(5/5) checklist
overall
Other best practices
GitHub Actions
Citation metadata consistency
MarkDown link checker
Tests

How to use

There are multiple scenarios to use this template:

• Scenario 1: Generating a new package using template
• Scenario 2: Applying the template to some pre-existing code
• Scenario 3: Updating a package made with the template

In all three scenarios, you will need to install Copier first, which we recommend doing with pipx:

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

Note

Note that it is also possible to install Copier with regular pip, but that Copier will then be installed in your common environment and may cause conflicts with its dependencies, while pipx will install Copier in a separate and dedicated environment.

Scenario 1: Create a new package

Step 1/2: Create the files and directory structure

Run copier copy with the template:

# Notes:
#   1. Make sure that `path/to/destination` is an empty directory
#   2. See table below for explanation of each question
#   3. The files will be generated in the specified destination directory
copier copy https://github.com/nlesc/python-template.git path/to/destination

Name	Default value	Explanation
package_name	my_python_package	Name of the package. Avoid using spaces, dashes, or uppercase letters for the best experience across operating systems. This also will be used as the github repository name.
package_short_description	Short description of package	The information that you enter here will end up in the README, documentation, license, and pyproject.toml, so it may be a good idea to prepare something in advance.
keyword1	keyword1	A term that describes your package.
keyword2	keyword2	Another term that describes your package.
version	0.1.0
github_organization	<my-github-organization>	GitHub organization that will contain this project's repository. This can also be your GitHub user name.
license	Apache Software License 2.0	The software license under which the code is made available.
full_name	Jane Smith	Your full name, e.g. Jane Smith.
email	yourname@esciencecenter.nl	Your (work) email address.
copyright_holder	Netherlands eScience Center	Name(s) of the organization(s) or person(s) who hold the copyright of the software.
code_of_conduct_email	yourname@esciencecenter.nl	Email address of the person who should be contacted in case of violations of the Code of Conduct.

Once the project files have been generated, follow the steps outlined in next_steps.md.

Step 2/2: Read about what was just generated

Good job! You have now generated the skeleton for your package:

.
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── .copier-answers.yml
├── docs
│   ├── conf.py
│   ├── index.rst
│   ├── make.bat
│   ├── Makefile
│   └── _templates
│       └── .gitignore
├── .editorconfig
├── .githooks
│   └── pre-commit
├── .github
│   ├── next_steps
│   │   ├── 01_sonarcloud_integration.md
│   │   ├── 02_citation.md
│   │   ├── 03_readthedocs.md
│   │   ├── 04_zenodo_integration.md
│   │   └── 05_linting.md
│   └── workflows
│       ├── build.yml
│       ├── cffconvert.yml
│       ├── documentation.yml
│       ├── markdown-link-check.yml
│       ├── next_steps.yml
│       └── sonarcloud.yml
├── .gitignore
├── MANIFEST.in
├── .mlc-config.json
├── next_steps.md
├── NOTICE
├── project_setup.md
├── pyproject.toml
├── README.dev.md
├── README.md
├── .readthedocs.yaml
├── sonar-project.properties
├── src
│   └── my_python_package
│       ├── __init__.py
│       └── my_module.py
├── tests
│   ├── __init__.py
│   ├── test_my_module.py
│   ├── test_project.py
│   └── test_values.py
└── .zenodo.json

For an explanation of what's there, read on in the project_setup.md file.

Scenario 2: Apply to pre-existing code

To apply the template to pre-existing code, you can use the same copier copy command as when creating a new package, except that you point to the folder containing your existing code rather than a new one:

copier copy https://github.com/nlesc/python-template.git path/to/existing/code

This works because if path/to/destination already exists, Copier will update what is already there by either adding new files or updating existing files. Copier will ask to overwrite any files that resulted in conflicts. Especially if your files are already under version control, it is recommended to answer 'yes' for all files, you will still be able to review the changes suggested by the template.

Scenario 3. Updating a template-made package

Copier provides the functionality for re-applying the template to a previously created project using the copier update command. This has two effects:

1. Your project will be updated according to the latest version of the template
2. You can change any of your previous answers to apply these changes throughout your entire project.

Caution

Do not manually update answers in .copier-answers.yml, as it will result in unexpected behavior.

cd path/to/project
copier update

If you don't want to change any of your answers, but only want to update your project according to the latest template updates, you can provide the --skip-answered option. This tells Copier to reuse all of your previous answers, and simply bring in all updates from the template into your current project, such as updating which Python versions are supported. You will still be asked to answer any new questions that have been added to the template since you last applied it.

copier update --skip-answered

Examples

Many developers have gone before you in using this template to get started quickly. Check out their projects in the list below:

1. Cerise: https://github.com/MD-Studio/cerise
2. cerulean: https://github.com/MD-Studio/cerulean
3. cffconvert: https://github.com/citation-file-format/cff-converter-python
4. fairtally: https://github.com/fair-software/fairtally
5. howfairis: https://github.com/fair-software/howfairis
6. matchms: https://github.com/matchms/matchms
7. MUSCLE 3: https://github.com/multiscale/muscle3
8. pycff: https://github.com/citation-file-format/pycff
9. spec2vec: https://github.com/iomega/spec2vec
10. yatiml: https://github.com/yatiml/yatiml
11. ... And many more (see this discussion). Make a PR to add your project here, or simply ping us in an issue!

How to contribute

Suggestions/improvements/edits are most welcome. Please read the contribution guidelines before creating an issue or a pull request.