nextfake 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. nextfake-0.1.0/.github/scripts/free_threaded_smoke.py +40 -0
  2. nextfake-0.1.0/.github/workflows/ci.yml +84 -0
  3. nextfake-0.1.0/.github/workflows/wheels.yml +141 -0
  4. nextfake-0.1.0/.gitignore +15 -0
  5. nextfake-0.1.0/CONTRIBUTING.md +90 -0
  6. nextfake-0.1.0/Cargo.lock +1072 -0
  7. nextfake-0.1.0/Cargo.toml +45 -0
  8. nextfake-0.1.0/LICENSE-APACHE +201 -0
  9. nextfake-0.1.0/LICENSE-MIT +21 -0
  10. nextfake-0.1.0/PKG-INFO +477 -0
  11. nextfake-0.1.0/README.md +435 -0
  12. nextfake-0.1.0/SECURITY.md +55 -0
  13. nextfake-0.1.0/benches/RESULTS.md +74 -0
  14. nextfake-0.1.0/benches/results.json +318 -0
  15. nextfake-0.1.0/benches/run_benchmarks.py +679 -0
  16. nextfake-0.1.0/pyproject.toml +91 -0
  17. nextfake-0.1.0/python/nextfake/__init__.py +174 -0
  18. nextfake-0.1.0/python/nextfake/_nextfake.pyi +83 -0
  19. nextfake-0.1.0/python/nextfake/exceptions.py +45 -0
  20. nextfake-0.1.0/python/nextfake/faker.py +1154 -0
  21. nextfake-0.1.0/python/nextfake/py.typed +0 -0
  22. nextfake-0.1.0/python/nextfake/schema.py +964 -0
  23. nextfake-0.1.0/python/nextfake/types.py +266 -0
  24. nextfake-0.1.0/src/errors.rs +117 -0
  25. nextfake-0.1.0/src/lib.rs +793 -0
  26. nextfake-0.1.0/src/locales/de_de.rs +145 -0
  27. nextfake-0.1.0/src/locales/en_gb.rs +138 -0
  28. nextfake-0.1.0/src/locales/en_us.rs +158 -0
  29. nextfake-0.1.0/src/locales/fr_fr.rs +152 -0
  30. nextfake-0.1.0/src/locales/ja_jp.rs +129 -0
  31. nextfake-0.1.0/src/locales/mod.rs +351 -0
  32. nextfake-0.1.0/src/providers.rs +1958 -0
  33. nextfake-0.1.0/src/rng.rs +254 -0
  34. nextfake-0.1.0/src/schema.rs +376 -0
  35. nextfake-0.1.0/src/writers.rs +524 -0
  36. nextfake-0.1.0/tests/__init__.py +0 -0
  37. nextfake-0.1.0/tests/conftest.py +10 -0
  38. nextfake-0.1.0/tests/helpers.py +16 -0
  39. nextfake-0.1.0/tests/test_determinism.py +86 -0
  40. nextfake-0.1.0/tests/test_exporters.py +266 -0
  41. nextfake-0.1.0/tests/test_locales.py +82 -0
  42. nextfake-0.1.0/tests/test_providers.py +152 -0
  43. nextfake-0.1.0/tests/test_schema_models.py +325 -0
  44. nextfake-0.1.0/tests/test_typing.py +83 -0
@@ -0,0 +1,40 @@
1
+ """Smoke test for free-threaded CPython (3.14t): the extension must not re-enable the GIL and
2
+ must generate correct, deterministic data when called from many Python threads at once."""
3
+
4
+ import sys
5
+ import threading
6
+
7
+ import nextfake
8
+
9
+ assert not sys._is_gil_enabled(), "importing nextfake re-enabled the GIL"
10
+
11
+ SCHEMA = {"id": "int", "name": "name", "email": "email", "created_at": "datetime"}
12
+ expected = nextfake.Faker(seed=7).to_dicts(SCHEMA, 20_000)
13
+ shared = nextfake.Faker(seed=1)
14
+ results: list[object] = []
15
+ errors: list[BaseException] = []
16
+
17
+
18
+ def work() -> None:
19
+ try:
20
+ # independent generators: must reproduce the seeded reference exactly
21
+ assert nextfake.Faker(seed=7).to_dicts(SCHEMA, 20_000) == expected
22
+ # one shared generator used concurrently: must stay consistent and not crash
23
+ rows = shared.to_dicts(SCHEMA, 5_000)
24
+ assert len(rows) == 5_000
25
+ assert all("@" in r["email"] for r in rows)
26
+ results.append(len(shared.names(1_000)))
27
+ except BaseException as exc: # re-raised in the main thread
28
+ errors.append(exc)
29
+
30
+
31
+ threads = [threading.Thread(target=work) for _ in range(16)]
32
+ for t in threads:
33
+ t.start()
34
+ for t in threads:
35
+ t.join()
36
+ if errors:
37
+ raise errors[0]
38
+ assert results == [1_000] * 16
39
+ assert not sys._is_gil_enabled()
40
+ print(f"free-threaded OK: GIL disabled, 16 concurrent threads, sample {expected[0]['name']!r}")
@@ -0,0 +1,84 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ workflow_dispatch:
8
+
9
+ concurrency:
10
+ group: ci-${{ github.ref }}
11
+ cancel-in-progress: true
12
+
13
+ env:
14
+ CARGO_TERM_COLOR: always
15
+ RUST_BACKTRACE: 1
16
+
17
+ jobs:
18
+ rust:
19
+ name: Rust (fmt, clippy, test)
20
+ runs-on: ubuntu-latest
21
+ steps:
22
+ - uses: actions/checkout@v5
23
+ - uses: dtolnay/rust-toolchain@stable
24
+ with:
25
+ components: rustfmt, clippy
26
+ - uses: Swatinem/rust-cache@v2
27
+ - name: cargo fmt
28
+ run: cargo fmt --all --check
29
+ - name: cargo clippy (core)
30
+ run: cargo clippy --all-targets -- -D warnings
31
+ - name: cargo clippy (python bindings)
32
+ run: cargo clippy --all-targets --features python -- -D warnings
33
+ - name: cargo test
34
+ run: cargo test
35
+
36
+ python:
37
+ name: Python ${{ matrix.python-version }} / ${{ matrix.os }}
38
+ runs-on: ${{ matrix.os }}
39
+ strategy:
40
+ fail-fast: false
41
+ matrix:
42
+ os: [ubuntu-latest, macos-latest, windows-latest]
43
+ python-version: ["3.10", "3.13"]
44
+ steps:
45
+ - uses: actions/checkout@v5
46
+ - uses: dtolnay/rust-toolchain@stable
47
+ - uses: Swatinem/rust-cache@v2
48
+ - uses: astral-sh/setup-uv@v7
49
+ with:
50
+ python-version: ${{ matrix.python-version }}
51
+ - name: Create venv & install dev dependencies
52
+ run: |
53
+ uv venv
54
+ uv pip install --group dev
55
+ - name: Build extension (release)
56
+ run: uv run --no-sync maturin develop --release
57
+ - name: ruff
58
+ run: uv run --no-sync ruff check python tests benches
59
+ - name: mypy --strict
60
+ run: uv run --no-sync mypy --strict python/nextfake tests/test_typing.py
61
+ - name: pytest
62
+ run: uv run --no-sync pytest -v
63
+
64
+ free-threaded:
65
+ name: Free-threaded CPython 3.14t smoke test
66
+ runs-on: ubuntu-latest
67
+ steps:
68
+ - uses: actions/checkout@v5
69
+ - uses: dtolnay/rust-toolchain@stable
70
+ - uses: Swatinem/rust-cache@v2
71
+ - uses: astral-sh/setup-uv@v7
72
+ with:
73
+ python-version: "3.14t"
74
+ # Build a wheel and install it on its own: `maturin develop` would also install the
75
+ # project's `dev` dependency group, and some of it (polars-runtime) has no 3.14t wheel
76
+ # and is compiled from source (~20 min).
77
+ - name: Build and install the wheel
78
+ run: |
79
+ uv venv
80
+ uv pip install maturin
81
+ uv run --no-sync maturin build --release --out dist --interpreter python
82
+ uv pip install --no-deps dist/*.whl
83
+ - name: Smoke test (GIL stays disabled, concurrent generation)
84
+ run: uv run --no-sync python .github/scripts/free_threaded_smoke.py
@@ -0,0 +1,141 @@
1
+ name: Wheels
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ workflow_dispatch:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ linux:
13
+ name: manylinux ${{ matrix.target }}
14
+ runs-on: ${{ matrix.runner }}
15
+ strategy:
16
+ matrix:
17
+ include:
18
+ - { runner: ubuntu-latest, target: x86_64 }
19
+ - { runner: ubuntu-24.04-arm, target: aarch64 }
20
+ steps:
21
+ - uses: actions/checkout@v5
22
+ - uses: PyO3/maturin-action@v1
23
+ with:
24
+ target: ${{ matrix.target }}
25
+ args: --release --out dist
26
+ manylinux: "2_28"
27
+ sccache: "true"
28
+ - uses: actions/upload-artifact@v6
29
+ with:
30
+ name: wheels-manylinux-${{ matrix.target }}
31
+ path: dist
32
+
33
+ musllinux:
34
+ name: musllinux ${{ matrix.target }}
35
+ runs-on: ${{ matrix.runner }}
36
+ strategy:
37
+ matrix:
38
+ include:
39
+ - { runner: ubuntu-latest, target: x86_64 }
40
+ - { runner: ubuntu-24.04-arm, target: aarch64 }
41
+ steps:
42
+ - uses: actions/checkout@v5
43
+ - uses: PyO3/maturin-action@v1
44
+ with:
45
+ target: ${{ matrix.target }}
46
+ args: --release --out dist
47
+ manylinux: musllinux_1_2
48
+ sccache: "true"
49
+ - uses: actions/upload-artifact@v6
50
+ with:
51
+ name: wheels-musllinux-${{ matrix.target }}
52
+ path: dist
53
+
54
+ macos:
55
+ name: macOS ${{ matrix.target }}
56
+ runs-on: ${{ matrix.runner }}
57
+ strategy:
58
+ matrix:
59
+ include:
60
+ # Apple Silicon runners for both targets; x86_64 is cross-compiled. `macos-latest`
61
+ # avoids breakage when pinned images retire (macos-13 and macos-14 already have).
62
+ # Wheel compatibility comes from maturin's deployment target, not the runner OS.
63
+ - { runner: macos-latest, target: x86_64 }
64
+ - { runner: macos-latest, target: aarch64 }
65
+ steps:
66
+ - uses: actions/checkout@v5
67
+ - uses: PyO3/maturin-action@v1
68
+ with:
69
+ target: ${{ matrix.target }}
70
+ args: --release --out dist
71
+ sccache: "true"
72
+ - uses: actions/upload-artifact@v6
73
+ with:
74
+ name: wheels-macos-${{ matrix.target }}
75
+ path: dist
76
+
77
+ windows:
78
+ name: Windows x64
79
+ runs-on: windows-latest
80
+ steps:
81
+ - uses: actions/checkout@v5
82
+ - uses: actions/setup-python@v6
83
+ with:
84
+ python-version: "3.13"
85
+ architecture: x64
86
+ - uses: PyO3/maturin-action@v1
87
+ with:
88
+ target: x64
89
+ args: --release --out dist
90
+ sccache: "true"
91
+ - uses: actions/upload-artifact@v6
92
+ with:
93
+ name: wheels-windows-x64
94
+ path: dist
95
+
96
+ sdist:
97
+ name: sdist
98
+ runs-on: ubuntu-latest
99
+ steps:
100
+ - uses: actions/checkout@v5
101
+ - uses: PyO3/maturin-action@v1
102
+ with:
103
+ command: sdist
104
+ args: --out dist
105
+ - uses: actions/upload-artifact@v6
106
+ with:
107
+ name: wheels-sdist
108
+ path: dist
109
+
110
+ release:
111
+ name: Publish to PyPI
112
+ runs-on: ubuntu-latest
113
+ if: startsWith(github.ref, 'refs/tags/v')
114
+ needs: [linux, musllinux, macos, windows, sdist]
115
+ environment:
116
+ name: pypi
117
+ url: https://pypi.org/p/nextfake
118
+ permissions:
119
+ id-token: write # Trusted Publishing + Sigstore signing of the PEP 740 attestations
120
+ attestations: write # GitHub artifact attestations (`gh attestation verify`)
121
+ contents: read
122
+ steps:
123
+ - uses: actions/download-artifact@v7
124
+ with:
125
+ pattern: wheels-*
126
+ merge-multiple: true
127
+ path: dist
128
+ - name: Check tag matches package version
129
+ run: |
130
+ version="${GITHUB_REF_NAME#v}"
131
+ ls -l dist
132
+ ls dist/nextfake-"$version"-*.whl dist/nextfake-"$version".tar.gz > /dev/null
133
+ - name: GitHub build provenance
134
+ uses: actions/attest-build-provenance@v4
135
+ with:
136
+ subject-path: "dist/*"
137
+ - name: Publish to PyPI with PEP 740 attestations
138
+ uses: pypa/gh-action-pypi-publish@release/v1
139
+ with:
140
+ attestations: true
141
+ skip-existing: true
@@ -0,0 +1,15 @@
1
+ /target
2
+ .venv/
3
+ __pycache__/
4
+ *.py[cod]
5
+ *.so
6
+ *.pyd
7
+ *.dylib
8
+ .mypy_cache/
9
+ .ruff_cache/
10
+ .pytest_cache/
11
+ dist/
12
+ *.egg-info/
13
+ benches/_out/
14
+ benches/raw_results.json.tmp
15
+ .envrc.sh
@@ -0,0 +1,90 @@
1
+ # Contributing to nextfake
2
+
3
+ Thanks for helping! nextfake is a Rust core (`src/`, PyO3 + rayon + Arrow) with a thin, typed
4
+ Python layer (`python/nextfake/`).
5
+
6
+ ## Development setup
7
+
8
+ ```bash
9
+ # Rust stable (1.85+) and Python 3.10+ required
10
+ uv venv && source .venv/bin/activate # or: python -m venv .venv
11
+ uv pip install --group dev --group bench # or: pip install maturin pytest ruff mypy ...
12
+ maturin develop --release # build & install the extension in-place
13
+ ```
14
+
15
+ Use `maturin develop` (debug) for fast iteration and `--release` for benchmarks.
16
+
17
+ ## Quality gates (all must pass — CI enforces them)
18
+
19
+ ```bash
20
+ cargo fmt --check
21
+ cargo clippy --all-targets -- -D warnings
22
+ cargo clippy --all-targets --features python -- -D warnings
23
+ cargo test
24
+ ruff check python tests benches
25
+ mypy --strict python/nextfake tests/test_typing.py
26
+ pytest -v
27
+ ```
28
+
29
+ `cargo test` exercises the pure-Rust core; the PyO3 bindings live behind the `python` cargo
30
+ feature (enabled automatically by maturin), so Rust tests never need to link libpython.
31
+
32
+ ## Project layout
33
+
34
+ | Path | What lives there |
35
+ |---|---|
36
+ | `src/rng.rs` | Deterministic `ChaCha8Rng` keyed by (seed, chunk), per-column streams |
37
+ | `src/providers.rs` | All value providers, Luhn, UUIDv7, ISO formatting |
38
+ | `src/locales/` | Compiled locale tables (`en_US`, `en_GB`, `de_DE`, `fr_FR`, `ja_JP`) |
39
+ | `src/schema.rs` | Column plans, parallel generation, Arrow conversion, thread pools |
40
+ | `src/writers.rs` | Arrow IPC, Parquet (parallel column encoding), CSV, JSONL |
41
+ | `src/lib.rs` | PyO3 module (`Engine`, `CompiledPlan`, `ArrowStream`) |
42
+ | `python/nextfake/` | `Faker` API, schema introspection & heuristics, specs, exceptions |
43
+ | `benches/run_benchmarks.py` | Head-to-head benchmarks → `benches/RESULTS.md` |
44
+
45
+ ## Ground rules
46
+
47
+ * **Determinism is a contract.** For a given seed, output must be identical for any thread
48
+ count, and existing columns must not change when unrelated columns are added. Changes to
49
+ `CHUNK_ROWS`, RNG keying or a provider's sampling logic change generated data — call this out
50
+ in the PR and the changelog.
51
+ * **No per-row Python objects on bulk paths.** Arrow / Parquet / CSV / JSONL paths must stay in
52
+ Rust with the GIL released (`py.detach`).
53
+ * **Keep the Python layer typed.** Public APIs need annotations that pass `mypy --strict`, and
54
+ stubs in `python/nextfake/_nextfake.pyi` must match the Rust bindings.
55
+ * Add tests for new providers in both Rust (`#[cfg(test)]`) and Python (`tests/`).
56
+
57
+ ## Adding a locale
58
+
59
+ 1. Create `src/locales/xx_yy.rs` with a `pub static XX_YY: Locale` (copy an existing locale).
60
+ 2. Register it in `LOCALES` in `src/locales/mod.rs` (and an alias in `get()` if useful).
61
+ 3. Provide romanised name tables (`first_names_romanized`) for non-Latin scripts so e-mails and
62
+ usernames stay ASCII.
63
+ 4. Extend `tests/test_locales.py` with format checks for postcodes and phone numbers.
64
+
65
+ ## Adding a provider
66
+
67
+ 1. Add a variant to `Provider` in `src/providers.rs`, parse it in `Provider::parse`, give it a
68
+ `Kind`, and implement generation.
69
+ 2. Add the name to `PROVIDER_NAMES`, optional aliases to `canonical()`, and field-name
70
+ heuristics in `python/nextfake/schema.py` if appropriate.
71
+ 3. Add typed `Faker` methods (single + batch) in `python/nextfake/faker.py`.
72
+
73
+ ## Releasing
74
+
75
+ Releases are published by `.github/workflows/wheels.yml` when a `v*` tag is pushed: it builds
76
+ manylinux/musllinux (x86_64, aarch64), macOS (x86_64, arm64), Windows x64 wheels and the sdist,
77
+ then uploads them to PyPI via Trusted Publishing with PEP 740 attestations and GitHub build
78
+ provenance (see [SECURITY.md](SECURITY.md#verifying-releases)).
79
+
80
+ 1. Bump `version` in `Cargo.toml` — the single source of truth (the Python package version is
81
+ read from it by maturin). Run `cargo check` so `Cargo.lock` updates, and run the quality gates.
82
+ 2. Commit, then tag the commit: `git tag -a vX.Y.Z -m "nextfake X.Y.Z"` and push the tag.
83
+ 3. Approve the `pypi` environment deployment in the Actions run if reviewers are required.
84
+
85
+ The publish job fails fast if the tag does not match the built version. Re-running a partially
86
+ failed publish is safe (`skip-existing`).
87
+
88
+ ## Commit messages
89
+
90
+ Reference the tracking key (e.g. `NXFK-402: ...`) and describe user-visible behaviour changes.