Guide

This guide covers the PPy language, one topic per page.

A .ppy file is valid Python 3.12+. What PPy adds is carried by annotations and decorators from the ppy package, and all of them are inert at runtime. Under plain CPython the decorators return the function unchanged, and the markers are ordinary typing.Annotated aliases. The compiler adds enforcement and speed. It does not change behavior.

Each namespace has a Python reference implementation and a lowering that agrees with it, so a program that uses any of them runs the same on every path.

Pages

page	what it covers
The subset	What the compiler accepts, the compatibility policy, and the three absences of a type: unknown, Any, and Dynamic.
Directives and markers	@ppy.pure, @ppy.native, @ppy.jit, @ppy.dynamic and the rest; fixed-width integers, Buffer[T], Range, ownership.
Classes	Value classes and object classes in native code: trees, linked nodes, class Stack[T].
Collections	Vec, Deque, Heap, LinkedList, HashMap, HashSet, TreeMap, TreeSet: containers that compile, with no pointers.
Native memory and FFI	ppy.native pointers, stack allocation, extern and export, and ppy.ffi over them.
Lanes and the machine	ppy.simd vectors and ppy.cpu features, hints, and targets.
Atomics and threads	ppy.atomic with C11 orders; ppy.concurrent spawn, join, mutex, condition, barrier.
Parallel loops	parallel.range, reductions, and what the body may do.
Derivatives	ppy.grad and ppy.value_and_grad, one rule table on every path.
Coroutines	ppy.aio: sockets and sleeps under asyncio or the native epoll loop.
GPU kernels	ppy.cuda and ppy.hip: kernels in Python, PTX under ppy run.
Common tensors	Tensor[dtype, shape], bfloat16, mutable borrows, and backend storage.
XLA	@xla.jit: StableHLO from the compiler, run through PJRT.
Generics	Type parameters, bounds, monomorphization, static dispatch.
Effects and the three paths	The effect vocabulary, purity, and why three ways of running agree.
Reading input	ppy.input reads lines, ppy.scan reads tokens, ppy.read_* fill a buffer.
Native lowering	When a function gets a boundary, and what its parameters may be.
Regular expressions	A pattern compiled from a bytes literal, matched natively over a byte buffer.