Metadata-Version: 2.4
Name: rpi-display-core
Version: 1.1.2
Summary: Python display framework for Raspberry Pi, currently focused on SSD1306 and SH1106 OLEDs
Author-email: Andre Faria <andremarcalfaria@gmail.com>
Project-URL: Homepage, https://github.com/andremmfaria/rpi-display-core
Project-URL: Repository, https://github.com/andremmfaria/rpi-display-core
Project-URL: Issues, https://github.com/andremmfaria/rpi-display-core/issues
Keywords: raspberry-pi,raspberrypi,display,oled,ssd1306,sh1106,i2c
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: adafruit-blinka>=9.0.4
Requires-Dist: adafruit-circuitpython-ssd1306>=2.12.23
Requires-Dist: luma-core>=2.5.3
Requires-Dist: luma-oled>=3.15.0
Requires-Dist: pillow>=11.3.0

# rpi-display-core

`rpi-display-core` is a Python display framework for Raspberry Pi projects.

Today it supports SSD1306 and SH1106 OLED displays through dedicated backends under `rpi_display.displays`, while keeping the shared drawing and widget framework generic.

## Install

### From the repository

```bash
git clone https://github.com/andremmfaria/rpi-display-core.git
cd rpi-display-core
uv sync
```

### From PyPI

```bash
uv add rpi-display-core
```

Import it as:

```python
from rpi_display import Runner, canvas
from rpi_display.displays.ssd1306 import SSD1306Display
```

## What it provides

- `rpi_display.displays.ssd1306.SSD1306Display` — SSD1306 display wrapper for Raspberry Pi
- `rpi_display.displays.sh1106.SH1106Display` — SH1106 display wrapper for Raspberry Pi
- `canvas(display)` — context manager that creates a fresh PIL image and flushes it on exit
- `Runner` — simple fixed-FPS render loop
- `MockDisplay` — hardware-free test helper
- Built-in widgets for text, progress bars, clocks, network info, system stats, and spinners

## Quick example

```python
from rpi_display import Runner
from rpi_display.displays.ssd1306 import SSD1306Display
from rpi_display.widgets.clock import ClockWidget

Runner(SSD1306Display(), ClockWidget(), fps=1).run()
```

## Display integrations

```python
from rpi_display.displays.ssd1306 import SSD1306Display
from rpi_display.displays.sh1106 import SH1106Display
```

Other display chips can follow the same pattern under `rpi_display.displays`.

## Widget modules

```python
from rpi_display.widgets.text import Text, MultiLineText, ScrollingText
from rpi_display.widgets.shapes import ProgressBar
from rpi_display.widgets.clock import ClockWidget
from rpi_display.widgets.system import SystemStatsWidget
from rpi_display.widgets.network import NetworkWidget
from rpi_display.widgets.spinner import Spinner
```

## Examples

The repository includes ready-to-run examples in [`examples/`](./examples/):

- `01_hello_world.py`
- `02_system_stats.py`
- `05_animation.py`
- `07_clock.py`
- `09_systemd_service.py`
- `10_sh1106_system_stats.py`

## Raspberry Pi setup

For wiring, I2C enablement, uv-based setup, and systemd instructions, see [`SETUP.md`](./SETUP.md).

## Development workflow

```bash
uv sync
uv run pytest
uv run ruff check .
uv run black --check .
uv run isort --check-only .
uv run mypy
```

## Build and validate for PyPI

```bash
uv build
uvx twine check dist/*
```

## Publish

```bash
uv publish
```

## Current scope

- Raspberry Pi focused
- SSD1306 and SH1106 support implemented today
- Architecture intended to grow to more display types later
