TurboPython Examples

A gallery of example programs for TurboPython (tpy) — a compiler that translates Python to C++.

Most are real programs someone wrote to get a job done, ported to build and run with tpy; the rest are written here, to show one part of the language or library at a time or as applications of their own. The point is to show what TurboPython does with ordinary code, not to exercise the compiler with synthetic tests.

Examples

• shedskin/ — programs ported from the Shed Skin project, a Python-to-C++ compiler with goals close to TurboPython's. Third-party code, mixed licenses.
• landing/ — the short single-file programs shown in the code window on tpy-lang.org, each demonstrating one part of the language. Written for this project, MIT.
• basics/ — small single-file programs to run first: hello, a Brainfuck interpreter, Game of Life, an ASCII Mandelbrot. MIT.
• tplib/ — walkthroughs of the library, one type or module per file: the tplib containers, sockets and asyncio. MIT.
• programs/ — original applications with a command line and a job to do, one directory each, starting with a curl-like HTTP client. MIT.

The gallery is still small. Examples are added in small batches, and one appears only once it fully works: it compiles, runs to completion, and matches CPython's output wherever CPython can run it. Examples still waiting on compiler work are listed in TODO.md.

Requirements

• Linux or macOS
• Python 3.12+
• tpy-lang 0.6.2 — the version these examples target
• A C++23 compiler: g++ 13+ or clang++ 19+ — or none, if you use the bundled zig toolchain below

pip install "tpy-lang~=0.6.2"          # or: uv tool install "tpy-lang~=0.6.2"

If you don't have a suitable C++ compiler, install the bundled zig toolchain instead:

pip install "tpy-lang[bundled]~=0.6.2" # or: uv tool install "tpy-lang[bundled]~=0.6.2"

See tpy-lang.org for full installation instructions and the language documentation.

Running an example

Every ported example lives in its own directory and is self-contained, including any data files it reads:

git clone https://github.com/trozen/tpy-examples
cd tpy-examples/shedskin/<example-name>
tpy <example-name>.py

tpy compiles the program to a native binary and runs it. The entry point is always <example-name>.py, and programs/ follows the same layout. Examples needing extra setup say so in their own README. landing/, basics/ and tplib/ hold single files rather than directories, run the same way from inside their directory.

The build is optimized by default. Useful flags:

tpy --debug <example-name>.py     # unoptimized, with debug info: builds faster
tpy --dump-code <example-name>.py # inspect the generated C++

Running under CPython

Sources stay valid Python, so your editor and type checker still understand them. But a ported example is not a drop-in CPython script: it imports TurboPython types such as int32, and a few bind native libraries directly, which has no CPython equivalent.

Both running an example under CPython and resolving its imports for a type checker need compatibility stubs that currently ship only in a tpy-lang source checkout. So the CPython comparison we run while porting cannot yet be reproduced from a released package.

Verifying the examples

.verify/ is not an example directory. It holds the checks that keep the gallery honest: every example is built against the pinned compiler, the ones that can run unattended are run, and their output is compared with what was recorded when the port was verified. make test runs it; see .verify/README.md.

Gallery

E1M1, drawn by doom: a software BSP renderer in annotated Python, on SDL2 through TurboPython's native bindings.

A Cornell box, drawn by path_tracing: a Monte Carlo path tracer at ten thousand samples per pixel, with the material types dispatching through a @dynamic protocol.

Fire spreading through the demo text, drawn by tte's burn effect: TerminalTextEffects rewritten in TurboPython, where every character is an index into one list and every event a plain value.

Licensing

The directory boundary is the license boundary.

• shedskin/ — third-party programs copied from the Shed Skin project, each under its own terms, passed through unchanged. Many carry an author attribution and no license statement at all; others are GPL-2, GPL-3, or custom. Provided as-is. Check the individual example before reusing it. See shedskin/README.md.
• Everything else — MIT, see LICENSE. That covers everything this repository authors: the original examples in landing/, basics/, tplib/ and programs/, the READMEs, and the harness. Copy it freely.