Python Best Practices Launchpad

You can choose one of two approaches to set up this project:

Before cloning the repository, make sure you have Linuxbrew installed (or Homebrew on macOS).

1. Install WSL: Follow the official Microsoft instructions to install WSL and choose a Linux distribution (e.g., Ubuntu).

2. Open a Direct WSL Terminal:
Do NOT use wsl from a Windows terminal (like PowerShell or Command Prompt).
In VS Code: Open a new integrated terminal by clicking the "+" button on the terminals tab, and select your WSL distribution (e.g., "Ubuntu", "Debian") from the dropdown menu.
From Start Menu: Alternatively, launch your WSL distribution's terminal directly from the Windows Start Menu (e.g., "Ubuntu", "Debian").

All subsequent steps in this section must be executed within this direct WSL terminal.

    sudo apt update && sudo apt install -y build-essential curl file git

    

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    

    export PATH="/home/linuxbrew/.linuxbrew/bin:$PATH"

    export MANPATH="/home/linuxbrew/.linuxbrew/share/man:$MANPATH"

    export INFOPATH="/home/linuxbrew/.linuxbrew/share/info:$INFOPATH"

    

    git clone <repository_url>

    cd <project_name>

    

    uv venv

    

     uv sync

    

    pre-commit install

    

    uv lock

    

Project Metadata:
Basic project information like name, version, description, authors, etc.
Python version specified in requires-python
Dependencies:
Project's dependencies listed in the [project.dependencies array.
Development dependencies listed in the [project.optional-dependencies.dev] array, or you can add additional groups.

General-Purpose Hooks (pre-commit-hooks): Trailing whitespace removal, end-of-file newline enforcement, YAML validation, etc.
ruff Hook (astral-sh/ruff-pre-commit): Automatically fixes Ruff errors (ruff --fix).
black Hook (psf/black): Automatically reformats your code with the black formatter
mypy Hook (pre-commit/mirrors-mypy): Checks code for type errors with mypy

Type Checking: python.analysis.typeCheckingMode: Enables Python's type checker.
Linting: python.linting.ruffEnabled: Enables ruff as the linter.
Formatting: python.formatting.provider: Disables default formatter, since pre-commit is being used.
Ruff Settings: Settings for Ruff language server (e.g., importStrategy, organizeImports, fixAll, showSyntaxErrors).
ruff.configurationPreference: prioritize file based configs.

Here are some additional configurations that are often useful and are commonly used or at least helpful if applicable.

constraint-dependencies: If you want to pin a transitive dependency to a specific version use constraint-dependencies.

    [tool.uv]
        constraint-dependencies = ["cryptography<42.0.0"]
    

override-dependencies: Forces a dependency to use a specific version

    [tool.uv]
        override-dependencies = ["cryptography==42.0.0"]
    

index: You can specify additional package indexes to get dependencies from

    [[tool.uv.index]]
     name = "pytorch"
     url = "https://download.pytorch.org/whl/cu121"
     explicit = true
[tool.uv.sources]

     torch = { index = "pytorch" }

    

pytest.ini: Create a pytest.ini in your root folder to configure options for pytest.

    [pytest]
    testpaths = tests
    addopts =
        --cov=src/my_package
        --cov-report term-missing
        -vv
    

This will make sure that pytest runs against all tests in the tests folder

It will also add coverage info for src/my_package

It will also run in verbose mode

You can add additional hooks from other repositories.

You can configure existing hooks as needed. For example if you want to exclude files from ruff you can use:

-   id: ruff
    args: ["--fix", "--exclude", "path/to/exclude"]

- Create one venv per project to avoid dependency conflicts
- Don't commit the .venv directory (it's in .gitignore)
- On Windows, if UV fails, fall back to python -m venv
- Rebuild venv if you suspect dependency issues