Python Cookiecutter Template

This is a Cookiecutter template for creating a Python project with Poetry, including configurations for various project settings.

Table of Contents

• Introduction
• Installation
• Usage
• Configurations
  • Package manager - Poetry
  • Linters and formatters - Ruff
  • Spell checker - Typos
  • Static type checker - Mypy
  • Documentation - Sphinx
  • Testing - pytest and pytest-cov
• CI/CD - GitHub Actions
• Disclaimer
• Contributing
• Code of Conduct
• Versioning
• License
• Contact

Usage

1. Install Cruft (if you haven't already):

pip install cruft

2. Generate a New Project:

cruft create https://github.com/elixir-cloud-aai/cookiecutter-python.git

3. Commit and push the generated files (as applicable to your Git workflow)

Inside the generated project directory:

git add .
git branch -m main
git commit -m "chore(init): initialize project with https:github.com/elixir-cloud-aai/cookiecutter-python.git"

Push the code to the remote repository:

git remote add origin <your-repo-url>
git push -u origin main

Note: If you want to push your code to GitHub and make use of the generated GitHub Actions workflows, we recommend you to set up the necessary secrets before pushing the code. Otherwise some of workflows may fail.

Don't wanna use Cruft?

You can also use the cookiecutter command directly:

1. Install cookiecutter (if you haven't already):

pip install cookiecutter

2. Generate a New Project:

cookiecutter gh:elixir-cloud-aai/cookiecutter-python

Note: If you're using just cookiecutter, manually remove update-template job from update.yaml github action workflow file as cookiecutter doesn't support autosync like Cruft.

Configurations

Package manager - Poetry

This project uses Poetry as a package manager. Check out the commands at the official documentation.

Linters and formatters - Ruff

To lint and format Python code files, it uses Ruff, the default configuration is set in the pyproject.toml file.

select = [
  "B", # flake8-bugbear
  "E", # pycodestyle
  "F", # Pyflakes
  "I", # isort
  "PL", # pylint
  "SIM", # flake8-simplify
  "UP", # pyupgrade
]

To configure it to your needs, refer to the [rules documentation][ruff-linter] , and for formatter configuration, refer to the configuration documentation.

Spell checker - Typos

If you want to ignore certain words, add them to the pyproject.toml file, under the tool.typos.default.extend-words key.

[tool.typos.default.extend-words]
mke = 'mke'

For further configuration, refer to the typos docs.

Static type checker - Mypy

Change the configuration in pyproject.toml file, for further information refer to the documentation.

Documentation - Sphinx

Configuration for Sphinx is in the docs/source/conf.py file, for further info refer to the Sphinx documentation. The default configuration uses furo theme and ReadTheDocs to host the documentation, you can change the configuration using /docs/source/conf.py and .readthedocs.yml file.

Note: Make sure to set up the ReadTheDocs account and add the projects to the account to host the documentation.

Testing - pytest and pytest-cov

Generate a coverage report using pytest-cov and uploads it to codecov.io.

Note: Make sure to set up the Codecov account and add the project to the account to host the coverage report and add github token.

CI/CD - GitHub Actions

Here are the GitHub Actions Secrets that need to be included in the repository settings:

• PYPI_TOKEN: PyPI account password.

  Note: PyPI account token scoped to this repository (requires the project to exist prior to using the Cookiecutter) or to all repositories. To set up the token, visit https://pypi.org, log in, go to Account settings in the user menu and hit the Add API token button in the API tokens section. Add a name, choose the scope and create the token.

• CODECOV_TOKEN: Codecov token.

  Note: To set up the token, visit https://codecov.io/, log in, find the repository that you want to set up (you may need to "Resync") and hit the "Configure" button. The token should show up in the "Coverage" tab.

• GITHUB_TOKEN: This token is auto-generated by GitHub Actions for each job, so please do NOT set it manually.

  Note: The token needs to be granted the authority to create pull requests. See GitHub for details on how to set this permission.

Disclaimer

Some of the links and images have been hardcoded with ELIXIR Cloud & AAI's assets in the documentation, please update them manually if needed. These assets MUST be included for projects owned by ELIXIR Cloud & AAI, but MUST NOT be included for projects that are not (personal projects, projects owned by other orgs).

Only markdown files and images/ directory need to be changed.

Contributing

This project is a community effort and lives off your contributions, be it in the form of bug reports, feature requests, discussions, fixes or any other form of contribution!

Please refer to the guidelines available at CONTRIBUTING.md if you are interested in contributing.

Code of Conduct

We kindly request all contributors to abide by our organization's Code of Conduct. Please also refer to this document if you want to report an incident with respect to conduct in our community. Thank you for your cooperation.

Versioning

The project adopts the semantic versioning scheme for versioning. Currently the service is in a pre-release stage, so changes to the API, including breaking changes, may occur at any time without further notice.

License

This project is distributed under the Apache License 2.0, a copy of which is also available in LICENSE.

Contact

The project is maintained by ELIXIR Cloud & AAI, a Driver Project of the Global Alliance for Genomics and Health (GA4GH), under the umbrella of the ELIXIR Compute Platform.

To get in touch with us, please use one of the following routes:

• For filing bug reports, feature requests or other code-related issues, please make use of the project's issue tracker.
• For private/personal issues, more involved communication, or if you would like to join our team as a regular contributor, you can either join our chat board or email the community leaders.