Python in 2026: optional GIL, real types, and packaging that finally works

# Install uv - no existing Python required
curl -LsSf https://astral.sh/uv/install.sh | sh

# Start a project
uv init shop-api
cd shop-api

# Add dependencies - this creates the venv, resolves and locks in one step
uv add fastapi uvicorn sqlalchemy
uv add --dev pytest ruff mypy

# Run things inside the environment without activating it
uv run python main.py
uv run pytest

# Install and pin a specific interpreter
uv python install 3.14
uv python pin 3.14

# Reproduce the exact environment elsewhere - this is what CI should run
uv sync --frozen

# Run a tool without installing it into your project
uvx ruff check .

[project]
name = "shop-api"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "fastapi>=0.120",
    "sqlalchemy>=2.0",
]

[dependency-groups]
dev = ["pytest>=8", "ruff>=0.14", "mypy>=1.15"]

[tool.ruff]
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "B", "SIM", "RUF"]

[tool.mypy]
strict = true
python_version = "3.14"

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip freeze > requirements.txt  # note: this captures your whole environment, not your intent

class Money:
    def __init__(self, cents: int, currency: str = "BDT") -> None:
        self.cents = cents
        self.currency = currency

    def __add__(self, other: "Money") -> "Money":
        if self.currency != other.currency:
            raise ValueError("cannot add different currencies")
        return Money(self.cents + other.cents, self.currency)

    def __eq__(self, other: object) -> bool:
        return (
            isinstance(other, Money)
            and (self.cents, self.currency) == (other.cents, other.currency)
        )

    def __repr__(self) -> str:
        return f"Money({self.cents}, {self.currency!r})"

    def __format__(self, spec: str) -> str:
        return f"{self.cents / 100:,.2f} {self.currency}"

total = Money(4999) + Money(2500)
print(f"{total}")     # 74.99 BDT

orders = [{"id": 1, "total": 4999, "paid": True}, {"id": 2, "total": 2500, "paid": False}]

# List comprehension
paid_ids = [o["id"] for o in orders if o["paid"]]

# Dict comprehension
totals = {o["id"]: o["total"] for o in orders}

# Generator expression - lazy, constant memory, use it for large data
revenue = sum(o["total"] for o in orders if o["paid"])

# A generator function streams instead of materialising
def read_large_file(path: str):
    with open(path) as f:
        for line in f:            # files iterate line by line, not all at once
            yield line.rstrip()

for line in read_large_file("10gb.log"):
    process(line)                 # memory stays flat regardless of file size

from dataclasses import dataclass, field
from datetime import datetime, UTC

@dataclass(frozen=True, slots=True)
class Order:
    id: int
    customer_id: int
    total_cents: int
    tags: list[str] = field(default_factory=list)
    placed_at: datetime = field(default_factory=lambda: datetime.now(UTC))

    @property
    def total(self) -> float:
        return self.total_cents / 100

order = Order(id=1, customer_id=7, total_cents=4999)

def handle(event: dict) -> str:
    match event:
        case {"type": "payment", "amount": int(amount)} if amount > 100_000:
            return f"large payment: {amount}"

        case {"type": "payment", "amount": amount}:
            return f"payment: {amount}"

        case {"type": "refund", "order_id": str() | int() as oid}:
            return f"refund for {oid}"

        case {"type": str(kind)}:
            return f"unhandled: {kind}"

        case _:
            raise ValueError("malformed event")

from contextlib import contextmanager
import time

@contextmanager
def timed(label: str):
    start = time.perf_counter()
    try:
        yield
    finally:
        print(f"{label}: {time.perf_counter() - start:.3f}s")

with timed("import"), open("data.csv") as f:
    rows = f.readlines()

from collections.abc import Iterable, Callable
from typing import Protocol, TypedDict, Literal

# Builtins are generic - no more typing.List or typing.Dict
def total(values: list[int]) -> int:
    return sum(values)

# Unions with |, optional with | None
def find_user(user_id: int) -> dict[str, str] | None: ...

# Literal types for a fixed set of values
Status = Literal["pending", "paid", "shipped", "cancelled"]

# TypedDict for structured dictionaries you cannot turn into classes
class OrderRow(TypedDict):
    id: int
    status: Status
    total_cents: int

# Protocols: structural typing, no inheritance required
class Storage(Protocol):
    def get(self, key: str) -> bytes | None: ...
    def put(self, key: str, value: bytes) -> None: ...

def cache_result(storage: Storage, key: str) -> None: ...
# Anything with those two methods satisfies Storage. Duck typing, checked statically.

# Generics with the 3.12+ syntax - no TypeVar declaration needed
def first[T](items: list[T]) -> T | None:
    return items[0] if items else None

class Repository[T]:
    def __init__(self) -> None:
        self._items: dict[int, T] = {}

    def add(self, key: int, item: T) -> None:
        self._items[key] = item

    def get(self, key: int) -> T | None:
        return self._items.get(key)

uv run mypy src/          # the established checker
uvx ty check src/         # Astral's Rust checker, much faster, newer
uvx pyright src/          # Microsoft's, strong inference

import asyncio
import httpx

async def fetch(client: httpx.AsyncClient, url: str) -> int:
    response = await client.get(url)
    return len(response.content)

async def main() -> None:
    urls = [f"https://example.com/page/{i}" for i in range(50)]

    async with httpx.AsyncClient() as client:
        # TaskGroup cancels siblings if one fails - prefer it over gather()
        async with asyncio.TaskGroup() as tg:
            tasks = [tg.create_task(fetch(client, url)) for url in urls]

    total = sum(task.result() for task in tasks)
    print(f"{total:,} bytes from {len(urls)} pages")

asyncio.run(main())

import asyncio

def parse_big_csv(path: str) -> list[dict]: ...   # synchronous, slow

async def handler(path: str):
    rows = await asyncio.to_thread(parse_big_csv, path)   # off the event loop
    return len(rows)

# Install and check
uv python install 3.14t
python3.14t -c "import sys; print(sys._is_gil_enabled())"
# False means you are genuinely running without the GIL

# Profile before optimising anything
python -m cProfile -s cumtime script.py | head -30

# Line-level detail
uvx line_profiler script.py

# Sampling profiler for a live process - new in 3.15, and much lower overhead
python -m profiling sample <pid>

# Memory
uvx memray run script.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI()

class CreateOrder(BaseModel):
    customer_id: int
    total_cents: int = Field(gt=0, le=10_000_000)
    note: str | None = Field(default=None, max_length=500)

@app.post("/orders", status_code=201)
async def create_order(payload: CreateOrder) -> dict:
    if not await customer_exists(payload.customer_id):
        raise HTTPException(404, "customer not found")
    return await save_order(payload)

uv sync --frozen              # exact locked environment
uv run ruff format --check .  # formatting
uv run ruff check .           # linting - replaces flake8, isort, pyupgrade and more
uv run mypy src/              # type checking
uv run pytest --cov=src       # tests with coverage

import pytest
from app.orders import Order, apply_discount

@pytest.fixture
def order() -> Order:
    return Order(id=1, customer_id=7, total_cents=10_000)

@pytest.mark.parametrize(
    ("percent", "expected"),
    [(0, 10_000), (10, 9_000), (100, 0)],
)
def test_discount(order: Order, percent: int, expected: int) -> None:
    assert apply_discount(order, percent).total_cents == expected

def test_rejects_negative_discount(order: Order) -> None:
    with pytest.raises(ValueError, match="must be between"):
        apply_discount(order, -5)

FROM python:3.14-slim AS build
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
WORKDIR /app
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-install-project --no-dev

COPY . .
RUN uv sync --frozen --no-dev

FROM python:3.14-slim
WORKDIR /app
COPY --from=build /app /app
ENV PATH="/app/.venv/bin:$PATH"
RUN useradd -m app && chown -R app /app
USER app
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

# Mutable default arguments - evaluated ONCE, at function definition
def add_item(item, basket=[]):      # every call shares the same list
    basket.append(item)
    return basket

add_item("a")   # ['a']
add_item("b")   # ['a', 'b']  ← not what anyone expects

# Correct
def add_item(item, basket: list | None = None):
    basket = [] if basket is None else basket
    basket.append(item)
    return basket