pygraphics

Native and pure-Python pygraphics for MicroPython, CircuitPython, and CPython. The C module can be built into MicroPython or CircuitPython, while the pure-Python package is available for users who prefer not to compile their own build. Import as pygraphics.

One release tag vX.Y.Z publishes both products at that version.

Install

# Native C extension (CPython desktop, Android, Pyodide)
pip install -i https://test.pypi.org/simple/ \
  --extra-index-url https://pypi.org/simple/ pydevices-pygraphics

# Pure Python, for MicroPython and CircuitPython
import mip
mip.install("pygraphics", index="https://PyDevices.github.io/mip")

Full options and verification: docs/installation.md.

Quick start

import pygraphics
from pygraphics import FrameBuffer, RGB565

fb = FrameBuffer(bytearray(160 * 128 * 2), 160, 128, RGB565)
fb.fill(0)
fb.fill_rect(10, 10, 40, 40, 0xF800)
print(pygraphics.implementation())  # native_cmod or pygraphics_python

pygraphics has zero external dependencies on any other PyDevices libraries or hardware modules. It functions as an independent, portable 2D graphics engine that can be used in any MicroPython, CircuitPython, or CPython project needing fast drawing primitives or off-screen framebuffer manipulation, regardless of whether you are using PyDevices displays.

pygraphics extends MicroPython's standard framebuf into a powerful 2D graphics engine while preserving full API compatibility:

• Zero Dependencies & Universal Use: No required external packages; usable in any Python application.
• Dual Invocation & Draw Class: Call methods directly on FrameBuffer instances (fb.circle(...)), invoke standalone canvas functions (pygraphics.circle(fb, ...)), or use the Draw styling context for maximum architectural flexibility.
• Exposed Attributes: Direct read-only access to .buf, .width, .height, .stride, .format, and .color_depth on every FrameBuffer instance.
• 24-bit True Color (RGB888): Supports 24-bit packed RGB color format (format constant RGB888), ideal for 24-bit displays as well as NeoPixel (WS2812B) and DotStar (APA102) LED matrix arrays.
• Dirty Area Returns: Drawing operations return an Area(x, y, w, h) bounding box so drivers can flush only modified screen regions.
• Rich Primitive Library: Standard shapes plus round_rect, circle, arc, triangle, polygon, and gradient_rect.
• Multi-Font Engine: Built-in 8x8 (text8), 8x14 (text14), 8x16 (text16), and custom Font support.
• Image & File I/O: Load and save images directly using load_image, save_image, export_framebuffer, BMP565, and PBM/PGM codecs.
• Colorkey Blitting: blit_transparent() for transparent sprite overlays.
• Native C Speed & Fallback Safety: C acceleration compiled for MicroPython, CircuitPython, and CPython wheels (TestPyPI pydevices-pygraphics), with a pure-Python fallback available whenever precompiled binaries are not present in the firmware or environment.

Links

• Documentation
• Source-linked API reference
• Source
• Issues
• Related: pydevices-examples

License

MIT (framebuf algorithms derived from MicroPython extmod/modframebuf.c, Damien P. George).

Build from source

Layout

pygraphics/
  micropython.mk / micropython.cmake / circuitpython.mk / setup.py
  src/                     # C sources + headers (gfx_*.h, font_8x*.h, qstrs)
  lib/pygraphics/            # pure-Python package (import pygraphics)
  tests/                   # native smoke / parity tests
  tools/                   # developer benchmarks / helpers
  docs/ scripts/ web/

CPython native (editable)

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python tests/test_area.py
.venv/bin/python tests/test_pygraphics.py
.venv/bin/python tests/test_subclass.py

Pure Python (no extension)

PYTHONPATH=lib python3 -c "import pygraphics; print(pygraphics.implementation())"

Parity testing (native vs pure-Python)

micropython tools/compare_graphics_run.py    # single interpreter
python tools/compare_graphics_matrix.py      # all desktop interpreters
micropython tools/compare_framebuf_mp.py     # C framebuf vs lib/pygraphics/framebuf.py

MicroPython

Clone as a sibling of micropython/:

workspace/
  pygraphics/     ← this repo
  micropython/

cd micropython/ports/unix
make submodules
make USER_C_MODULES=../../..
cd ../../..
./micropython/ports/unix/build-standard/micropython pygraphics/tests/test_area.py

CircuitPython (unix)

Adafruit’s Extending CircuitPython guide (and the design guide — native modules) describe adding shared-bindings/ + shared-module/ inside the CircuitPython tree. This repo keeps those sources out-of-tree under src/circuitpython_spike/ and applies them with ./apply_cp_patches.sh into a local (uncommitted) CircuitPython clone — Adafruit has no separate out-of-tree C-module path.

Clone as a sibling of circuitpython/:

# siblings: circuitpython/ and pygraphics/
./apply_cp_patches.sh --apply
cd ../circuitpython/ports/unix && make -j VARIANT=coverage

See the cmods workspace for an easier way to build this repo with other user C modules (MicroPython) or extensions (CircuitPython).

pydevices-examples integration

When this cmod is installed or linked, pygraphics.framebuf_backend() reports native and pygraphics.implementation() reports native_cmod. Otherwise the pure-Python package reports pygraphics_python.