A generic blank Python project

This repo provides a scratch of a Python project. Its purpose is to serve as starting point for the development of a Python project based on a minimal working structure.

Covered features

• A Python package organized following the src-layout;
• A preconfigured pyproject.toml file following the suggestions from the Official Python Packaging docs;
• GitHub Actions convenient workflows with minimal configurations for the latest Ubuntu, macOS, and Windows;
• Tests with pytest, integrating Python notebooks as tests together with the usual test_*.py files;
• Development environment with two options:
  • The classic venv
  • A conda/miniconda environment with conda-devenv extension
• Hierarchical structure to a Python package inspired by PyPA recommendations. See also the Official Python docs;
• A MkDocs for nice-looking and modern docs (at least at the moment that you are reading this). A GH Actions workflow is provided to automatically update the docs after each PR based on docstrings and Jupyter Notebooks. See the Docs website here;
• pre-commit to perform git hooks before commits. A GH Actions workflow is provided to check and update the hooks on a weekly basis, opening PRs by github-actions[bot]. The following plugins are being used as git hooks:
  • trailing-whitespace
  • end-of-file-fixer
  • ruff
  • blacken-docs
  • nb-clean
  • jupytext
• A free Coverage reporter using this Action. It comments on PR, annotates where there is a lack of coverage, and provides coverage badges in a dedicated branch after PRs;
• Type-checking with mypy;
• A bunch of convenient tasks to improve productivity defined using invoke;
• Automated Python Package releases to PyPI through Pre-Release PRs using git tags. The release is uploaded using this official GH Action;
• A PR automerge workflow (based on this GH Actions) for when a PR is ready to go with all reviews, code changes, and checks done. Just label the PR with automerge and see the magic;
• Use conda-lock when working with conda envs, assuring fully reproducible envs for Windows, Ubuntu, and MacOS. A GH Actions workflow is also provided to update conda-lock files on a weekly basis, opening PRs with updates whenever needed;
• Run CodeQL to analyze the code and report security issues;
• Dependabot is configured to watch and send PRs updating the GH Actions versions.

Contributions

Contributions are VERY welcome. But please be aware of the purpose of the repo: A minimal working structure. If you want to add a feature that is very particular to your needs, please analyse if it fits the goals of this template.

Suggestions and advice are welcome; feel free to open an Issue or send me an email.

Contact

My name is Diego. Feel free to contact me through the email [email protected].