Python Project Generator

Generates a Python project structure with github actions for continuous integration and continuous deployment. Both pure Python projects and Python projects with Rust modules using PyO3 can be created. Additionally FastAPI projects can be generated.

Pure Python project included packages

For package management choose between:

• poetry
• setuptools
• uv

Dev packages:

• mypy for static type checking
• pytest for testing
• pytest-cov for test coverage reports
• ruff for linting and code formatting

Python project with Rust modules included packages

• maturin for package management
• mypy for static type checking
• pytest for testing
• pytest-cov for test coverage reports
• ruff for linting and code formatting
• PyO3 for managing the Rust/Python FFI
• justfile for running commands (to use this you will need to install just)

FastAPI projects include

• asyncpg for interacting with PostgreSQL
• camel-converter for converting to and from camel/snake case in Pydantic models when serializing/deserializing JSON
• fastapi
• granian for handling the web requests
• httptools for faster http parsing
• loguru for logging
• orjson for faster JSON serization/deserilization
• pwdlib for password hashing
• pydantic for model validation
• pydantic-settings for managing settings
• uvloop for enhanced performance (not available on Windows)
• postgresql for the database layer
• valkey for the caching layer
• traefik for reverse proxy
• sqlx for migrations

Docs

If you chose to include docs then additional dev packages will be included for docs.

• mkdocs for creating the docs
• mkdocs-material for theming the docs
• mkdocstrings for automatically creating API docs

Additionally the pypi_publish.yml workflow will also be setup to deploy the doc on release.

Installation

Install with cargo:

cargo install python-project-generator

If you want to be able to generate FastAPI projects install with the fastapi feature

cargo install python-project-generator -F fastapi

Install on Arch with the AUR:

paru -S python-project-generator-bin

Install on Debian/Ubuntu:

Note: Change the version to match the version you want to install.

curl -LO https://github.com/sanders41/python-project-generator/releases/download/v1.0.16/python-project-generator_1.0.16_amd64.deb
sudo dpkg -i python-project-generator_1.0.16_amd64.deb

Python Project Generator can also be installed with binaries provided with each release here, or with cargo.

How to use

Create a new project

From your terminal run:

python-project create

You will be asked a series of questions that will be used to generate your project. The project generator will check pypi for the latest version of the included packages and use those while generating the project.

Options

• License

  Choose from MIT, Apache 2, or no license.

• Python Version

  This will be the default Python version used. For example when releasing the project this is the version of Python that will be used.

• Minimum Python Version

  This is the minimum supported Python version for the project. This is also the version that is used for ruff's upgrade target version.

• Python Versions for Github Actions Testing

  Versions listed here will be the versions used for testing in CI.

• Project Manager

  Specifies how project dependencies and builds should be handled

• Application or Library

  Choosing application will create main.py and __main__.py files. Choosing library will omit these files. FastAPI projects are automatically created as applications with a special FastAPI main.py

• Async Project

  Selecting yes for this option will add pytest-asyncio to the dev dependencies. Additionally if the project is an application the main function will be made async. This question is skipped with FastAPI projects and automatically set to an async project

• Max Line Length

  This controls how long the ruff formatter will use for line wrapping.

• Use Dependabot

  Dependabot can be used to keep dependencies up to date. If enabled dependabot will automatically create PRs to update dependencies when they are available.

• Dependabot Schedule

  When dependabot is enabled the schedule controls how often dependabot will check for updates and create PRs.

• Use Continuous Deployment

  This will create a GitHub Action to deploy the project to PyPI when a new release is created. Note that for this to work you will need to setup a trusted publisher in PyPI with a workflow name of pypi_publish.yml.

  If the project is a FastAPI project this will create workflows to deploy to test and production servers using GitHub runners.

• Release Drafter

  Choosing yes will create a release drafter action automatically adds the tile of the PR, who created it, and it's PR number to a draft GitHub release. By default the release will get a patch version update. Adding a bug label will get a patch version update and add it to the Bug section of the release notes. Adding an enhancement label to a PR will create a release with a minor version bump, and a breaking-change label will create a major version bump. The draft release will get the release version tag for the highest label applied to the merged PRs in the release. PRs can be excluded from the release notes by applying a skip-changelog label to the PR.

• Use Multi OS CI

  Choosing yes will setup CI to run tests on Linux, Mac, and Windows. If no is chosen tests will only run on Linux in CI.

  This is skipped for FastAPI projects and defaults to Linux only. FastAPI projects use Docker with is only available in Linux in GitHub Actions.

• Include Docs

  Choosing yes will add additional packages and base setup for creating documents with mkdocs.

• Docs Site Name

  This question will only show if you chose yes for Include Docs. This value sets the site name field for mkdocs.

• Docs Site Description

  This question will only show if you chose yes for Include Docs. This value provides a a description of the repo to use in the docs.

• Docs Site URL

  This question will only show if you chose yes for Include Docs. This is the URL where the docs will be hosted.

• Docs Locale

  This question will only show if you chose yes for Include Docs, and controls the language of the docs.

• Repo Name

  This question will only show if you chose yes for Include Docs. This is the name of the repo the docs are referencing. For example in this repository the repo name would be sanders41/python-project-generator.

• Repo URL

  This question will only show if you chose yes for Include Docs. This is URL for the repo the docs are referencing. For example in this repository the repo url would be https://github.com/sanders41/python-project-generator

After running the generator a new directory will be created with the name you used for the Project Slug. Change to this directory and your project is ready to use. If the project is a PyO3 project the rust code will need to be compiled. Running just install will do this.

FastAPI projects

Create a .env file with the needed variables. the .env-example file can be used as a starter template. Then start the containers.

docker compose up

Now your project is ready to use.

Save custom default values

You can specify default values for many of the project options. For example to save a default creator:

python-project config creator "Wade Watts"

To see a full list of values that be set as defaults run:

python-project config --help

To view the current saved defaults:

python-project config show

To remove custom defaults:

python-project config reset

Information

just

just allows you to add project specific commands to the project that can be run from the command line. It is very similar to make but has the advantage of being cross platform compatible and purposee build for running commands.

As an example, if you have the following in the justfile (this is included with the default file generated by this project):

@_default:
  just --list

@lint:
  echo mypy
  just --justfile {{justfile()}} mypy
  echo ruff-check
  just --justfile {{justfile()}} ruff-check
  echo ruff-format
  just --justfile {{justfile()}} ruff-format

@mypy:
  uv run mypy my_project tests

@ruff-check:
  uv run ruff check my_project tests

@ruff-format:
  uv run ruff format my_project tests

@test *args="":
  -uv run pytest {{args}}

@lock:
  uv lock

@lock-upgrade:
  uv lock --upgrade

@install:
  uv sync --frozen --all-extras

Then you can run mypy, ruff check, and ruff format with:

just mypy
just ruff-check
just ruff-format

You can also run all 3 with 1 just command:

just lint

pre-commit

pre-commit runs linting and formatting on your code (as defined in the provided .pre-commit-config.yaml file) every time you make a commit to your code. If any of the lints fail pre-commit will cancel the commit. When possible, pre-commit will also automatically fix any errors that fail. For example pre-commit can automatically apply changes that fail ruff formatting. pre-commit caches information and only runs on files that have changed so it is fast and doesn't slow down your work flow will preventing you from forgetting to run checks.

FastAPI migrations

sqlx is used for migrations. A dedicated docker container runs the migrations each time docker is started. For creating new migrations install sqlx-cli. sqlx-cli also needs to be installed in order to run the generated test suite.

cargo install sqlx-cli --no-default-features --features native-tls,postgres

Then to add a new migration run:

sqlx migrate add -r my_migration

This will create new migration up and down files in the migrations directory.

Contributing

If you are interested in contributing please see our contributing guide