nondet 0.0.1__tar.gz

nondet-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seth Wheeler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nondet-0.0.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: nondet
+Version: 0.0.1
+Summary: Run a function in fresh processes and see if it answers the same. A witness is a fact; agreement is not.
+License: MIT
+Keywords: determinism,nondeterminism,reproducibility,purity,side-effects,hash-randomisation,pythonhashseed,memoize,caching,flaky,testing,zero-dependency
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# `nondet`
+
+Run a function more than once, **in fresh processes**, and see if it answers the same.
+
+```sh
+nondet src/                     # every module-level function under a tree
+nondet src/util.py::normalise   # one function
+```
+
+```
+FINDINGS — 1, each with a witness:
+  nondeterministic  src/features.py::resolve_features
+         [["alpha","beta","gamma","delta","epsilon"]] -> V:set["epsilon","delta",…]  then  V:set["beta","gamma",…]
+         a witness is a fact: this function gave two answers to one input
+```
+
+## Why fresh processes, which is the whole design
+
+Calling a function twice in one interpreter is the check anybody writes first, and it is
+blind to the commonest source of nondeterminism in Python:
+
+```
+$ for i in 1 2 3; do python3 -c "print(list({'alpha','beta','gamma'}))"; done
+['gamma', 'alpha', 'beta']
+['beta', 'gamma', 'alpha']
+['alpha', 'gamma', 'beta']
+
+$ python3 -c "
+> for i in range(3): print(list({'alpha','beta','gamma'}))"
+['beta', 'alpha', 'gamma']
+['beta', 'alpha', 'gamma']       # <- stable, twenty times out of twenty
+['beta', 'alpha', 'gamma']
+```
+
+String hashing is randomised per interpreter, so set and dict iteration order is stable
+**within** a process and different in every new one. An in-process repeat check reports
+that function deterministic every time it is asked, and the build that depends on it
+breaks on a machine that started the process differently.
+
+That control is a test: `test_in_process_repetition_would_have_missed_it` asserts the
+in-process check finds *no* variation over 20 calls and that `nondet` finds it anyway.
+If in-process repetition ever catches it, fresh processes are expensive theatre and the
+test says so.
+
+## The verdicts are asymmetric
+
+| verdict | means | worth |
+|---|---|---|
+| `nondeterministic` | an input, and two different answers to it | **a witness, and a witness is a fact** |
+| `deterministic` | no run disagreed, across N runs over a finite ladder | the absence of a counterexample, which is not proof of its absence |
+| `look` | could not be probed — and why | never a finding, never fails the run |
+
+The `deterministic` line says so in the output rather than letting you read it as a
+guarantee.
+
+## What it is measured at
+
+**A labelled fixture set** (`fixtures/known.py`, 18 functions, labels written down
+separately from the names so the checker is not graded against its own convention):
+
+| | |
+|---|---|
+| nondeterministic caught | **9 of 9** |
+| deterministic falsely flagged | **0 of 9** |
+
+The pairs are the point. `dedup_unsorted` and `dedup_sorted` are one `sorted()` apart.
+`seeded` uses `random.Random(42)` — deterministic, and the specific false positive a
+static gate that greps for `random` produces. `duration_arithmetic` imports `time` and
+never reads the clock.
+
+**A real tree** — `trainingResearch/tools`, 283 functions, not written with this tool in
+mind:
+
+| | with the safety gate | `--unsafe` |
+|---|---|---|
+| probed | 127 (45%) | 169 (60%) |
+| nondeterministic | **2** | **4** |
+| not probed | 156 | 114 |
+
+Both findings are genuine: a function returning a `set`, and one whose value differs
+across runs. The gate costs recall and the table says so — one of the two findings it
+hides (`harness_backlog`, which returns a path under a fresh temp directory) is a true
+positive that the gate can no longer see.
+
+## It executes the code it is asked about
+
+This is the sharpest thing to know, and it was found the hard way. Pointed at a real
+tree, `nondet` reported a function raising `TypeError` on one run and `FileExistsError`
+on the next — a true finding, and proof that the probe had **created a file on
+somebody's disk**.
+
+So there are two gates, asking different questions:
+
+- **is it safe to run?** — static, conservative, and refusing costs a `look`
+- **is it deterministic?** — dynamic, and the point of the package
+
+The line is drawn at **writing and communicating**, not at impurity. `time`, `random`,
+`uuid`, `os.getpid` and set ordering are read-only and nondeterministic — they are
+exactly the target, and a gate that refused them would refuse the findings. What gets
+refused is anything that could change the world outside the process: `open()`,
+`subprocess`, `shutil`, sockets, `os.remove` and friends.
+
+`--unsafe` lifts it. A test asserts the gate does not eat the read-only findings, and
+another asserts a file-writing function is refused *and the file does not appear*.
+
+## What it is for
+
+- **What is safe to memoize or cache.** A function that answers differently per process
+  is not.
+- **Finding hidden global state**, module-level caches, and accidental clock or
+  environment dependence.
+- **Reproducible builds and artefacts.** A generator returning a set is how a build
+  output changes between machines with no source change.
+- **Pre-filtering** candidates for snapshot testing or property testing.
+
+## Prior art
+
+Swept on mechanism nouns across **both registries** — the first sweep queried npm hard
+and PyPI only by guessing names, which is how it nearly missed the entry below.
+
+On npm, `keywords:purity` returns 26 packages and **every one is static analysis**
+(`pure-react-check`, `@efct/efct`, `@tslite/analysis`, `@ogaga/spacta`);
+`keywords:nondeterminism` returns one replay recorder.
+
+On PyPI and in the literature, three neighbours are real and none of them is this:
+
+- **[`reprotest`](https://pypi.org/project/reprotest/)** asks the same question at
+  **build** granularity: run it twice under deliberately varied conditions and diff the
+  output. It is the direct ancestor of this package's `VARIATIONS`, which were added
+  after reading it. It cannot tell you *which function* moved.
+- **Groce & Holmes, [*Practical Automatic Lightweight Nondeterminism and Flaky Test
+  Detection and Debugging for Python*](https://agroce.github.io/qrs20-2.pdf)** (QRS 2020)
+  is the academic prior art, at **test** granularity.
+- **`pytest-flakefinder`**, **`pytest-randomly`** and **`flaky`** rerun or reorder
+  *tests*. `pytest-randomly` surfaces nondeterminism by controlling seeds; none of them
+  names a function or produces a witness input.
+
+The gap is the granularity: nothing found points at an arbitrary function, walks a
+ladder, and hands back the input that distinguished two runs.
+
+Static and dynamic are complements rather than rivals, and this ships both: the static
+gate decides what is *safe to execute*, the dynamic check decides what is *actually
+nondeterministic*. A static gate alone refuses `seeded` and `duration_arithmetic`; a
+dynamic check alone writes to your disk.
+
+## Limits
+
+- **The ladder is fixed and small.** Arity 1–3, no variadics, no keyword-only. On a real
+  tree that is most of the 156 `look`s, and the census names every one.
+- **Values with no canonical form are excluded, not reported.** `<Thing object at
+  0x10f3c2e50>` differs every run and means nothing; flagging it would flag every
+  codebase in the world. The count of excluded rungs is printed.
+- **Exception type, not message.** Messages carry paths, addresses and timings.
+- **`PYTHONHASHSEED` is cleared for the workers**, so a fixed seed in your environment
+  cannot blind the check — and the fact that it was set is reported either way.
+- **The environment is varied between runs** — timezone and locale, borrowed from
+  `reprotest`. Hash randomisation is free with every new process; these are not. So
+  `deterministic` here means *"the same answer under these varied conditions"*, which is
+  a stronger claim than three runs on one machine. `epoch_year` in the fixtures is the
+  control: `fromtimestamp(0).year` is 1970 in UTC and 1969 west of it, does not move
+  with the clock, and is caught **only** because the timezone varies.
+- Zero dependencies, Python 3.9+.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+25 tests. Two of them are regressions for bugs *in this tool* that first looked like
+findings about the code under test: loading a package module by file path broke relative
+imports and refused 56 of 68 functions, and sending the result vector over stdout meant
+any function that printed corrupted it. Both were caught by pointing the tool at a real
+codebase and disbelieving the refusal rate.
+
+One of those fixes is worth its own note: it took reach from 2/68 to 60/68 **while
+breaking correctness on all 17 fixtures**. A tool watched only by "how many did it
+probe" would have scored that as an improvement.

nondet-0.0.1/README.md

@@ -0,0 +1,178 @@
+# `nondet`
+
+Run a function more than once, **in fresh processes**, and see if it answers the same.
+
+```sh
+nondet src/                     # every module-level function under a tree
+nondet src/util.py::normalise   # one function
+```
+
+```
+FINDINGS — 1, each with a witness:
+  nondeterministic  src/features.py::resolve_features
+         [["alpha","beta","gamma","delta","epsilon"]] -> V:set["epsilon","delta",…]  then  V:set["beta","gamma",…]
+         a witness is a fact: this function gave two answers to one input
+```
+
+## Why fresh processes, which is the whole design
+
+Calling a function twice in one interpreter is the check anybody writes first, and it is
+blind to the commonest source of nondeterminism in Python:
+
+```
+$ for i in 1 2 3; do python3 -c "print(list({'alpha','beta','gamma'}))"; done
+['gamma', 'alpha', 'beta']
+['beta', 'gamma', 'alpha']
+['alpha', 'gamma', 'beta']
+
+$ python3 -c "
+> for i in range(3): print(list({'alpha','beta','gamma'}))"
+['beta', 'alpha', 'gamma']
+['beta', 'alpha', 'gamma']       # <- stable, twenty times out of twenty
+['beta', 'alpha', 'gamma']
+```
+
+String hashing is randomised per interpreter, so set and dict iteration order is stable
+**within** a process and different in every new one. An in-process repeat check reports
+that function deterministic every time it is asked, and the build that depends on it
+breaks on a machine that started the process differently.
+
+That control is a test: `test_in_process_repetition_would_have_missed_it` asserts the
+in-process check finds *no* variation over 20 calls and that `nondet` finds it anyway.
+If in-process repetition ever catches it, fresh processes are expensive theatre and the
+test says so.
+
+## The verdicts are asymmetric
+
+| verdict | means | worth |
+|---|---|---|
+| `nondeterministic` | an input, and two different answers to it | **a witness, and a witness is a fact** |
+| `deterministic` | no run disagreed, across N runs over a finite ladder | the absence of a counterexample, which is not proof of its absence |
+| `look` | could not be probed — and why | never a finding, never fails the run |
+
+The `deterministic` line says so in the output rather than letting you read it as a
+guarantee.
+
+## What it is measured at
+
+**A labelled fixture set** (`fixtures/known.py`, 18 functions, labels written down
+separately from the names so the checker is not graded against its own convention):
+
+| | |
+|---|---|
+| nondeterministic caught | **9 of 9** |
+| deterministic falsely flagged | **0 of 9** |
+
+The pairs are the point. `dedup_unsorted` and `dedup_sorted` are one `sorted()` apart.
+`seeded` uses `random.Random(42)` — deterministic, and the specific false positive a
+static gate that greps for `random` produces. `duration_arithmetic` imports `time` and
+never reads the clock.
+
+**A real tree** — `trainingResearch/tools`, 283 functions, not written with this tool in
+mind:
+
+| | with the safety gate | `--unsafe` |
+|---|---|---|
+| probed | 127 (45%) | 169 (60%) |
+| nondeterministic | **2** | **4** |
+| not probed | 156 | 114 |
+
+Both findings are genuine: a function returning a `set`, and one whose value differs
+across runs. The gate costs recall and the table says so — one of the two findings it
+hides (`harness_backlog`, which returns a path under a fresh temp directory) is a true
+positive that the gate can no longer see.
+
+## It executes the code it is asked about
+
+This is the sharpest thing to know, and it was found the hard way. Pointed at a real
+tree, `nondet` reported a function raising `TypeError` on one run and `FileExistsError`
+on the next — a true finding, and proof that the probe had **created a file on
+somebody's disk**.
+
+So there are two gates, asking different questions:
+
+- **is it safe to run?** — static, conservative, and refusing costs a `look`
+- **is it deterministic?** — dynamic, and the point of the package
+
+The line is drawn at **writing and communicating**, not at impurity. `time`, `random`,
+`uuid`, `os.getpid` and set ordering are read-only and nondeterministic — they are
+exactly the target, and a gate that refused them would refuse the findings. What gets
+refused is anything that could change the world outside the process: `open()`,
+`subprocess`, `shutil`, sockets, `os.remove` and friends.
+
+`--unsafe` lifts it. A test asserts the gate does not eat the read-only findings, and
+another asserts a file-writing function is refused *and the file does not appear*.
+
+## What it is for
+
+- **What is safe to memoize or cache.** A function that answers differently per process
+  is not.
+- **Finding hidden global state**, module-level caches, and accidental clock or
+  environment dependence.
+- **Reproducible builds and artefacts.** A generator returning a set is how a build
+  output changes between machines with no source change.
+- **Pre-filtering** candidates for snapshot testing or property testing.
+
+## Prior art
+
+Swept on mechanism nouns across **both registries** — the first sweep queried npm hard
+and PyPI only by guessing names, which is how it nearly missed the entry below.
+
+On npm, `keywords:purity` returns 26 packages and **every one is static analysis**
+(`pure-react-check`, `@efct/efct`, `@tslite/analysis`, `@ogaga/spacta`);
+`keywords:nondeterminism` returns one replay recorder.
+
+On PyPI and in the literature, three neighbours are real and none of them is this:
+
+- **[`reprotest`](https://pypi.org/project/reprotest/)** asks the same question at
+  **build** granularity: run it twice under deliberately varied conditions and diff the
+  output. It is the direct ancestor of this package's `VARIATIONS`, which were added
+  after reading it. It cannot tell you *which function* moved.
+- **Groce & Holmes, [*Practical Automatic Lightweight Nondeterminism and Flaky Test
+  Detection and Debugging for Python*](https://agroce.github.io/qrs20-2.pdf)** (QRS 2020)
+  is the academic prior art, at **test** granularity.
+- **`pytest-flakefinder`**, **`pytest-randomly`** and **`flaky`** rerun or reorder
+  *tests*. `pytest-randomly` surfaces nondeterminism by controlling seeds; none of them
+  names a function or produces a witness input.
+
+The gap is the granularity: nothing found points at an arbitrary function, walks a
+ladder, and hands back the input that distinguished two runs.
+
+Static and dynamic are complements rather than rivals, and this ships both: the static
+gate decides what is *safe to execute*, the dynamic check decides what is *actually
+nondeterministic*. A static gate alone refuses `seeded` and `duration_arithmetic`; a
+dynamic check alone writes to your disk.
+
+## Limits
+
+- **The ladder is fixed and small.** Arity 1–3, no variadics, no keyword-only. On a real
+  tree that is most of the 156 `look`s, and the census names every one.
+- **Values with no canonical form are excluded, not reported.** `<Thing object at
+  0x10f3c2e50>` differs every run and means nothing; flagging it would flag every
+  codebase in the world. The count of excluded rungs is printed.
+- **Exception type, not message.** Messages carry paths, addresses and timings.
+- **`PYTHONHASHSEED` is cleared for the workers**, so a fixed seed in your environment
+  cannot blind the check — and the fact that it was set is reported either way.
+- **The environment is varied between runs** — timezone and locale, borrowed from
+  `reprotest`. Hash randomisation is free with every new process; these are not. So
+  `deterministic` here means *"the same answer under these varied conditions"*, which is
+  a stronger claim than three runs on one machine. `epoch_year` in the fixtures is the
+  control: `fromtimestamp(0).year` is 1970 in UTC and 1969 west of it, does not move
+  with the clock, and is caught **only** because the timezone varies.
+- Zero dependencies, Python 3.9+.
+
+## Tests
+
+```sh
+python3 -m unittest discover -s tests
+```
+
+25 tests. Two of them are regressions for bugs *in this tool* that first looked like
+findings about the code under test: loading a package module by file path broke relative
+imports and refused 56 of 68 functions, and sending the result vector over stdout meant
+any function that printed corrupted it. Both were caught by pointing the tool at a real
+codebase and disbelieving the refusal rate.
+
+One of those fixes is worth its own note: it took reach from 2/68 to 60/68 **while
+breaking correctness on all 17 fixtures**. A tool watched only by "how many did it
+probe" would have scored that as an improvement.

nondet-0.0.1/nondet/__init__.py

@@ -0,0 +1,24 @@
+"""nondet — run it twice in fresh processes and see if it answers the same.
+
+    from nondet import check, scan
+
+`nondeterministic` carries a witness and is a fact. `deterministic` is the absence of
+one across a finite number of runs over a finite ladder, and is worth exactly what that
+is worth. The two are never printed as though they were the same kind of claim.
+"""
+
+from .core import (
+    Census,
+    Verdict,
+    check,
+    functions_in,
+    ladder,
+    scan,
+    LADDER_VALUES,
+    MAX_ARITY,
+    RUNS,
+)
+
+__all__ = ["check", "scan", "Verdict", "Census", "functions_in", "ladder",
+           "LADDER_VALUES", "MAX_ARITY", "RUNS"]
+__version__ = "0.0.1"

nondet-0.0.1/nondet/cli.py

@@ -0,0 +1,112 @@
+"""`nondet` — run it twice in fresh processes and see if it answers the same.
+
+    nondet src/                       # every module-level function under a tree
+    nondet src/util.py::normalise     # one function
+    nondet src/ --runs 5 --json
+
+Exit codes: 0 nothing found · 1 at least one function is nondeterministic · 2 the tool
+could not run.
+
+A `look` NEVER fails the run. A check that cries wolf is one nobody runs, and a function
+this could not probe is not a finding about that function — it is a gap in the probe,
+and it is counted and named rather than hidden.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .core import RUNS, check, functions_in, scan
+
+
+def _one(ref: str, runs: int, unsafe: bool = False):
+    path, _, name = ref.partition("::")
+    for candidate, arity in functions_in(path):
+        if candidate == name:
+            return check(path, name, arity, runs=runs, unsafe=unsafe)
+    return None
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="nondet",
+        description="Run a function in fresh processes and see if it answers the same.",
+    )
+    parser.add_argument("paths", nargs="+", help="files, directories, or FILE::NAME")
+    parser.add_argument("--runs", type=int, default=RUNS,
+                        help=f"fresh interpreters per function (default {RUNS})")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    parser.add_argument("--unsafe", action="store_true",
+                        help="run functions the static gate refuses as side-effecting. "
+                             "This tool EXECUTES what it probes; the gate is why it does "
+                             "not leave files behind on a working tree.")
+    parser.add_argument("-q", "--quiet", action="store_true",
+                        help="only print findings and the census")
+    args = parser.parse_args(argv)
+
+    verdicts = []
+    for ref in args.paths:
+        if "::" in ref:
+            verdict = _one(ref, args.runs, args.unsafe)
+            if verdict is None:
+                sys.stderr.write(f"nondet: {ref} names no module-level function\n")
+                return 2
+            verdicts.append(verdict)
+        else:
+            if not os.path.exists(ref):
+                sys.stderr.write(f"nondet: {ref} does not exist\n")
+                return 2
+            verdicts.extend(scan([ref], runs=args.runs, unsafe=args.unsafe).verdicts)
+
+    findings = [v for v in verdicts if v.state == "nondeterministic"]
+    looks = [v for v in verdicts if v.state == "look"]
+    clean = [v for v in verdicts if v.state == "deterministic"]
+
+    if args.as_json:
+        json.dump(
+            {"functions": len(verdicts),
+             "nondeterministic": len(findings),
+             "deterministic": len(clean),
+             "look": len(looks),
+             "verdicts": [
+                 {"ref": v.ref, "state": v.state, "detail": v.detail,
+                  "witness": v.witness, "compared": v.compared, "total": v.total,
+                  "unstateable": v.unstateable, "hash_seed_fixed": v.hash_seed_fixed}
+                 for v in verdicts
+             ]},
+            sys.stdout, indent=2, sort_keys=True,
+        )
+        sys.stdout.write("\n")
+        return 1 if findings else 0
+
+    if findings:
+        print(f"\nFINDINGS — {len(findings)}, each with a witness:")
+        for v in findings:
+            print("  " + str(v))
+    if looks and not args.quiet:
+        print(f"\nLOOK — {len(looks)} the probe could not settle. These never fail the run.")
+        for v in looks:
+            print("  " + str(v))
+
+    # THE DENOMINATOR IS PRINTED, ALWAYS. A run that probed nothing and a run that
+    # probed everything and found nothing print the same word otherwise, and they are
+    # not the same result.
+    print(f"\n{len(verdicts)} functions: {len(clean)} deterministic, "
+          f"{len(findings)} nondeterministic, {len(looks)} not probed")
+    if not verdicts:
+        print("  nothing was probed, so this is not a clean result — it is no result")
+    unstateable = sum(v.unstateable for v in verdicts)
+    if unstateable:
+        print(f"  {unstateable} rung(s) held values with no canonical form and were "
+              f"excluded from every comparison")
+    if any(v.hash_seed_fixed for v in verdicts):
+        print("  PYTHONHASHSEED was set in this environment; it was cleared for the "
+              "workers so hash-order\n  nondeterminism could still be seen")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())