docs(python): bring README + Counters docstring in sync with current API - #6
Merged
Merged
Conversation
Seven specific staleness items in the Python-binding documentation,
spread across two files. The .pyi stubs and the PyO3 wrapper were
already correct; only the human-readable docs had drifted since the
spillway feature landed (2026-05-04).
README.md fixes:
1. "Opening a database" snippet — replaced the old kwarg
`cache_size=1024 # pages in the LRU` with the current
`cache_max_bytes=8_388_608 # bytes`. The old form raises
TypeError if a user copies the snippet verbatim.
2. Operational-error table — added two previously-undocumented
rows that are already registered, in __all__, and in the .pyi:
- TransactionInProgressError (reserved for future use; the
v1 binding doesn't expose the runtime config setters that
produce it)
- SpillwayFullError (reserved for future use; spillway is
currently hard-coded to 0 in the binding)
3. "Engine counters" bullet list — fsync_calls description was
"two per commit (data pages, then superblock)"; post-spillway
the no-spill commit cost is three (pre-drain flush + main
pages flush + superblock).
4. "Engine counters" code-example comment — same "commit cost: 2"
issue; now "commit cost: 3 (pre-drain + data + superblock)".
5. CacheFullError row + pages_allocated bullet — removed
"hard ceiling" terminology. Pre-spillway the cache had an
elastic 8x ceiling that could grow past cache_max_bytes;
post-spillway the cache is a strict bound and overflow goes
to the spillway sidecar (when enabled). Since the binding
currently disables the spillway, CacheFullError fires at the
strict cap; description now reflects that.
chisel/__init__.py fixes:
6. Counters docstring fsync_calls field description — same
"two per commit" → "three per commit" fix as README #3.
7. (No __init__.py edit for pages_allocated; the docstring
there is already terse and doesn't reference "hard ceiling".)
No code changes. Behavior is unchanged.
A follow-up will decide whether to expose spillway controls in
the binding's open() and add the runtime config setters
(set_cache_max_bytes / set_spillway_max_bytes / set_drain_insertion)
to PyChisel. The current "deferred until the Rust side has
stabilized" comment in src/db.rs is itself stale — the Rust side
HAS stabilized — but that decision is intentionally not bundled
with this docs catch-up.
5 tasks
🚦 Bench results: PR vs main
Per-scenario detail (4 metrics × cells)document-store
mutation-log
ycsb-a
ycsb-b
|
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes seven specific documentation-staleness items in the Python binding, surfaced by a fresh API-vs-docs review against the current Rust side. The
.pyistubs, PyO3 wrapper, and exception mapping were already correct; only the human-readable docs had drifted since the spillway feature landed (2026-05-04).What was stale (and why each fix matters)
python/README.md"Opening a database"cache_size=1024(the old per-page kwarg)cache_max_bytes=8_388_608(current per-byte kwarg). The old form raisesTypeErrorif copied verbatim — most user-impacting bug here.python/README.mdoperational-error tableTransactionInProgressErrorrow absentpython/README.mdoperational-error tableSpillwayFullErrorrow absentspillway_max_bytes=0)python/README.mdEngine counters bulletsfsync_calls: "two per commit"python/README.mdEngine counters example# commit cost: 2 (data + superblock)# commit cost: 3 (pre-drain + data + superblock)python/README.mdCacheFullError row + pages_allocated bulletpython/chisel/__init__.pyCounters docstringfsync_calls: "two per commit"Out of scope (deliberate)
The PyO3 wrapper at
python/src/db.rs::open()hard-codesspillway_max_bytes: 0anddrain_insertion: LruTailwith a comment that says "deferred until the Rust side has shipped and stabilized." The Rust side has shipped and stabilized, so that comment is itself stale — but the decision of whether to expose spillway controls (and the three runtime config setters:set_cache_max_bytes/set_spillway_max_bytes/set_drain_insertion) is its own design call. That's a separate follow-up PR, not this one.Test plan
grep -n 'cache_size=1024|two per commit|hard ceiling|commit cost: 2' python/README.md python/chisel/__init__.py python/chisel/chisel.pyi— 0 matchespython3 -c "import ast; ast.parse(open('python/chisel/__init__.py').read())"— syntax OK