📝 Add performance optimization design document - #37
Merged
Conversation
Three-big-wins strategy for closing the 21-benchmark performance gap vs CPython pathlib: 1. Shallow parsing — skip full parse for ops that don't need it 2. _make_child_fast — direct Rust construction, no Python round-trip 3. Inline short paths — CompactOsString + OnceLock + inline ParsedPath Detailed root-cause analysis, Rust code sketches, allocation profiling, implementation plan in 6 steps with verification gates.
BENCHMARKS.md, CHECKLIST.md, DESIGN.md, OPTIMIZATION.md → docs/ Update all cross-references in README.md and AGENTS.md.
Move verbose code examples, benchmark table, feature coverage, architecture diagram, and marketing prose to the existing docs/ files they duplicate. README now covers: quick tour, pure/concrete class tables, benchmark summary, dev commands, doc links.
…ectory The Makefile copies files directly into site-packages/pathlibrs/, so the intermediate pathlibrs/ subdir was unnecessary. Update DESIGN.md file tree and reference.
Move .pyi stubs directly into pathlibrs/ at repo root. No conflict with the Rust crate (source is in src/, Cargo.toml) and no import collision (_no_ __init__.py in this directory).
…ckage Python 3.3+ namespace packages pick up pathlibrs/ directory at repo root when the working dir is on sys.path. This shadows the installed .so on CI, causing 'module has no attribute Path' for all tests.
Replace step-summary-only output with a PR comment that updates in-place on each push using a hidden marker for deduplication. Benchmark json generated in one job, passed via artifact to a separate comment-posting job that creates or updates the comment.
Fork PRs get read-only GITHUB_TOKEN so the inline comment job returns 403. Split into two workflows: 1. ci.yml benchmarks job uploads benchmark-comment.md artifact 2. benchmark-comment.yml triggers on workflow_run completion, downloads artifact, posts/updates comment using main-branch token with full pull-requests:write permission.
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
2 participants
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
Adds
OPTIMIZATION.md— a detailed performance optimization design document and updatedCHECKLIST.mdwith Phase 6 tracking.Context
Current benchmark state: 14 faster, 21 slower, 4 at parity vs CPython 3.14 pathlib.
Three-Win Strategy
Shallow parsing — Skip full parse for ops that only need byte-level manipulation (
parent,truediv,joinpath,with_*). Currently all trigger full parse + per-part allocations._make_child_fast— Direct Rust-native path construction with subclass-override detection. Cuts 3 FFI crossings per result down to 1.Inline short paths —
CompactOsString(30-byte inline),OnceLockreplacingMutexforpath_info, inlinedParsedPath(noBox). Drops construction from 7 → 1 heap allocation.Contents
Test Plan
make fmt-check-rustpasses