|
1 | 1 | # Next Work Package |
2 | 2 |
|
3 | | -## Step: Expand docs landing page to all 6 languages |
| 3 | +## Step: Fix Python ruff format CI failure |
4 | 4 |
|
5 | 5 | ## Goal |
6 | 6 |
|
7 | | -Add Node.js, Java, Go, and WASM tabs to the Quick Start section in `docs/index.md` and add Java and |
8 | | -Go rows to the Available Bindings table. This closes the target gap "All code examples use tabbed |
9 | | -multi-language format" before the v0.0.1 release. |
| 7 | +Fix the `ruff format --check` failure in CI that is blocking the Python job (and thus pytest) from |
| 8 | +passing. The `_lowlevel.pyi` file has a single line-length formatting violation introduced by the |
| 9 | +interactive session commit `5461a65` (CPython C API optimizations for video functions). |
10 | 10 |
|
11 | 11 | ## Scope |
12 | 12 |
|
13 | 13 | - **Create**: (none) |
14 | | -- **Modify**: `docs/index.md` |
15 | | -- **Reference**: `docs/howto/nodejs.md`, `docs/howto/java.md`, `docs/howto/go.md`, |
16 | | - `docs/howto/wasm.md` (for idiomatic code patterns in each language) |
| 14 | +- **Modify**: `crates/iscc-py/python/iscc_lib/_lowlevel.pyi` |
| 15 | +- **Reference**: (none — the fix is mechanical formatting) |
17 | 16 |
|
18 | 17 | ## Not In Scope |
19 | 18 |
|
20 | | -- Fixing the existing Rust and Python Quick Start examples (they have minor inaccuracies — Rust |
21 | | - shows `println!("{result}")` as "JSON string" when it's a struct; Python uses `json.loads` when |
22 | | - the binding returns a dict-like object directly). These should be fixed but in a separate step |
23 | | -- Adding the `Key Features` bullet to mention Java and Go (currently says "Rust, Python, Node.js, |
24 | | - WebAssembly, or C") — cosmetic, defer |
25 | | -- Fixing the WASM howto guide package name (`@iscc/iscc-wasm` → `@iscc/wasm`) — pre-existing issue |
26 | | - in a different file |
27 | | -- Restructuring the page layout or adding new sections beyond Quick Start tabs and binding table |
28 | | - rows |
| 19 | +- Modifying any Rust code (`lib.rs`, `src/*.rs`) |
| 20 | +- Modifying `__init__.py` (already passes `ruff format --check`) |
| 21 | +- Investigating or changing the CPython C API logic in `crates/iscc-py/src/lib.rs` |
| 22 | +- Any other Python source changes beyond formatting |
| 23 | +- Tagging v0.0.1 or creating PRs (separate future step) |
29 | 24 |
|
30 | 25 | ## Implementation Notes |
31 | 26 |
|
32 | | -Add 4 new tabs to the `=== "Language"` tabbed block under Quick Start. Follow |
33 | | -[pymdownx.tabbed](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/) syntax |
34 | | -(already used by the existing Rust/Python tabs). Each tab shows install command + minimal code |
35 | | -example. |
| 27 | +Run `uv run ruff format crates/iscc-py/python/iscc_lib/_lowlevel.pyi` to apply canonical formatting. |
| 28 | +The only change is splitting the `gen_video_code_v0` function signature across multiple lines to |
| 29 | +satisfy the line-length limit: |
36 | 30 |
|
37 | | -**Tab order**: Rust, Python, Node.js, Java, Go, WASM (matches target.md ordering and Available |
38 | | -Bindings table). |
| 31 | +```diff |
| 32 | +-def gen_video_code_v0(frame_sigs: Sequence[Sequence[int]], bits: int = 64) -> dict[str, Any]: |
| 33 | ++def gen_video_code_v0( |
| 34 | ++ frame_sigs: Sequence[Sequence[int]], bits: int = 64 |
| 35 | ++) -> dict[str, Any]: |
| 36 | +``` |
39 | 37 |
|
40 | | -**Code patterns per language** (derived from howto guides and agent memory): |
41 | | - |
42 | | -- **Node.js** (`=== "Node.js"`): `npm install @iscc/lib`, then |
43 | | - `import { gen_text_code_v0 } from "@iscc/lib"` — returns a string directly (not structured |
44 | | - object) |
45 | | -- **Java** (`=== "Java"`): Maven dependency XML block or `System.loadLibrary` note, then |
46 | | - `IsccLib.genTextCodeV0("Hello World", 64)` — returns a String. Note that Maven Central is not |
47 | | - yet available (build from source). Use `import io.iscc.iscc_lib.IsccLib;` |
48 | | -- **Go** (`=== "Go"`): `go get github.com/iscc/iscc-lib/packages/go`, then show Runtime creation + |
49 | | - `rt.GenTextCodeV0(ctx, "Hello World", 64)` — returns `(string, error)`. Go requires more |
50 | | - boilerplate (runtime setup) so keep the example minimal but correct |
51 | | -- **WASM** (`=== "WASM"`): `npm install @iscc/wasm`, then |
52 | | - `import init, { gen_text_code_v0 } from "@iscc/wasm"` + `await init()` — returns a string. Note |
53 | | - the async init requirement |
54 | | - |
55 | | -**Available Bindings table**: Add rows for Java (Maven Central, `io.iscc:iscc-lib`, note not yet |
56 | | -published) and Go (Go module, `go get github.com/iscc/iscc-lib/packages/go`). |
57 | | - |
58 | | -**Consistency**: All 6 tabs should demonstrate the same function (`gen_text_code_v0` with "Hello |
59 | | -World") to make cross-language comparison easy. |
| 38 | +After applying, run `mise run format` to ensure all pre-commit auto-fix hooks are satisfied, then |
| 39 | +stage and commit. |
60 | 40 |
|
61 | 41 | ## Verification |
62 | 42 |
|
63 | | -- `uv run zensical build` exits 0 (docs site builds without errors) |
64 | | -- `grep -c '=== "' docs/index.md` returns 6 (one tab per language) |
65 | | -- `grep 'Node.js' docs/index.md` matches (Node.js tab present) |
66 | | -- `grep 'Java' docs/index.md` matches (Java tab and binding table row present) |
67 | | -- `grep 'Go' docs/index.md` matches (Go tab and binding table row present) |
68 | | -- `grep 'WASM' docs/index.md` matches (WASM tab present) |
69 | | -- `grep 'go get' docs/index.md` matches (Go install command in table or tab) |
70 | | -- Available Bindings table has 7 rows (Rust, Python, Node.js, WASM, C/C++, Java, Go) |
71 | | -- `mise run check` passes (formatting, linting) |
| 43 | +- `uv run ruff format --check crates/iscc-py/python/iscc_lib/` exits 0 |
| 44 | +- `uv run ruff check crates/iscc-py/python/iscc_lib/` exits 0 (still passes) |
| 45 | +- `mise run check` passes — all pre-commit hooks clean |
72 | 46 |
|
73 | 47 | ## Done When |
74 | 48 |
|
75 | | -All verification criteria pass — docs/index.md has 6 language tabs in Quick Start and 7 binding rows |
76 | | -in the table, and the docs site builds cleanly. |
| 49 | +All three verification criteria pass, confirming the formatting fix restores CI-green status for the |
| 50 | +Python job. |
0 commit comments