https://github.com/andgineer/cookiecutter-python-package
Cookiecutter template for Python package with GitHub actions to publish on PiPy and with mkdocs material.
https://github.com/andgineer/cookiecutter-python-package
cookiecutter invoke mkdocs-material package python
Last synced: 7 months ago
JSON representation
Cookiecutter template for Python package with GitHub actions to publish on PiPy and with mkdocs material.
- Host: GitHub
- URL: https://github.com/andgineer/cookiecutter-python-package
- Owner: andgineer
- License: mit
- Created: 2023-12-14T10:00:18.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-11T09:59:50.000Z (9 months ago)
- Last Synced: 2025-05-11T10:34:08.381Z (9 months ago)
- Topics: cookiecutter, invoke, mkdocs-material, package, python
- Language: Python
- Homepage:
- Size: 670 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Python Package Project Template
This Cookiecutter template generates a Python project structured for package development. It includes a suite of tools and workflows for high-quality software development and easy package distribution.
## Features
- **Python Package Setup**: Scaffold for creating a Python package.
- **Virtual environment**: Convenient creation/activation with a single command. Optionally use blazingly fast `uv`. Alternatively supports Anaconda envs.
- **Aux scripts**: Optionally Python scripts with Invoke or BASH with Makefile.
- **GitHub Actions for CI**: Automated workflows for Continuous Integration.
- **Publishing to PyPI**: Workflow for packaging and distributing your project on [PyPI](https://pypi.org/).
- **Static Analysis**: Pre-configured Flake8, Black, and MyPy checks. Use incredibly fast `ruff`.
- **Coverage Reporting**: Code coverage analysis with results published to a separate branch, integrated with Coveralls/Codecov.
- **Badges in README**: Status badges for CI and coverage.
- **Pre-commit Hooks**: Pre-configured hooks for code formatting and MyPy checks.
- **Dependency Management**: Using pip-tools with automated updates in `pyproject.toml` or using `uv lock`.
- **Version Management**: Makefile commands for package version management.
- **Documentation**: Multilanguage documentation with MkDocs Material, published on GitHub Pages.
## How to Use This Template
To create a new project from this template, you'll need to have Cookiecutter installed.
If you don't have Cookiecutter installed, you can install it with
[pipx](https://pipx.pypa.io/latest/installation/):
```bash
pipx install cookiecutter
```
Once Cookiecutter is installed, generate your project:
cookiecutter gh:andgineer/cookiecutter-python-package
Follow the prompts to enter your project details.
My personal preference is to create empty project first on GitHub and then clone it to my local machine.
Then without entering the project directory
cookiecutter gh:andgineer/cookiecutter-python-package --overwrite-if-exists
Of course the project name you enter should be the same as the name of the repository on GitHub.
This way it creates all the boilerplate in the project directory but leave `.git/` you just cloned intact.
You can then push the boilerplate created by cookiecutter back to the GitHub.
## Post-Generation Setup
After generating your project, perform the following steps:
### PyPI Credentials
Set up your PyPI credentials as GitHub Secrets for automated package publishing:
- Go to your GitHub repository's Settings.
- Navigate to 'Secrets'.
- Add the following secrets:
PYPI_USERNAME: Your PyPI username.
PYPI_PASSWORD: Your PyPI password.
### GitHub Pages
Enable GitHub Pages for your project's documentation:
- Go to your GitHub repository's Settings.
- In the 'Pages' section, set the source to the gh-pages branch.
### Optional Configurations
- Coveralls Integration: Activate your project on Coveralls.
- Codecove:
press `Configure` on appropriate project on [codecov.io](https://app.codecov.io/gh/andgineer).
activate the project in the codecov settings.
given on the page `CODECOV_TOKEN` add to GitHub Secrets.
Alternatively you can use `Global upload token` in settings - it will work for all projects.
## How to use generated project
### Docs
Doc autogenerated and published on Github Pages from markdown files in `docs` folder.
Also from docstings autogenerated API reference.
See link in README.md.
### Dependencies
To create virtualenv run `. ./activate.sh` in the root of the project (note the first ".").
You need [uv](https://pypi.org/project/uv/) installed for this.
If you change dependencies in `requirements.in` or `requirements.dev.in` run `make reqs` to update
`requirements.txt`, `requirements.dev.txt` and `pyproject.toml`.
This also will update dependencies in the virtualenv.
### Black & mypy
To activate autoformatting and mypy checks run `pre-commit install` in the root of the project.
### Publishing package in pip
To publish the package on PyPi just set git tag with `make ver-feature` etc,
see `make help` for details. After that the Github action will publish the package on PyPi
and add link to the version into Github release.