{"id":13572134,"url":"https://github.com/ryankanno/cookiecutter-py","last_synced_at":"2026-01-23T05:56:33.607Z","repository":{"id":31564367,"uuid":"35129098","full_name":"ryankanno/cookiecutter-py","owner":"ryankanno","description":"🐍 Modern Python project Cookiecutter template","archived":false,"fork":false,"pushed_at":"2026-01-15T20:42:01.000Z","size":1787,"stargazers_count":7,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-15T21:48:18.241Z","etag":null,"topics":["cookiecutter","cookiecutter-template","python","uv"],"latest_commit_sha":null,"homepage":"https://ryankanno.github.io/cookiecutter-py/latest/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryankanno.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2015-05-05T23:33:02.000Z","updated_at":"2026-01-15T20:41:40.000Z","dependencies_parsed_at":"2023-12-07T11:31:17.412Z","dependency_job_id":"d607e92b-bb00-4a48-b117-18bb933c62ae","html_url":"https://github.com/ryankanno/cookiecutter-py","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ryankanno/cookiecutter-py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryankanno%2Fcookiecutter-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryankanno%2Fcookiecutter-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryankanno%2Fcookiecutter-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryankanno%2Fcookiecutter-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryankanno","download_url":"https://codeload.github.com/ryankanno/cookiecutter-py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryankanno%2Fcookiecutter-py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28681567,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T05:48:07.525Z","status":"ssl_error","status_checked_at":"2026-01-23T05:48:07.129Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cookiecutter","cookiecutter-template","python","uv"],"created_at":"2024-08-01T14:01:14.421Z","updated_at":"2026-01-23T05:56:33.601Z","avatar_url":"https://github.com/ryankanno.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003ch3 align=\"center\"\u003ecookiecutter-py\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003e🐍 Modern Python project Cookiecutter template\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python 3.10-3.13](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue.svg)](https://www.python.org/downloads/)\n[![GitHub Issues][github-issues-shield]][github-issues-url]\n[![GitHub Pull Requests][github-prs-shield]][github-prs-url]\n[![License][project-license-shield]][project-license-url]\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[**Explore the latest docs »**][project-docs]\n\n\u003c/div\u003e\n\n---\n\nEach time you start a new Python project, you shouldn't start from scratch.\nIdeally, you'd start with a standard project structure and set of tools and\nintegrations to help facilitate writing quality Python code.\n\nThis modern Python [Cookiecutter](https://github.com/audreyr/cookiecutter)\ntemplate is the tool that will help you do just that.\n\n---\n\n\u003c!-- FEATURES --\u003e\n## ✨ Features\n\n- [`uv`](https://github.com/astral-sh/uv) to manage dependencies\n- [`structlog`](https://www.structlog.org/en/stable) for logging\n- [`mypy`](https://mypy-lang.org) for static typing\n- [`pytest`](https://github.com/pytest-dev/pytest), [`hypothesis`](https://github.com/HypothesisWorks/hypothesis), [`mutmut`](https://github.com/boxed/mutmut) for testing\n\n  - [`pytest-cov`](https://pytest-cov.readthedocs.io/en/latest/) for coverage reports\n  - [`pytest-mock`](https://github.com/pytest-dev/pytest-mock/) for mocks\n  - [`pytest-xdist`](https://github.com/pytest-dev/pytest-xdist) for distributed testing\n  - [`pytest-randomly`](https://github.com/pytest-dev/pytest-randomly) to randomly order tests\n\n- [`tox`](https://tox.readthedocs.org/en/latest/) for testing automation\n- [`sphinx`](http://www.sphinx-doc.org/en/master/) for docs\n  - [`myst-parser`](https://github.com/executablebooks/MyST-Parser) for markdown docs\n  - selectable theme\n- [`pdbp`](https://github.com/mdmintz/pdbp) for debugging\n- [`konch`](http://konch.readthedocs.org/en/latest/) for shell configuration w/ [`ipython`](https://ipython.org) support\n- [`pre-commit`](https://pre-commit.com) hooks with comprehensive tooling:\n  - [`uv-lock`](https://github.com/astral-sh/uv-pre-commit) for dependency management\n  - [`mypy`](https://mypy-lang.org) for type checking\n  - [`ruff`](https://github.com/astral-sh/ruff) for linting and formatting\n  - [`black`](https://github.com/psf/black) for code formatting\n  - [`blacken-docs`](https://github.com/adamchainz/blacken-docs) for formatting code in docs\n  - [`isort`](https://github.com/pycqa/isort) for import sorting\n  - [`bashate`](https://github.com/openstack/bashate) for shell script linting\n  - [`commitlint`](https://github.com/conventional-changelog/commitlint) for commit message standards\n  - [`detect-secrets`](https://github.com/Yelp/detect-secrets) for secret detection\n  - [`typos`](https://github.com/crate-ci/typos) for spell checking\n  - [`deptry`](https://github.com/fpgmaas/deptry) for dependency validation\n- [`dockerfile`](https://www.docker.com/) for development, testing, and production\n- [`dunamai`](https://github.com/mtkennerly/dunamai) for versioning\n- custom [`Justfile`](https://github.com/casey/just) (run `just`)\n- stay up-to-date w/ configured [`dependabot`](https://dependabot.com/)\n- [`github-actions`](https://github.com/features/actions) with ci (leveraging [`tox`](https://tox.readthedocs.org/en/latest/)), publish to pypi workflows w/ [`release-drafter`](https://github.com/release-drafter/release-drafter) integration\n\n  - [`ci`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/ci.yml) workflow (leveraging [`tox`](https://tox.readthedocs.org/en/latest/))\n\n    - optional [`codecov`](https://codecov.io) integration for code coverage\n\n  - [`publish`](https://github.com/ryankanno/cookiecutter-py/blob/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/publish.yml) workflow with configurable publishing to:\n    - [TestPyPI](https://test.pypi.org) (optional, enabled by default)\n    - [PyPI](https://pypi.org) (optional, enabled by default)\n    - [GitHub Packages](https://docs.github.com/en/packages) (optional, disabled by default)\n    - GitHub Release artifacts (optional, disabled by default)\n    - Always builds and uploads artifacts to GitHub Actions for manual inspection\n    - Integrated with [`release-drafter`](https://github.com/release-drafter/release-drafter)\n  - [`auto approve / merge`](https://github.com/ryankanno/cookiecutter-py/blob/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/auto-approve-merge-dependabot.yml) workflow\n  - with these additional workflows:\n\n    - [`codeql`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/codeql-analysis.yml) for security analysis\n    - [`hadolint`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/hadolint.yml) for Dockerfile linting\n    - [`pr-size-labeling`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/pr-size-labeler.yml) for PR size classification\n    - [`pr-labeler`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/pr-labeler.yml) for automated PR labeling\n    - [`commitlint`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/commitlint.yml) for commit message validation\n    - [`trufflehog`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/trufflehog.yml) for secret scanning\n    - [`docs`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/docs.yml) for documentation publishing\n    - [`release-drafter`](https://raw.githubusercontent.com/ryankanno/cookiecutter-py/main/%7B%7Bcookiecutter.package_name%7D%7D/.github/workflows/release-drafter.yml) for automated release notes\n- optional [`direnv`](https://github.com/direnv/direnv) .envrc (with [`use uv`](https://raw.githubusercontent.com/ryankanno/dotfiles/5ed45cfd8c387489fc0459eb1a485b2c21f3d159/dot_config/direnv/direnvrc) layout)\n\n\u003c!-- GETTING STARTED --\u003e\n## 🚀 Getting Started\n\n### Prerequisites\n\nInstall [Cookiecutter](https://cookiecutter.readthedocs.io/en/latest/installation.html)\n\n```sh\nuv add cookiecutter\n# pip install cookiecutter\n# pipenv install cookiecutter\n```\n\n**Optional**: Install [Cruft](https://github.com/cruft/cruft)\n\n```sh\nuv add cruft\n# pip install cruft\n# pipenv install cruft\n```\n\n## 🛠️ Usage\n\n### Cookiecutter\n\n```sh\ncookiecutter gh:ryankanno/cookiecutter-py\n```\n\n**Note**: If you want to use the auto approve / merge Dependabot workflow, make\nsure to create tags `major`, `minor`, `patch` so that Dependabot can tag its\nPRs. The workflow won't merge anything with a `major` tag.\n\n### Cruft (Optional)\n\n```sh\ncruft create https://github.com/ryankanno/cookiecutter-py/\n```\n\n\u003c!-- DETAILS --\u003e\n## 🔍 Details\n\n### Justfile Commands\n\nThe template includes a comprehensive [`Justfile`](https://github.com/casey/just) with the following commands:\n\n**Development:**\n- **`just install`** - Install dependencies using uv\n- **`just clean`** - Remove all build, test, and documentation artifacts\n\n**Testing \u0026 Quality:**\n- **`just tests`** - Run all tests (fast, no coverage)\n- **`just tests -- path/to/test.py`** - Run specific tests\n- **`just tests -- --durations=10`** - Show slow test durations\n- **`just coverage`** - Run tests with comprehensive coverage analysis\n- **`just lint`** - Run all linting checks via tox\n- **`just lint --fix`** - Auto-fix linting issues where possible\n- **`just pre-commit`** - Run pre-commit hooks\n\n**Documentation \u0026 Distribution:**\n- **`just docs`** - Build Sphinx documentation\n- **`just dist`** - Build distribution packages\n\n**Utilities:**\n- **`just tox -- \u003cargs\u003e`** - Run tox with custom arguments\n- **`just watch \u003crecipe\u003e`** - Watch files and re-run commands on changes (with desktop notifications)\n\nAll commands use `uv` as the package manager and integrate with tox environments for consistency.\n\n### Docker\n\nTo build the container:\n\n```sh\nDOCKER_BUILDKIT=1 docker build .\n```\n\nTo run the container (if you've installed the defaults):\n\n```sh\ndocker run \u003cimage_id or tag\u003e python -m surf.surf\n```\n\n### Versioning\n\nIf you enable the PyPi workflow, versioning will happen via [`dunamai`](https://github.com/mtkennerly/dunamai) within the Github pipeline.\n\nIf instead, you prefer to version your package, please do it via ```uv version $(dunamai from any)``` as recommended in their [documentation](https://github.com/mtkennerly/dunamai#user-content-integration).\n\n### Configuration Variables\n\nWhen you run cookiecutter, you'll be prompted for various configuration options. Here are the key variables:\n\n**Project Information:**\n- `author_name` - Your full name\n- `author_email` - Your email address\n- `project_name` - Human-readable project name\n- `project_short_description` - Brief description of your project\n- `project_url` - Project repository URL\n- `project_license` - License type (default: MIT)\n- `github_repository_owner` - GitHub username or organization\n- `package_name` - Python package name (snake_case)\n- `version` - Initial version number (default: 0.0.0)\n\n**Python \u0026 Dependencies:**\n- `python_version` - Minimum Python version (default: 3.12)\n- `supported_python_versions` - Comma-separated list of supported versions\n- `uv_version` - Version of uv to use\n- `tox_version` - Version of tox to use\n- `sphinx_theme` - Documentation theme (select from multiple options)\n\n**Optional Features:**\n- `should_use_direnv` - Include .envrc for direnv (default: y)\n- `should_create_author_files` - Include AUTHORS.rst (default: y)\n- `should_install_github_dependabot` - Enable Dependabot (default: y)\n- `should_automerge_autoapprove_github_dependabot` - Auto-approve/merge Dependabot PRs (default: y)\n- `should_install_github_actions` - Include GitHub Actions workflows (default: y)\n- `should_upload_coverage_to_codecov` - Upload coverage to Codecov (default: y)\n\n**Publishing Options:**\n- `should_publish_to_testpypi` - Publish to TestPyPI on every main push (default: y)\n- `should_publish_to_pypi` - Publish to PyPI on release (default: y)\n- `should_publish_to_github_packages` - Publish to GitHub Packages on release (default: n)\n- `should_attach_to_github_release` - Attach build artifacts to GitHub releases (default: n)\n\n**Note:** Even if all publishing options are disabled, the build job still runs and uploads artifacts to GitHub Actions for manual inspection.\n\n\u003c!-- ROADMAP --\u003e\n## 🚧 Roadmap\n\nSee the [open issues](https://github.com/ryankanno/cookiecutter-py/issues) for a list of proposed features (and known issues).\n\n\u003c!-- TODO --\u003e\n## ☑️ TODO\n\n- [ ] add mutmut example to template\n- [ ] add hypothesis example to template\n- [ ] add licenses\n- [ ] add typeguard\n- [ ] version releases\n- [ ] update docs\n- [ ] add publish docs workflow\n- [X] include cookiecutter var descriptions\n- [X] update default/initial template doc structure\n- [X] investigate uv\n- [X] migrate to uv\n- [X] finalize v1.0.0\n\n\u003c!-- CONTRIBUTING --\u003e\n## 🤝 Contributing\n\nContributions are very much appreciated.\n\n1. Fork the project\n2. Create your feature branch (`git checkout -b feature/new-cookiecutter-feature`)\n3. Commit your changes (`git commit -m 'Added a new feature'`)\n4. Push to the feature branch (`git push origin feature/new-cookiecutter-feature`)\n5. Open a PR! 🎆\n\n\u003c!-- LICENSE --\u003e\n## 📝 License\n\nDistributed under the MIT License. See [`LICENSE`](https://github.com/ryankanno/cookiecutter-py/blob/main/LICENSE) for more information.\n\n\u003c!-- CONTACT --\u003e\n## 📫 Contact\n\nRyan Kanno - [@ryankanno][twitter-ryankanno-url]\n\nProject Link: [https://github.com/ryankanno/cookiecutter-py][project-url]\n\n\n[project-url]: https://github.com/ryankanno/cookiecutter-py\n[project-docs]: https://ryankanno.github.io/cookiecutter-py/latest\n[project-license-shield]: https://img.shields.io/github/license/ryankanno/cookiecutter-py\n[project-license-url]: https://github.com/ryankanno/cookiecutter-py/blob/main/LICENSE\n[github-issues-shield]: https://img.shields.io/github/issues/ryankanno/cookiecutter-py\n[github-issues-url]: https://github.com/ryankanno/cookiecutter-py/issues\n[github-prs-shield]: https://img.shields.io/github/issues-pr/ryankanno/cookiecutter-py\n[github-prs-url]: https://github.com/ryankanno/cookiecutter-py/pulls\n[twitter-ryankanno-url]: https://twitter.com/ryankanno\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryankanno%2Fcookiecutter-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryankanno%2Fcookiecutter-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryankanno%2Fcookiecutter-py/lists"}