p5py-vibe 0.4.0

A Pythonic creative coding package inspired by p5.js.

p5py

p5py is a friendly Python creative-coding library inspired by p5.js. It is for people who want to sketch with code: draw shapes, animate motion, react to input, load images, play with pixels, and make small visual experiments without first building a full app.

The public API is Python-first. Function names use snake_case, sketches are ordinary Python files, and the renderer is powered by the packaged Rust canvas runtime.

Install

pip install p5py-vibe

Install optional media helpers when you need camera, video, or sound-related extras:

pip install "p5py-vibe[media]"

First Sketch

Create a file named circle_sketch.py:

import p5


@p5.setup
def setup() -> None:
    p5.create_canvas(400, 300)
    p5.no_stroke()


@p5.draw
def draw() -> None:
    p5.background(245)
    p5.fill(255, 90, 90)
    p5.circle(200, 150, 100)


p5.run()

Run it:

python circle_sketch.py

For repeatable scripts, use a bounded headless render:

p5.run(headless=True, max_frames=1)

Callbacks can also be async def, which is useful with async-compatible asset helpers:

image = None


@p5.preload
async def preload() -> None:
    global image
    image = await p5.load_image_async("sprite.png")

What You Can Make

• 2D drawings with shapes, curves, color, transforms, and blend modes.
• Animated sketches using the familiar setup() and draw() lifecycle.
• Decorator-based sketches, async-compatible callbacks, and object-oriented Sketch subclasses.
• Image and pixel experiments, including canvas export.
• Text, font measurement, and accessibility descriptions.
• Interactive sketches with mouse, keyboard, and touch state when native window support is available.
• WEBGL-style 3D sketches with primitives, lights, materials, models, textures, and shader objects on the current Rust-backed software 3D path.
• Small games and visual toys using the examples as starting points.

Loaded images keep their Rust-managed asset until you mutate pixels, so normal load_image(); image(...) sprite drawing can stay on the fast renderer path. Image-local resize, mask, filter, crop/copy, and alpha compositing delegate bulk byte work to the Rust canvas extension while keeping the Python Image API and version semantics. For pixel effects, load_pixels() keeps the compatibility list API and load_pixel_bytes() provides a bytes readback path; update_pixels() accepts lists and buffer-like inputs such as bytes, bytearray, and memoryview. Small canvas get() and set() region operations use Rust region calls where possible instead of reconstructing the full canvas as a Python image. For dense drawing loops, p5.fast() returns a frame-local facade that keeps public style/transform state while reducing global-mode dispatch overhead. Opt-in enable_performance_diagnostics() counters can identify readback, pixel conversion, upload, texture cache, and CPU compositing fallback paths.

Learn More

• Getting started
• Examples
• API reference
• Contributor docs

For Contributors

This repository uses uv for Python commands:

uv sync --dev
uv run ruff check .
uv run mypy src
uv run pytest

The canvas runtime is a required PyO3 extension:

uvx maturin develop --manifest-path crates/p5_canvas/Cargo.toml --module-name p5.rust._canvas --python-source src --features extension-module

The contributor documentation explains the architecture, lifecycle, testing workflow, and release shape in more detail:

• Contributor guide
• Architecture
• Runtime model
• Runtime diagnostics
• Build capabilities
• API performance policy
• Testing and CI

Performance benchmarks are opt-in:

uv run pytest tests/benchmark/test_canvas_backend_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_api_overhead_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_image_pipeline_perf.py --run-benchmarks
uv run pytest tests/benchmark/test_webgl_3d_perf.py --run-benchmarks

Canvas benchmark scenarios are expected to average at least 120 FPS. Failures below that floor are intentional optimization signals. Machine-specific baseline snapshots live in tests/benchmark/baselines/.

Long-running resource lifecycle checks are also opt-in:

uv run pytest tests/stress --run-stress -q -s

Compatibility

p5py is inspired by p5.js, but it is not a browser port. It does not include DOM helpers, browser-only APIs, JavaScript aliases, or a Pillow/Pyglet fallback. Unsupported features raise explicit package errors so sketches fail clearly.