Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
# Builds the sdist/wheel and publishes graphik to PyPI when a version tag is
# pushed. Publishing uses PyPI Trusted Publishing (OIDC) -- no API token is
# stored in the repo. See RELEASING.md for the one-time PyPI configuration and
# the release procedure.
# Builds the sdist/wheel and publishes graphik to PyPI. Publishing uses PyPI
# Trusted Publishing (OIDC) -- no API token is stored in the repo.
#
# Manual only: graphik is released as git tags that consumers install from the
# tag's source archive (see RELEASING.md), and no PyPI project is set up. The workflow is
# kept so PyPI can be turned on later: do the one-time setup it needs, then
# run it from the Actions tab against a v-tag (the tag check below compares
# the ref name with __version__).
name: Publish to PyPI

on:
push:
tags:
- "v*.*.*"
workflow_dispatch:

# Least privilege by default; the publish job opts into id-token below.
permissions:
Expand Down
53 changes: 52 additions & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Runs the test suite on every push and pull request so regressions are
# caught before merge, rather than relying solely on manual local validation.
# See RELEASING.md / publish.yml for the separate publish-on-tag workflow.
# See RELEASING.md for releases; publish.yml (manual-only PyPI publish) is separate.
name: Test

on:
Expand Down Expand Up @@ -54,3 +54,54 @@ jobs:
SDL_VIDEODRIVER: dummy
SDL_AUDIODRIVER: dummy
run: python -m pytest

archive-install:
# Consumers install graphik from a release tag's source archive, e.g.
# graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.3.0.zip
# (see RELEASING.md). This job builds the same kind of archive from the
# commit under test -- a zip with one top-level graphik-<version>/ folder,
# as GitHub serves it -- installs it into a fresh venv the way a consumer's
# `pip install -r requirements.txt` would, and draws with it. Unlike an
# import of the package alone, drawing loads graphik.py and pygame, so a
# build that dropped either fails here. An archive install never calls git.
name: Install from a release archive
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- uses: actions/setup-python@v5
with:
python-version: "3.13"

- name: Build a GitHub-style source archive
run: |
VERSION="$(python -c 'import sys; sys.path.insert(0, "src/main/python"); from preponderous.graphik._version import __version__; print(__version__)')"
git archive --format=zip --prefix="graphik-${VERSION}/" -o "$RUNNER_TEMP/graphik.zip" HEAD
echo "VERSION=$VERSION" >> "$GITHUB_ENV"

- name: Install the archive into a fresh venv
run: |
python -m venv "$RUNNER_TEMP/consumer"
"$RUNNER_TEMP/consumer/bin/python" -m pip install --upgrade pip
"$RUNNER_TEMP/consumer/bin/python" -m pip install "graphik @ file://$RUNNER_TEMP/graphik.zip"

- name: Import and draw with the installed package
# Run from outside the checkout so only the installed copy is importable.
working-directory: ${{ runner.temp }}
env:
SDL_VIDEODRIVER: dummy
SDL_AUDIODRIVER: dummy
run: |
"$RUNNER_TEMP/consumer/bin/python" - <<'PY'
import os
import pygame
import preponderous.graphik as package
from preponderous.graphik import Graphik

assert package.__version__ == os.environ["VERSION"], package.__version__
assert "site-packages" in package.__file__, package.__file__
surface = pygame.Surface((20, 20))
Graphik(surface).drawRectangle(2, 2, 10, 10, Graphik.red)
assert tuple(surface.get_at((5, 5)))[:3] == Graphik.red
print("installed graphik", package.__version__, "draws OK from", package.__file__)
PY
46 changes: 35 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,30 @@

This library assists developers with graphics programming.

![Rectangles, centred text, a button and an image drawn with graphik](docs/images/hero.png)

*Every draw method, rendered by graphik itself (`scripts/make_readme_images.py`).*

## Installation
`graphik` has not been published to PyPI yet (see [RELEASING.md](RELEASING.md)
for the release process), so `pip install graphik` will not resolve until the
first release is published. Until then, install directly from this repository:
graphik is released as git tags, not on PyPI. Install a release from its tag's
archive (no `git` needed):
```bash
pip install git+https://github.com/Stephenson-Software/graphik.git
```
Once a release is published, it will be installable with:
```bash
pip install graphik
pip install "graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.3.0.zip"
```
In a `requirements.txt`, use the same line without the quotes. See
[RELEASING.md](RELEASING.md) for how releases are cut.

## Dependents
These games use graphik. When a release goes out, each one gets a pull request
that bumps the tag in its `requirements.txt`:

| Game | Repository |
|---|---|
| Roam | [Preponderous-Software/roam](https://github.com/Preponderous-Software/roam) |
| Ophidian | [Preponderous-Software/ophidian](https://github.com/Preponderous-Software/ophidian) |
| Apex | [Preponderous-Software/apex](https://github.com/Preponderous-Software/apex) |
| Rock Paper Scissors 2D | [Stephenson-Software/Rock-Paper-Scissors-2D](https://github.com/Stephenson-Software/Rock-Paper-Scissors-2D) |
| Tic Tak Toe | [Stephenson-Software/Tic-Tak-Toe](https://github.com/Stephenson-Software/Tic-Tak-Toe) |

## Usage
```python
Expand All @@ -30,12 +43,14 @@ while running:
if event.type == pygame.QUIT:
running = False

graphik.beginFrame() # optional: buttons fire once per click instead of while held
gameDisplay.fill(Graphik.black)
graphik.drawRectangle(100, 100, 200, 50, Graphik.blue)
graphik.drawText("Hello, world!", 200, 125, 24, Graphik.white)
graphik.drawButton(100, 200, 200, 50, Graphik.green, Graphik.black, 24, "Click me", lambda: print("clicked"))
graphik.drawImage("path/to/image.png", 100, 300, 200, 200) # replace with a real image file
pygame.display.update()
graphik.endFrame()

pygame.quit()
```
Expand All @@ -48,7 +63,13 @@ Public `Graphik` methods:
- `getVersion()` — returns the installed graphik version string.
- `drawRectangle(xpos, ypos, width, height, color)` — `xpos`/`ypos` are the rectangle's top-left corner.
- `drawText(text, xpos, ypos, size, color)` — `xpos`/`ypos` are the **center** of the rendered text, not its top-left corner. This differs from `drawRectangle`, `drawButton` and `drawImage`, which all position their top-left corner at the given coordinates. Glyph edges are antialiased, blending with whatever is already on the surface. The text is always rendered as a single line — a `"\n"` is not a line break, so multi-line text needs one call per line — and a null character (`"\0"`) raises `ValueError` before anything is painted.
- `drawButton(xpos, ypos, width, height, colorBox, colorText, sizeText, text, function)` — draws a rectangle and centered text, and calls `function()` on every call where the mouse is held inside the button with button 1 down (there is no click-edge detection, so a held-down mouse fires `function()` once per call, not once per click). Callers wanting once-per-click semantics must debounce on their side. The clickable region is exactly the drawn box — `xpos` through `xpos + width - 1`, and `ypos` through `ypos + height - 1` — so buttons laid out edge to edge share no clickable coordinate. The hit test uses `pygame.mouse.get_pos()`, which is in window coordinates, so this only holds when the `Graphik` is bound to the display itself (or another surface whose top-left sits at the window's origin): bound to a subsurface or an off-screen surface blitted elsewhere, the box is painted at that surface's position but stays clickable at `xpos`/`ypos` relative to the window. The label is not clipped to the box: one too large for it overflows past the box edges, and that overflow is painted but not clickable. Reading the mouse needs the video system, so unlike `drawRectangle` and `drawText` it raises `pygame.error` (after painting) when neither `pygame.init()` nor `pygame.display.init()` has been called, even for an off-screen surface; no display mode is needed.
- `beginFrame()` — call once at the top of each frame to make `drawButton` fire once per click instead of while held. Calling it again in the same frame does nothing, so nested screens can each call it. A press that is already held when the first `beginFrame()` runs, or that slides onto a button while held, doesn't count, and each press fires at most one button.
- `endFrame()` — call once at the end of each frame started with `beginFrame()`. A frame that misses it (an exception, an early return) doesn't leave clicks stuck: the next `beginFrame()` notices the mouse button changed and takes a new snapshot.
- `drawButton(xpos, ypos, width, height, colorBox, colorText, sizeText, text, function)` — draws a rectangle and centered text, and calls `function()` when the button is clicked. By default it fires on every call where the mouse is held inside the button with button 1 down (once per call, not once per click), as earlier versions did. After the first `beginFrame()` call on the instance, it fires once per click instead: only in the frame where button 1 goes down inside the button. While the mouse is over the box, the box is drawn in a lifted color (light colors darken by 25, dark ones lighten by 35, per channel, clamped; the label color is unchanged), so it reads as clickable. The clickable region is exactly the drawn box — `xpos` through `xpos + width - 1`, and `ypos` through `ypos + height - 1` — so buttons laid out edge to edge share no clickable coordinate. The hit test uses `pygame.mouse.get_pos()`, which is in window coordinates, so this only holds when the `Graphik` is bound to the display itself (or another surface whose top-left sits at the window's origin): bound to a subsurface or an off-screen surface blitted elsewhere, the box is painted at that surface's position but stays clickable at `xpos`/`ypos` relative to the window. The label is not clipped to the box: one too large for it overflows past the box edges, and that overflow is painted but not clickable. Reading the mouse needs the video system, so unlike `drawRectangle` and `drawText` it raises `pygame.error` (after painting) when neither `pygame.init()` nor `pygame.display.init()` has been called, even for an off-screen surface; no display mode is needed.

![Buttons with the mouse away and over them](docs/images/hover.png)

*The hover lift, rendered by `scripts/make_readme_images.py`.*
- `drawImage(filePath, xpos, ypos, width, height)` — caches the loaded and scaled surface by `filePath`, so an image edited on disk mid-run will not be picked up until the process restarts. `filePath` may be a `str` or a `pathlib.Path`, and is used as the key exactly as given: two spellings of one file (relative and absolute, or a `str` and a `Path`) are cached, and loaded, separately. Only the most recently requested size is kept per path, so drawing the same file at two alternating sizes rescales it on every call. Unlike the other draw methods, it raises `pygame.error` unless a display mode has been set with `pygame.display.set_mode`, even when the `Graphik` is bound to an off-screen surface. Only the first load of a path needs one: a path already in the cache keeps drawing to an off-screen surface with no display mode set.

Positions passed to the draw methods need not lie on the surface: anything drawn across its edge (including at negative coordinates) is clipped to it, with the part that falls off simply not painted — nothing raises, and nothing is shifted to fit.
Expand All @@ -75,10 +96,13 @@ source .venv/bin/activate
pip install -e ".[test]"
pytest
```
The suite is headless: `src/test/python/conftest.py` sets `SDL_VIDEODRIVER`/`SDL_AUDIODRIVER` to `dummy` before pygame touches a display, so no window is created and the tests run on a machine with no display attached. `pytest` alone works from the repo root because `[tool.pytest.ini_options]` in `pyproject.toml` points `testpaths` at `src/test/python` and `pythonpath` at `src/main/python`. `.github/workflows/test.yml` runs the same `pip install -e ".[test]"` + `pytest` sequence — preceded by a compile check and an import smoke test, across the supported Python versions — on every pull request and on every push to `main`. A push to a branch with no open pull request is not covered, so run `pytest` locally before opening one.
The suite is headless: `src/test/python/conftest.py` sets `SDL_VIDEODRIVER`/`SDL_AUDIODRIVER` to `dummy` before pygame touches a display, so no window is created and the tests run on a machine with no display attached. `pytest` alone works from the repo root because `[tool.pytest.ini_options]` in `pyproject.toml` points `testpaths` at `src/test/python` and `pythonpath` at `src/main/python`. `.github/workflows/test.yml` runs the same `pip install -e ".[test]"` + `pytest` sequence — preceded by a compile check and an import smoke test, across the supported Python versions — on every pull request and on every push to `main`. A second job, *Install from a release archive*, packs the commit the way GitHub serves a tag's archive, installs it into a fresh venv as a consumer would, and draws with it. A push to a branch with no open pull request is not covered, so run `pytest` locally before opening one.

The README images are generated, not hand-made. After changing how something draws, regenerate them with
`SDL_VIDEODRIVER=dummy python scripts/make_readme_images.py` and commit the updated `docs/images/*.png`.

## Projects
[Projects that utilize this library](https://github.com/Stephenson-Software/graphik/wiki/Projects)
The games that use graphik are listed under [Dependents](#dependents) above.

## 📄 License

Expand Down
102 changes: 43 additions & 59 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -1,77 +1,61 @@
# Releasing graphik

graphik is published to [PyPI](https://pypi.org/) via **Trusted Publishing**
(OIDC) — no API token is stored in this repository. Publishing is automated by
[`.github/workflows/publish.yml`](.github/workflows/publish.yml), which runs
when a version tag (`vX.Y.Z`) is pushed.
graphik is released as **git tags**. It isn't published to PyPI. Consumers
install a release from the tag's source archive on GitHub:

## One-time setup (maintainer)

These steps are prerequisites for the workflow to succeed and are done outside
this repository:
```
graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.3.0.zip
```

1. **Claim the project name on PyPI.** Register `graphik` (the
[`pyproject.toml`](pyproject.toml) `name`). `preponderous-graphik` is the
namespaced fallback if the name is unavailable.
2. **Configure a Trusted Publisher** on the PyPI project pointing at this repo:
- Owner: `Stephenson-Software`
- Repository: `graphik`
- Workflow filename: `publish.yml`
- Environment name: `pypi`
3. **Create a GitHub environment** named `pypi` (Settings → Environments). An
optional required-reviewer rule can be added there to gate each release.
pip downloads the archive and builds the wheel locally with setuptools, using
[`pyproject.toml`](pyproject.toml). This needs access to GitHub but not `git`,
which matters for players installing a game from source on Windows. (The
`git+https://...@v0.3.0` form also works where `git` is installed.)

## Cutting a release

1. Bump the single version source —
1. Bump the single version source,
[`src/main/python/preponderous/graphik/_version.py`](src/main/python/preponderous/graphik/_version.py)
(`__version__`). Every other version reference is derived from it.
2. Commit the bump and merge it to `main`.
3. Tag the release commit and push the tag:
(`__version__`). Every other version reference is derived from it. Use three
dot-separated parts (`0.3.0`), with no `.dev` suffix for a release.
2. Merge the bump to `main`, with green CI. The *Install from a release
archive* job in `test.yml` has already installed and drawn with an archive
built the same way as the tag's.
3. Tag the merge commit as `v` + `__version__`, push the tag, and create a
GitHub release for it:

````bash
git tag v0.2.0
git push origin v0.2.0
git tag -a v0.3.0 -m "graphik 0.3.0" <merge-sha>
git push origin v0.3.0
gh release create v0.3.0 --verify-tag --notes "<changes>"
````

4. The `Publish to PyPI` workflow then:
- verifies the tag matches `__version__` (a mismatch fails the build),
- builds the sdist and wheel,
- smoke-tests the built wheel: installs it, runs `import preponderous.graphik`,
and checks `__version__` against the tag. `Graphik` itself is imported
lazily on first access, so this step never loads `graphik.py` or
`pygame` — a wheel with a missing or broken `graphik.py`, or without a
working `pygame` dependency, would still pass it
(tracked in
[#46](https://github.com/Stephenson-Software/graphik/issues/46)),
- publishes to PyPI via Trusted Publishing.
4. Check that the tag installs and imports in a clean environment:

The tag must equal `v` + `__version__` (e.g. `__version__ = "0.2.0"` → tag
`v0.2.0`), and `__version__` must have at least three dot-separated parts,
because the trigger in `publish.yml` is the glob `v*.*.*`, which needs two dots
after the `v`. A tag that matches the trigger but whose version does not match
`__version__` fails the build before anything is published. A tag that does
not match the trigger fails silently instead: the workflow never runs and
nothing reports the missed release. That covers a tag **without** the `v`
prefix, and also a `v`-prefixed tag with fewer than three parts such as
`v1.0` — even when it equals `v` + `__version__`. (The `v0.1` tag on this
repository is of that shape, and would not trigger the workflow either.) The
`0.2.0` and `0.3.0.dev20260808` tags were pushed without the prefix, so the
publish workflow has never run (tracked in
[#34](https://github.com/Stephenson-Software/graphik/issues/34)).
````bash
python -m venv /tmp/g && /tmp/g/bin/pip install "graphik @ https://github.com/Stephenson-Software/graphik/archive/refs/tags/v0.3.0.zip"
SDL_VIDEODRIVER=dummy /tmp/g/bin/python -c "from preponderous.graphik import Graphik, __version__; print(__version__)"
````

## Installing (after the first publish)
5. Open a pull request in each repository in the README's
[Dependents](README.md#dependents) list that bumps the tag in its
`requirements.txt`.

Once the package is live on PyPI, consumers can replace their vendored copies
with a versioned dependency:
A released tag must never be moved or deleted: consumers' installs resolve it
by name, so moving it would change what they install without any change on
their side.

````bash
pip install graphik
````
## Earlier tags

```python
from preponderous.graphik import Graphik
```
`v0.1`, `0.2.0` and `0.3.0.dev20260808` were pushed before this process. The
last two have no `v` prefix. `v0.3.0` is the first release under it.

## PyPI (not in use)

Migrating the existing consumers (Roam, Apex, Ophidian, Patchwork, Tic-Tak-Toe)
off their vendored copies is tracked as follow-up work in the consumer repos.
[`.github/workflows/publish.yml`](.github/workflows/publish.yml) can build and
publish to PyPI with Trusted Publishing, but it runs only when started by hand
(`workflow_dispatch`). No PyPI project is set up. To turn it on: claim the
`graphik` name on PyPI (`preponderous-graphik` as a fallback), add a Trusted
Publisher for owner `Stephenson-Software`, repository `graphik`, workflow
`publish.yml`, environment `pypi`, create the `pypi` environment in this
repository's settings, then run the workflow against a `v` tag.
Binary file added docs/images/hero.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/hover.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading