Skip to content

Commit 08469c0

Browse files
codexByron
authored andcommitted
feat: expose native fixtures with Python post-processing
Python test suites need reusable read-only fixtures and a way to initialize or post-process them with ordinary closures. Bind the pinned `gix-testtools` fixture APIs through `gix.testtools` so Python callers share the native cache, versioning, archive, and creation-mode behavior instead of rebuilding it in Python. Pass `FixtureState` to Python producers and post-processors, preserve their return values and original exceptions, and detach during native work. Expose owned writable `TempDir` fixtures with context-manager cleanup, fixture input helpers, and the isolated native `git()` test oracle. Freeze the native tempfile registry without termination handlers before helpers request setup, preserving Python signal ownership. Forward hash features without enabling C-backed XZ support. Update the local checkout selector for `tests/tools`, ship type stubs, and document cache mutation rules, copy-mode limitations, callback reentrancy, and the supported API subset. Keep tests in disposable process workspaces. Validation on Apple Silicon macOS with Rust/Cargo 1.99.0: - Ordinary CPython 3.14.7: 110 discovered tests pass with two expected skips. - Free-threaded 3.14.7 with `PYTHON_GIL=0`: 110 tests, one expected skip. - SHA-1-only and SHA-256-only: 110 tests each, 75 expected skips. - Default and reduced clippy with warnings denied; seven Rust tests, nine helper checks, formatting, and `git diff --check` pass. - An ABI3 wheel rebuilt from its sdist passes all 110 discovered tests in an offline installation; artifact contents and fixture stubs are checked. - Local metadata resolves `gix-testtools` from the selected checkout. Project builds disable C/C++ compilers; dependency metadata fits Rust 1.89. - Final focused fixture and runtime/stub checks pass. No Intel/cross-platform builds, actual Rust 1.89 execution, or publication were performed. Read-only fixture paths remain a caller contract.
1 parent ef5e408 commit 08469c0

19 files changed

Lines changed: 880 additions & 30 deletions

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
99

1010
### New Features
1111

12+
- Expose native cached read-only and writable fixtures through `gix.testtools`,
13+
with Python closures for fixture creation and post-processing.
1214
- Select a local Gitoxide checkout for Python development builds with
1315
`GIXPYTHON_GITOXIDE_PATH` or `--gitoxide-path`, using a separate development
1416
lockfile. `--packaged` forces release dependencies. Local builds report checkout HEAD.

‎Cargo.lock‎

Lines changed: 105 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ crate-type = ["cdylib", "rlib"]
1616
[features]
1717
default = ["max-pure"]
1818
max-pure = ["sha1", "sha256", "max-performance", "revision", "revparse-regex", "index", "attributes", "dirwalk", "status", "blob-diff", "merge", "blame", "notes", "mailmap", "signing", "worktree-mutation", "worktree-stream", "worktree-archive", "https"]
19-
sha1 = ["gix/sha1", "gix-archive?/sha1"]
20-
sha256 = ["gix/sha256", "gix-archive?/sha256"]
19+
sha1 = ["gix/sha1", "gix-archive?/sha1", "gix-testtools/sha1"]
20+
sha256 = ["gix/sha256", "gix-archive?/sha256", "gix-testtools/sha256"]
2121
max-performance = ["gix/max-performance"]
2222
revision = ["gix/revision", "index"]
2323
revparse-regex = ["gix/revparse-regex", "revision"]
@@ -48,6 +48,7 @@ abi3 = ["pyo3/abi3-py311"]
4848
pyo3 = { version = "0.29.3", features = ["multiple-pymethods"] }
4949
gix = { git = "https://github.com/GitoxideLabs/gitoxide", rev = "09f85be4e3fda42f3e8fd19c53a63758fdf6fb3d", default-features = false, features = ["parallel", "auto-chain-error", "progress-tree"] }
5050
gix-archive = { git = "https://github.com/GitoxideLabs/gitoxide", rev = "09f85be4e3fda42f3e8fd19c53a63758fdf6fb3d", default-features = false, optional = true }
51+
gix-testtools = { git = "https://github.com/GitoxideLabs/gitoxide", rev = "09f85be4e3fda42f3e8fd19c53a63758fdf6fb3d", default-features = false, features = ["worktree-exclusions"] }
5152
reqwest = { version = "0.13.4", default-features = false, features = ["blocking"], optional = true }
5253
rustls = { version = "0.23.45", default-features = false, features = ["std", "tls12"], optional = true }
5354
rustls-graviola = { version = "=0.4.0", optional = true }

‎DEVELOPMENT.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,11 @@ Development builds continue using the local selection described above.
113113

114114
## Integration checks
115115

116+
Use [native cached fixtures](docs/testtools.md) through `gix.testtools` when
117+
tests only inspect stable repositories. Python closures can create fixtures
118+
or post-process scripted fixtures; writable helpers provide disposable copies
119+
for mutations. Do not write into shared read-only fixture directories.
120+
116121
Each new binding should have a focused Python integration check against a disposable repository. Verify errors as well as success, both supported hash kinds, and any meaningful reduced feature configuration. Compare with Git when it provides an appropriate reference result.
117122

118123
Threading checks share repository handles between Python threads and verify actual work with the GIL disabled. Lazy-API checks consume only a prefix and confirm that later results have not been eagerly produced. Long-running operations expose pollable `Progress.snapshot()` and `CancellationToken`; they must propagate Python interruption and release resources when stopped.

‎agents.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
- Preserve tagged and published history. Now that `v0.1.0` exists, create new commits for further changes, including CI fixes; do not amend earlier commits unless the user explicitly authorizes that specific amendment.
3939
- Keep packaging, type information, examples, contributor guidance, CI, security policy, and artifact-building configuration part of the project.
4040
- Tests use disposable repositories and isolated Git configuration/environment. Never mutate the developer's checkout, another worktree, or shared Git metadata as a fixture.
41+
- Test suites may use native cached read-only fixtures through `gix.testtools`; only their initialization/post-processing callback may modify them. Use writable fixtures for mutations. Python fixture callbacks are supported separately from the callback-free progress API, without repository state locks or native signal ownership.
4142
- The implementation sequence and persistent design decisions are in [docs/implementation-plan.md](docs/implementation-plan.md). Update its status as work lands; do not present planned coverage as completed.
4243

4344
## Current session boundary

‎docs/api-coverage.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,9 @@ policy for unavailable worktree encodings.
120120

121121
## Explicit limits and native behavior
122122

123+
- `gix.testtools` provides native cached fixtures, Python producers and
124+
post-processors, temporary writable copies, and isolated Git test commands.
125+
See [fixture APIs and limits](testtools.md).
123126
- Rust callback/delegate interfaces are not Python callbacks. Tree change and
124127
directory traversal use native iterators/adapters. Custom per-entry traversal
125128
delegates, object-token visitor callbacks and filter callbacks are not exposed.

‎docs/implementation-plan.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,11 @@ new public revision.
6868

6969
## Acceptance
7070

71+
Native `gix-testtools` fixtures are available through `gix.testtools`, with
72+
Python callbacks preserving `FixtureState` and return-value semantics.
73+
Read-only caches support inspection suites; writable temporary copies keep
74+
mutation tests isolated. See [the fixture guide](testtools.md).
75+
7176
Every completed capability has a Python integration check and accurate type/documentation coverage. Checks use disposable repositories and isolated Git configuration; both hash kinds and relevant feature selections are exercised. Shared-handle concurrency, GIL-disabled execution, partial iterator consumption, interruption, stale-reference rejection, and artifact installation are project requirements.
7277

7378
Gitoxide currently exposes commit merges even where older overview documentation says otherwise. Its push-related configuration does not itself provide native push execution. Verify capabilities against source rather than treating an old feature checklist as authoritative.

‎docs/testtools.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Cached fixtures for Python test suites
2+
3+
`gix.testtools` binds `gix-testtools`' native fixture cache. It is available in
4+
every build, including reduced hash configurations. Paths and return values
5+
follow the Rust API; fixture paths are `pathlib.Path` objects.
6+
7+
Run tests from the test project's root. Fixtures and scripts live under
8+
`tests/fixtures`, generated directories under
9+
`tests/fixtures/generated-do-not-edit`, and reusable TAR archives under
10+
`tests/fixtures/generated-archives`. Names passed to `rust_fixture_*` must
11+
be a single path component, unique within that project. The Rust function
12+
names are retained even when Python supplies the producer:
13+
14+
```python
15+
import gix
16+
from gix import testtools
17+
18+
def make_fixture(state):
19+
path = state.path()
20+
if state.is_uninitialized():
21+
repo = gix.init(path / "repo", options=gix.OpenOptions.isolated())
22+
blob_id = repo.write_blob(b"fixture content")
23+
(path / "blob-id").write_text(str(blob_id))
24+
return (path / "blob-id").read_text()
25+
26+
fixture, blob_id = testtools.rust_fixture_read_only("objects", 1, make_fixture)
27+
repo = gix.open_opts(fixture / "repo", gix.OpenOptions.isolated())
28+
assert repo.find_blob(blob_id).data == b"fixture content"
29+
```
30+
31+
The callback receives a `FixtureState`. `is_uninitialized()` is true when
32+
it must create or post-process contents; it is false when the fixture comes
33+
from the cache or an archive. The callback runs in either case to compute
34+
its return value. Increment `version` whenever the callback's generation
35+
behavior changes. The native lock coordinates concurrent creators, and a
36+
failed producer leaves a marker so the next call recreates the fixture.
37+
Python exceptions retain their original type and instance.
38+
39+
Read-only fixtures are a usage contract, not filesystem write protection.
40+
Never mutate the returned directory or run Git operations that could change
41+
its index, references, or configuration. Use isolated native open options
42+
for reading. Post-process only while `is_uninitialized()` is true.
43+
44+
For a script, use `scripted_fixture_read_only("make.sh")`, or provide a
45+
Python closure to `scripted_fixture_read_only_with_post("make.sh", 1, post)`.
46+
The corresponding `_with_args` functions forward a list of arguments;
47+
`scripted_fixture_read_only_with_args_with_post` accepts both. Scripts run
48+
with native Git environment isolation. Bash fixtures can use
49+
`gix_testtools_require_symlinks` and `fixture_has_symlinks()` for preflight.
50+
Scripts need Git and their own interpreter installed; Python-only producers
51+
can use native `gix` operations. Creating native archives still requires Git
52+
to record its version in the archive metadata; ignoring archive creation
53+
avoids that requirement.
54+
55+
Tests that mutate a fixture use a writable temporary directory:
56+
57+
```python
58+
temporary, blob_id = testtools.rust_fixture_writable(
59+
"objects", 1, testtools.Creation.CopyFromReadOnly, make_fixture
60+
)
61+
with temporary:
62+
work = temporary.path()
63+
# Mutate only this disposable copy.
64+
```
65+
66+
`TempDir.close()`, leaving its context, or dropping it removes the directory.
67+
The cached source remains available. `Creation.CopyFromReadOnly` may call
68+
the callback twice: once for the cache, then with a fresh state at the copy
69+
to compute a value for its final location. This native copy mode does not
70+
preserve symlinks. Use `Creation.Execute` for symlinks or absolute paths:
71+
it generates directly in the final temporary directory. The scripted
72+
writable helpers provide the same modes and post-processing overloads.
73+
74+
Archive generation and extraction retain native behavior. Ignore generated
75+
directories with `tests/fixtures/generated-do-not-edit/` and, when archives
76+
are unwanted, ignore `tests/fixtures/generated-archives/*.tar`. Set
77+
`GIX_TEST_IGNORE_ARCHIVES=1` to regenerate locally, or use
78+
`scripted_fixture_read_only_needs_archive()` for native archive preference.
79+
It prefers an existing archive despite that variable and falls back to the
80+
script if no matching archive exists. This build uses TAR, without XZ.
81+
`GIX_TEST_FIXTURE_HASH` selects an enabled fixture hash kind.
82+
83+
`fixture_path()` resolves a fixture input, `fixture_bytes()` reads its bytes,
84+
and `git(directory, arguments)` runs the native isolated Git helper for a
85+
reference result. The argument string follows its shell-like quote parsing.
86+
Git here is a test oracle, not a repository-operation fallback.
87+
88+
Native work runs detached from Python. The producer callback attaches only
89+
while it runs; no repository state mutex is held by the binding. Callbacks
90+
must not recursively request the same fixture, whose native file lock is
91+
held until generation finishes. Avoid changing the process working
92+
directory or environment while fixtures run concurrently. Python retains
93+
ownership of signal handlers; importing the module and generating fixtures
94+
does not install native termination handlers.
95+
96+
The binding covers the fixture APIs above, not every `gix-testtools` utility.
97+
Single-archive argument variants, Git-version predicates, process-environment
98+
guards, repository snapshots, Git daemons, and Cargo example builders are
99+
not currently exposed.

‎docs/validation.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,39 @@
11
# Local validation
22

3+
## Python fixture tools (2026-10-12)
4+
5+
The pinned `gix-testtools 0.22.0` is available as `gix.testtools` in default
6+
and reduced builds. Python producers and post-processors retain native
7+
`FixtureState`, cache versions, archives, and callback return values. Five
8+
integration checks run in disposable child-process workspaces and cover
9+
concurrent initialization, cross-process cache reuse, archive extraction,
10+
script arguments and Git environment isolation, all bound post-processing
11+
variants, writable copy/direct-generation cleanup, exception identity,
12+
failed-fixture retry, invalid inputs, and Python signal-handler preservation.
13+
14+
On Apple Silicon macOS with Rust/Cargo 1.99.0, packaged CPython 3.14.7 passes
15+
all 110 tests with two expected skips; free-threaded CPython 3.14.7 with
16+
`PYTHON_GIL=0` passes all 110 with one skip. Both hash-only configurations
17+
pass 110 discovered tests with 75 expected skips, including the fixture
18+
checks. Default and reduced clippy (`sha1,sha256,revision,index`) pass with
19+
warnings denied; seven Rust tests, nine helper checks, formatting, and
20+
whitespace checks pass. Local dependency metadata resolves `gix-testtools`
21+
from the selected checkout's `tests/tools` directory. Dependency metadata
22+
fits Rust 1.89 without an actual MSRV run. Project builds disable C/C++
23+
compilers; fixture archives use TAR without the C-backed XZ feature.
24+
25+
The ABI3 macOS wheel rebuilt from its sdist includes `gix.testtools` and
26+
its stubs, and passes all 110 tests on CPython 3.14.7 with two expected
27+
skips in an offline installation. Archive and wheel content checks pass.
28+
Development-profile candidates are in `dist/testtools-validation/`.
29+
30+
The fixture API is a supported subset, documented in [the guide](testtools.md).
31+
Read-only paths remain a caller contract rather than filesystem protection.
32+
Callbacks must not recursively acquire the same fixture or change process
33+
environment/working directory while fixture calls run concurrently.
34+
No remote operations, publication, Intel/cross-platform builds, or actual
35+
Rust 1.89 execution were performed.
36+
337
## Public `main` integration without vendoring (2026-10-12)
438

539
On Apple Silicon macOS with Rust/Cargo 1.99.0, packaged builds resolve public

0 commit comments

Comments
 (0)