Py-Pkgs-Cookiecutter

py-pkgs-cookiecutter is a cookiecutter template for creating a fully-featured Python package using poetry. It supplements the Python Packages book by Tomas Beuzen and Tiffany Timbers but can be used independently.

Features

py-pkgs-cookiecutter includes the following core features:

• pytest testing: Setup to easily test for Python 3.7 & 3.8 (other Python versions can be added by editing the GitHub Actions workflow file) across ubuntu, mac and windows operating systems

• GitHub Actions: Ready for GitHub Actions Continuous Integration testing & Deployment

• codecov: Code coverage report and badge using codecov and GitHub Actions

• Sphinx docs: Documentation ready for generation with, for example, ReadTheDocs

• Python-semantic-release: Pre-configured version bumping upon merging pull request to main

• Auto-release to testPyPI upon merging pull request to main

Quick Start

Install cookiecutter:

pip install cookiecutter

Generate a Python package structure using py-pkgs-cookiecutter:

cookiecutter https://github.com/py-pkgs/py-pkgs-cookiecutter.git

pkg
├── .github                    ┐
│   └── workflows              │ GitHub Actions workflow
│       └── ci-cd.yml          ┘
├── .gitignore                 ┐
├── .readthedocs.yml           │
├── CHANGELOG.md               │
├── CONDUCT.md                 │
├── CONTRIBUTING.md            │
├── docs                       │
│   ├── make.bat               │
│   ├── Makefile               │
│   ├── requirements.txt       │
│   ├── changelog.md           │
│   ├── conduct.md             │
│   ├── conf.py                │ Package documentation
│   ├── contributing.md        │
│   ├── index.md               │
│   └── usage.ipynb            │
├── LICENSE                    │
├── README.md                  ┘
├── pyproject.toml             ┐ 
├── src                        │
│   └── pkg                    │ Package source code, metadata,
│       ├── __init__.py        │ and build instructions 
│       └── pkg.py             ┘
└── tests                      ┐
    └── test_pkg.py            ┘ Package tests

Parameters

When generating a Python package structure using py-pkgs-cookiecutter, you will be prompted for the input parameters shown below.

Description of py-pkgs-cookiecutter configuration parameters.

Parameters	Default value	Description
author_name	Monty Python	Your name.
package_name	mypkg	Package name (check if your name is already taken here).
package_short_description	A package for doing great things!	Brief description of your project.
package_version	0.1.0	Initial package version. In semantic versioning 0.1.0 is used for the initial version release.
python_version	3.9	Minimum Python version your package will support.
open_source_license	MIT	License to use for your package.
include_github_actions	no	Whether to include a GitHub Actions workflow file for CI or CI/CD.

Learn More

To learn more, checkout the sections below.

Quick Start User Guide Python Packages Book Contributing Guidelines

Acknowledgements

py-pkgs-cookiecutter was originally developed for use in the University of British Columbia’s (UBC) Master of Data Science_ program (MDS). It was inspired by the pyOpenSci cookiecutter template.