Quickstart

This guide covers the essential steps to get up and running with a project generated by cookiecutter-robust-python. Perfect for developers who want to start coding with the core workflows immediately.

For detailed tool explanations and project philosophy, see the full documentation.

1. Prerequisites

Make sure you have these installed:

  • Python 3.10+ (or your chosen template version).

  • Git.

  • uv: Our chosen dependency manager. Install it officially.

  • Docker or Podman: If you plan to work with containers (most web apps will need this). Install Docker or Podman.

2. Create Your Project

Navigate to the directory you want to create your new project in.

cd ~/path/to/my/repos

Generate your project from the template:

uvx cruft create https://github.com/robust-python/cookiecutter-robust-python.git

Follow the prompts to customize your project.

3. Initial Project Setup

Navigate to your new project directory:

cd your-project-slug

Set up the virtual environment and install dependencies:

uvx nox -s setup-venv

This sets up a virtual environment with uv and installs all development dependencies.

4. Install Pre-commit Hooks

Set up automated checks that run before you commit code:

uvx nox -s pre-commit -- install

Now, git commit will automatically run code formatting and basic linting checks on staged files.

5. Run Checks and Tests

Run quality checks and tests using the nox sessions:

uvx nox -s lint-python      # Run Ruff linting
uvx nox -s typecheck        # Run Basedpyright type checking
uvx nox -s security-python  # Run Bandit and pip-audit
uvx nox -s tests-python     # Run pytest with coverage

These commands run in isolated environments with the proper Python versions as defined in noxfile.py.

6. Build Documentation

Build and serve the project documentation locally:

uvx nox -s docs           # Build and serve with live reload
uvx nox -s build-docs     # Build only (static files)

The docs session builds and serves documentation with automatic reload on changes.

Next Steps

  • Start writing your code in the src/ directory!

  • Add and remove dependencies using uv add <package> and uv remove <package>.

  • If building a web application, explore the Dockerfile and compose.yaml (Application Container Building, Container Orchestration).

  • Set up CI/CD using the example workflow files (e.g., in .github/workflows/).

For detailed information on any of these tools or workflows, navigate through the template’s full documentation.