Package graphik for proper release & distribution (replace vendored copies)

[dmccoystephenson]

Problem

graphik is consumed today by vendoring a pinned copy — every downstream project either adds graphik as a git submodule or copies graphik.py directly:

Consumer	How it pulls graphik in
Preponderous-Software/roam	submodule at src/lib/graphik/, from lib.graphik.src.graphik import Graphik
Preponderous-Software/apex	copied into src/lib/graphiklib/, from lib.graphiklib.graphik import Graphik
Preponderous-Software/ophidian	submodule at src/lib/graphik/
Preponderous-Software/patchwork	copied graphik.py
Stephenson-Software/Tic-Tak-Toe	git submodule graphik

There is no installable package and no real release mechanism. Consequences:

• Every consumer pins a different copy at a different commit; there's no single "version 0.2.0 of graphik" they can depend on.
• A bug fix here doesn't reach anyone until they manually bump a submodule or re-copy the file.
• Import paths differ per consumer (lib.graphik.src.graphik vs lib.graphiklib.graphik), so there's no canonical import graphik.
• Version metadata is inconsistent and unenforced: version.txt = 0.2.0 but pom.xml <version> = 0.2-alpha-1, and getVersion() returns an attribute that's never set.

Goal

Make graphik installable as a proper Python package with a real release/usage flow, so consumers can declare a versioned dependency (e.g. graphik==0.2.0) instead of vendoring source.

Packaging work required regardless of where we host it

1. Add packaging metadata — a pyproject.toml (PEP 621) declaring name, version, the pygame dependency, and the package layout. Retire the vestigial Java pom.xml (this is a Python project) or, if it's intentionally kept, stop treating it as a version source.
2. Settle the import path / layout. Today the module lives at src/main/python/preponderous/graphik/graphik.py (a Maven-style tree). Decide the canonical import — e.g. from preponderous.graphik import Graphik — and make the package build expose exactly that, so all consumers can converge on one import.
3. Single source of version truth. Pick one (likely pyproject.toml or version.txt) and have everything else — including getVersion() — read from it. Fix the current drift.
4. Build + publish workflow. A CI job (none exists yet) that builds an sdist/wheel and publishes on tag.

Distribution options (need a decision)

A. Public PyPI — standard, zero-infra, consumers just pip install graphik. Name availability on PyPI needs checking (graphik may be taken). Best reach; fully public.

B. Private index hosted on gateway — gateway already runs a Nexus instance (repo.dansplugins.com) serving Maven artifacts; Nexus OSS can also host PyPI-format repositories. Reusing it means no new infrastructure: publish wheels there and consumers install with an --index-url / pip.conf entry. Keeps releases in-house, consistent with how the Maven plugins are already distributed.

C. Interim: formalize the git-tag + submodule flow — until a package exists, at least cut real git tags/releases and standardize the submodule path/import across consumers, so everyone pins the same tagged commits. Lower effort, doesn't solve the "no pip install" problem but reduces drift.

Open questions

• Public (PyPI) vs in-house (gateway/Nexus) — or publish to both?
• Is the graphik name available on PyPI, and do we want the public namespace?
• Canonical import path and final package layout?
• Do we migrate existing consumers off vendored copies as part of this, or ship the package first and migrate them in follow-ups?

Filed as a design/discussion issue — the concrete packaging PRs (pyproject, version-source consolidation, CI publish) can be split out once the host + import-path decisions are made.

[dmccoystephenson]

Recommendation: publish to public PyPI (Option A)

Claim the name now. Checked availability — graphik is free on PyPI (so is preponderous-graphik as a namespaced fallback). The package name is the one effectively irreversible decision here, so registering graphik should happen before any other work.

Why public PyPI over an in-house index

The deciding factor is graphik's own stated purpose. The README is explicit: MIT-licensed, "maximum freedom for developers," "boost adoption," "position graphik as a widely used rendering and visualization library," with "no plans to move away from open source." A private index works against all of those — nobody can pip install graphik without first configuring a custom --index-url, which is exactly the friction that suppresses adoption.

On gateway: capacity is not the constraint — we can absolutely stand up a new service on gateway (a private PyPI index, a CI runner, a mirror, etc.), and Nexus already there could host a PyPI repo. The reason to prefer PyPI isn't "we can't host it" — it's that an in-house index contradicts the goal. The gateway/Nexus precedent (repo.dansplugins.com) fits the Minecraft plugins, which are distributed in-house by design for one community; graphik is a general-purpose library being pitched for broad public use. Different goal, different home.

Where gateway can still help, complementary to PyPI:

• A self-hosted CI runner for the build/publish-on-tag job.
• An optional internal mirror/cache of the published wheels for the Preponderous ecosystem builds.
• A staging index to smoke-test a release before pushing the public tag.

So: public PyPI as the source of truth; gateway in a supporting role if/when useful — not as the primary distribution channel.

Decision summary

• A (public PyPI) — recommended. Matches the adoption goal, zero friction for consumers.
• B (gateway/Nexus private index) — not the primary channel for this library (contradicts the public-adoption goal), though gateway is available for the supporting roles above.
• C (git-tag + submodule formalization) — useful only as an interim stepping stone, not a destination.

Suggested sequencing

1. Claim graphik on PyPI (reserve preponderous-graphik too).
2. Add pyproject.toml (PEP 621): name, version, pygame dep; retire the vestigial Java pom.xml.
3. Settle the canonical import — from preponderous.graphik import Graphik — and converge consumers onto it.
4. Single version source (pyproject.toml as truth; getVersion() reads it; kill the version.txt/pom.xml drift).
5. CI publish-on-tag via PyPI Trusted Publishing (OIDC, no stored token) — optionally on a gateway-hosted runner.
6. Migrate consumers (Roam, Apex, Ophidian, Patchwork, Tic-Tak-Toe) off vendored copies to a versioned pip install graphik dependency, in follow-up PRs.

Steps 2–4 are self-contained and could be picked up incrementally; steps 1, 5, 6 are decisions/cross-repo.

Recommendation drafted by Claude on behalf of Daniel Stephenson.

[dmccoystephenson]

Reopened — this issue was auto-closed in error when PR #10 merged. The merge commit's message contained the phrase "Does not close #5", and GitHub's keyword matcher does not parse negation: it matched the substring close #5 and closed the issue.

PR #10 only advances #5 (step 5 — the CI publish-on-tag workflow). The remaining work keeps this issue open:

• Step 1 — claim the graphik name on PyPI (manual account action).
• Step 6 — migrate consumers (Roam, Apex, Ophidian, Patchwork, Tic-Tak-Toe) off vendored copies to a versioned pip install graphik dependency (cross-repo follow-ups).

Reopened by Claude on behalf of Daniel Stephenson.