{"id":16543137,"url":"https://github.com/sanders41/python-project-generator","last_synced_at":"2025-12-25T23:48:01.541Z","repository":{"id":191092440,"uuid":"683882363","full_name":"sanders41/python-project-generator","owner":"sanders41","description":"Generates a Python project structure for starting new projects","archived":false,"fork":false,"pushed_at":"2025-03-14T14:18:24.000Z","size":1588,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-15T13:04:20.987Z","etag":null,"topics":["maturin","poetry","project-template","pyo3","python","python-project-starter","python-project-template","rust","setuptools","template"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/sanders41.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":["sanders41"]}},"created_at":"2023-08-28T01:29:46.000Z","updated_at":"2025-03-14T14:12:26.000Z","dependencies_parsed_at":"2023-08-28T04:50:25.783Z","dependency_job_id":"fce30ed3-142b-4c2c-8a1f-383654f7a23a","html_url":"https://github.com/sanders41/python-project-generator","commit_stats":null,"previous_names":["sanders41/python-project-generator"],"tags_count":131,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanders41%2Fpython-project-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanders41%2Fpython-project-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanders41%2Fpython-project-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sanders41%2Fpython-project-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sanders41","download_url":"https://codeload.github.com/sanders41/python-project-generator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244777867,"owners_count":20508801,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["maturin","poetry","project-template","pyo3","python","python-project-starter","python-project-template","rust","setuptools","template"],"created_at":"2024-10-11T18:59:26.088Z","updated_at":"2025-12-25T23:48:01.535Z","avatar_url":"https://github.com/sanders41.png","language":"Rust","readme":"# Python Project Generator\n\n[![Tests Status](https://github.com/sanders41/python-project-generator/actions/workflows/testing.yml/badge.svg?branch=main\u0026event=push)](https://github.com/sanders41/python-project-generator/actions?query=workflow%3ATesting+branch%3Amain+event%3Apush)\n![crates.io](https://img.shields.io/crates/v/python-project-generator.svg?color=brightgreen)\n\nGenerates a Python project structure with github actions for continuous integration and continuous\ndeployment. Both pure Python projects and Python projects with Rust modules using PyO3 can be\ncreated. Additionally FastAPI projects can be generated.\n\n## Pure Python project included packages\n\nFor package management choose between:\n\n- [poetry](https://python-poetry.org/)\n- [setuptools](https://github.com/pypa/setuptools)\n- [uv](https://docs.astral.sh/uv/)\n\nDev packages:\n\n- [mypy](https://www.mypy-lang.org/) for static type checking\n- [pytest](https://docs.pytest.org/en/latest/) for testing\n- [pytest-cov](https://github.com/pytest-dev/pytest-cov) for test coverage reports\n- [ruff](https://beta.ruff.rs/docs/) for linting and code formatting\n\n## Python project with Rust modules included packages\n\n- [maturin](https://github.com/PyO3/maturin) for package management\n- [mypy](https://www.mypy-lang.org/) for static type checking\n- [pytest](https://docs.pytest.org/en/latest/) for testing\n- [pytest-cov](https://github.com/pytest-dev/pytest-cov) for test coverage reports\n- [ruff](https://beta.ruff.rs/docs/) for linting and code formatting\n- [PyO3](https://github.com/PyO3/pyo3) for managing the Rust/Python FFI\n- [justfile](https://github.com/casey/just) for running commands (to use this you will need to\n  install just)\n\n## FastAPI projects include\n\n- [asyncpg](https://github.com/MagicStack/asyncpg) for interacting with PostgreSQL\n- [camel-converter](https://github.com/sanders41/camel-converter) for converting to and from\n  camel/snake case in Pydantic models when serializing/deserializing JSON\n- [fastapi](https://github.com/fastapi/fastapi)\n- [granian](https://github.com/emmett-framework/granian) for handling the web requests\n- [httptools](https://github.com/MagicStack/httptools) for faster http parsing\n- [loguru](https://github.com/Delgan/loguru) for logging\n- [orjson](https://github.com/ijl/orjson) for faster JSON serization/deserilization\n- [pwdlib](https://github.com/frankie567/pwdlib) for password hashing\n- [pydantic](https://github.com/pydantic/pydantic) for model validation\n- [pydantic-settings](https://github.com/pydantic/pydantic-settings) for managing settings\n- [uvloop](https://github.com/MagicStack/uvloop) for enhanced performance (not available on Windows)\n- [postgresql](https://www.postgresql.org/) for the database layer\n- [valkey](https://github.com/valkey-io/valkey) for the caching layer\n- [traefik](https://github.com/traefik/traefik) for reverse proxy\n- [sqlx](https://github.com/launchbadge/sqlx) for migrations\n\n## Docs\n\nIf you chose to include docs then additional dev packages will be included for docs.\n\n- [mkdocs](index_md) for creating the docs\n- [mkdocs-material](index_md) for theming the docs\n- [mkdocstrings](index_md) for automatically creating API docs\n\nAdditionally the `pypi_publish.yml` workflow will also be setup to deploy the doc on release.\n\n## Installation\n\nInstall with `cargo`:\n\n```sh\ncargo install python-project-generator\n```\n\nIf you want to be able to generate FastAPI projects install with the fastapi feature\n\n```sh\ncargo install python-project-generator -F fastapi\n```\n\nInstall on Arch with the AUR:\n\n```sh\nparu -S python-project-generator-bin\n```\n\nInstall on Debian/Ubuntu:\n\nNote: Change the version to match the version you want to install.\n\n```sh\ncurl -LO https://github.com/sanders41/python-project-generator/releases/download/v1.0.16/python-project-generator_1.0.16_amd64.deb\nsudo dpkg -i python-project-generator_1.0.16_amd64.deb\n```\n\nPython Project Generator can also be installed with binaries provided with each release\n[here](https://github.com/sanders41/python-project-generator/releases), or with cargo.\n\n## How to use\n\n### Create a new project\n\nFrom your terminal run:\n\n```sh\npython-project create\n```\n\nYou will be asked a series of questions that will be used to generate your project. The project\ngenerator will check pypi for the latest version of the included packages and use those while\ngenerating the project.\n\n#### Options\n\n- License\n\n  Choose from MIT, Apache 2, or no license.\n\n- Python Version\n\n  This will be the default Python version used. For example when releasing the project this is the\n  version of Python that will be used.\n\n- Minimum Python Version\n\n  This is the minimum supported Python version for the project. This is also the version that is\n  used for ruff's upgrade target version.\n\n- Python Versions for Github Actions Testing\n\n  Versions listed here will be the versions used for testing in CI.\n\n- Project Manager\n\n  Specifies how project dependencies and builds should be handled\n\n- Application or Library\n\n  Choosing application will create `main.py` and `__main__.py` files. Choosing library will omit\n  these files. FastAPI projects are automatically created as applications with a special FastAPI\n  main.py\n\n- Async Project\n\n  Selecting yes for this option will add [pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio)\n  to the dev dependencies. Additionally if the project is an application the `main` function will\n  be made async. This question is skipped with FastAPI projects and automatically set to an async\n  project\n\n- Max Line Length\n\n  This controls how long the ruff formatter will use for line wrapping.\n\n- Use Dependabot\n\n  Dependabot can be used to keep dependencies up to date. If enabled dependabot will automatically\n  create PRs to update dependencies when they are available.\n\n- Dependabot Schedule\n\n  When dependabot is enabled the schedule controls how often dependabot will check for updates and\n  create PRs.\n\n- Use Continuous Deployment\n\n  This will create a GitHub Action to deploy the project to PyPI when a new release is created.\n  Note that for this to work you will need to setup a\n  [trusted publisher](https://docs.pypi.org/trusted-publishers/adding-a-publisher/) in PyPI with\n  a workflow name of pypi_publish.yml.\n\n  If the project is a FastAPI project this will create workflows to deploy to test and production\n  servers using GitHub runners.\n\n- Release Drafter\n\n  Choosing yes will create a [release drafter](https://github.com/release-drafter/release-drafter)\n  action automatically adds the tile of the PR, who created it, and it's PR number to a draft\n  GitHub release. By default the release will get a patch version update. Adding a `bug` label will\n  get a patch version update and add it to the `Bug` section of the release notes. Adding an\n  `enhancement` label to a PR will create a release with a minor version bump, and a\n  `breaking-change` label will create a major version bump. The draft release will get the release\n  version tag for the highest label applied to the merged PRs in the release. PRs can be excluded\n  from the release notes by applying a `skip-changelog` label to the PR.\n\n- Use Multi OS CI\n\n  Choosing yes will setup CI to run tests on Linux, Mac, and Windows. If no is chosen tests will\n  only run on Linux in CI.\n\n  This is skipped for FastAPI projects and defaults to Linux only. FastAPI projects use Docker\n  with is only available in Linux in GitHub Actions.\n\n- Include Docs\n\n  Choosing yes will add additional packages and base setup for creating documents with mkdocs.\n\n- Docs Site Name\n\n  This question will only show if you chose `yes` for `Include Docs`. This value sets the site name\n  field for mkdocs.\n\n- Docs Site Description\n\n  This question will only show if you chose `yes` for `Include Docs`. This value provides a\n  a description of the repo to use in the docs.\n\n- Docs Site URL\n\n  This question will only show if you chose `yes` for `Include Docs`. This is the URL where the docs\n  will be hosted.\n\n- Docs Locale\n\n  This question will only show if you chose `yes` for `Include Docs`, and controls the language of\n  the docs.\n\n- Repo Name\n\n  This question will only show if you chose `yes` for `Include Docs`. This is the name of the repo\n  the docs are referencing. For example in this repository the repo name would be\n  `sanders41/python-project-generator`.\n\n- Repo URL\n\n  This question will only show if you chose `yes` for `Include Docs`. This is URL for the repo the\n  docs are referencing. For example in this repository the repo url would be\n  `https://github.com/sanders41/python-project-generator`\n\nAfter running the generator a new directory will be created with the name you used for the\n`Project Slug`. Change to this directory and your project is ready to use. If the project is a\nPyO3 project the rust code will need to be compiled. Running `just install` will do this.\n\n### FastAPI projects\n\nCreate a .env file with the needed variables. the .env-example file can be used as a starter\ntemplate. Then start the containers.\n\n```sh\ndocker compose up\n```\n\nNow your project is ready to use.\n\n### Save custom default values\n\nYou can specify default values for many of the project options. For example to save a default\ncreator:\n\n```sh\npython-project config creator \"Wade Watts\"\n```\n\nTo see a full list of values that be set as defaults run:\n\n```sh\npython-project config --help\n```\n\nTo view the current saved defaults:\n\n```sh\npython-project config show\n```\n\nTo remove custom defaults:\n\n```sh\npython-project config reset\n```\n\n## Information\n\n### just\n\n[just](https://github.com/casey/just) allows you to add project specific commands to the project\nthat can be run from the command line. It is very similar to [make](https://github.com/mirror/make)\nbut has the advantage of being cross platform compatible and purposee build for running commands.\n\nAs an example, if you have the following in the `justfile` (this is included with the default file\ngenerated by this project):\n\n```just\n@_default:\n  just --list\n\n@lint:\n  echo mypy\n  just --justfile {{justfile()}} mypy\n  echo ruff-check\n  just --justfile {{justfile()}} ruff-check\n  echo ruff-format\n  just --justfile {{justfile()}} ruff-format\n\n@mypy:\n  uv run mypy my_project tests\n\n@ruff-check:\n  uv run ruff check my_project tests\n\n@ruff-format:\n  uv run ruff format my_project tests\n\n@test *args=\"\":\n  -uv run pytest {{args}}\n\n@lock:\n  uv lock\n\n@lock-upgrade:\n  uv lock --upgrade\n\n@install:\n  uv sync --frozen --all-extras\n```\n\nThen you can run `mypy`, `ruff` check, and `ruff` format with:\n\n```sh\njust mypy\njust ruff-check\njust ruff-format\n```\n\nYou can also run all 3 with 1 `just` command:\n\n```sh\njust lint\n```\n\n### pre-commit\n\n[pre-commit](https://pre-commit.com/) runs linting and formatting on your code (as defined in the\nprovided .pre-commit-config.yaml file) every time you make a commit to your code. If any of the\nlints fail pre-commit will cancel the commit. When possible, pre-commit will also automatically\nfix any errors that fail. For example pre-commit can automatically apply changes that fail ruff\nformatting. pre-commit caches information and only runs on files that have changed so it is fast\nand doesn't slow down your work flow will preventing you from forgetting to run checks.\n\n### FastAPI migrations\n\n[sqlx](https://github.com/launchbadge/sqlx) is used for migrations. A dedicated docker container\nruns the migrations each time docker is started. For creating new migrations install `sqlx-cli`.\n`sqlx-cli` also needs to be installed in order to run the generated test suite.\n\n```sh\ncargo install sqlx-cli --no-default-features --features native-tls,postgres\n```\n\nThen to add a new migration run:\n\n```sh\nsqlx migrate add -r my_migration\n```\n\nThis will create new migration up and down files in the migrations directory.\n\n## Contributing\n\nIf you are interested in contributing please see our [contributing guide](CONTRIBUTING.md)\n","funding_links":["https://github.com/sponsors/sanders41"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanders41%2Fpython-project-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsanders41%2Fpython-project-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsanders41%2Fpython-project-generator/lists"}