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 Cookiecutter 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 prospector,
- 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
| 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 |  |
We recommend installing cookiecutter in user space as per cookiecutter's instructions. This way, you don't have to
install cookiecutter for every new project.
python3 -m pip install --user --upgrade cookiecutterRun cookiecutter with the template:
# Notes:
# 1. See table below for explanation of each question
# 2. The files will be generated in a new directory
cookiecutter https://github.com/nlesc/python-template.git| Name | Default value | Explanation |
|---|---|---|
| directory_name | my-python-project | Name of the directory that contains the package. Avoid using spaces or uppercase letters for the best experience across operating systems. To get an impression of what will be generated, see the directory tree below |
| package_name | my_python_package | Name of the package. Avoid using spaces, dashes, or uppercase letters for the best experience across operating systems. |
| package_short_description | Short description of package | The information that you enter here will end up in the README, documentation, license, and setup.cfg, 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 protected] | 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 | [email protected] | 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 {{cookiecutter.directory_name}}/next_steps.md.
Good job! You have now generated the skeleton for your package:
my-python-project/
├── .bumpversion.cfg
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── docs
│ ├── conf.py
│ ├── index.rst
│ ├── make.bat
│ ├── Makefile
│ ├── _static
│ │ └── theme_overrides.css
│ └── _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
│ ├── lint.yml
│ ├── markdown-link-check.yml
│ ├── next_steps.yml
│ └── sonarcloud.yml
├── .gitignore
├── LICENSE
├── MANIFEST.in
├── .mlc-config.json
├── my_python_package
│ ├── __init__.py
│ ├── my_module.py
│ └── __version__.py
├── next_steps.md
├── NOTICE
├── project_setup.md
├── .prospector.yml
├── .pylintrc
├── pyproject.toml
├── README.dev.md
├── README.md
├── setup.cfg
├── setup.py
├── sonar-project.properties
└── tests
├── __init__.py
└── test_my_module.py
For an explanation of what's there, read on in the project_setup.md file. There are also instructions on how to apply the template to an existing Python package.
Many developers have gone before you in using this template to get started quickly. Check out their projects in the list below:
- Cerise: https://github.com/MD-Studio/cerise
- cerulean: https://github.com/MD-Studio/cerulean
- cffconvert: https://github.com/citation-file-format/cff-converter-python
- fairtally: https://github.com/fair-software/fairtally
- howfairis: https://github.com/fair-software/howfairis
- matchms: https://github.com/matchms/matchms
- MUSCLE 3: https://github.com/multiscale/muscle3
- pycff: https://github.com/citation-file-format/pycff
- spec2vec: https://github.com/iomega/spec2vec
- yatiml: https://github.com/yatiml/yatiml
- ... And many more. Make a PR to add your project here!
Suggestions/improvements/edits are most welcome. Please read the contribution guidelines before creating an issue or a pull request.