nab-python 0.0.2__tar.gz → 0.0.4__tar.gz

nab_python-0.0.4/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.hypothesis/
+.coverage*
+.ruff_cache/
+.hatch/
+docs/_build/
+
+*token*.txt
+*.pypirc
+.pypirc
+
+# Profiling artefacts.  By convention these live in `profiling/` at
+# the workspace root and never inside `docs/`, so the Sphinx build
+# never has to scan them.
+profiling/

nab_python-0.0.4/LICENSE

@@ -0,0 +1 @@
+../LICENSE

{nab_python-0.0.2 → nab_python-0.0.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: nab-python
-Version: 0.0.2
+Version: 0.0.4
 Summary: Index-backed provider, lockfile emitter, and downloader for nab
 Project-URL: Homepage, https://github.com/notatallshaw/nab
 Project-URL: Documentation, https://nab.readthedocs.io/
 Project-URL: Issues, https://github.com/notatallshaw/nab/issues
 Project-URL: Source, https://github.com/notatallshaw/nab
-Project-URL: Changelog, https://github.com/notatallshaw/nab/blob/main/CHANGELOG.md
+Project-URL: Changelog, https://github.com/notatallshaw/nab/releases
 Author-email: Damian Shaw <damian.peter.shaw@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
@@ -20,8 +20,8 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: build>=1.2
 Requires-Dist: installer>=0.7
-Requires-Dist: nab-index==0.0.2
-Requires-Dist: nab-resolver==0.0.2
+Requires-Dist: nab-index==0.0.4
+Requires-Dist: nab-resolver==0.0.4
 Requires-Dist: pyproject-hooks>=1.2
 Requires-Dist: tomli-w>=1.2
 Requires-Dist: tomli>=2.0

nab_python-0.0.4/benchmarks/README.md

@@ -0,0 +1,53 @@
+# Benchmarks
+
+nab ships two benchmark suites that exercise the single-environment
+and the universal resolver against real-world scenarios.
+
+## Single-environment scenarios
+
+`nab-python/benchmarks/scenarios.py` runs scenarios drawn from
+real-world resolver issues across pip, uv, poetry, pex, and
+pip-tools.  Scenario TOML files live under
+`nab-python/benchmarks/scenarios/`.
+
+```bash
+python nab-python/benchmarks/scenarios.py
+```
+
+The runner records wall-clock, decision-count, and round-count
+metrics, and writes a JSON summary under
+`nab-python/benchmarks/results/<commit>/`.
+
+## Universal-resolution scenarios
+
+`nab-python/benchmarks/universal_scenarios.py` runs
+universal-resolution scenarios sourced from public uv/poetry/pex
+slowness reports.  The cases stress cross-tuple alignment, marker
+divergence, and pre-release handling.
+
+```bash
+python nab-python/benchmarks/universal_scenarios.py
+python nab-python/benchmarks/universal_summary.py
+```
+
+`universal_summary.py` walks the latest results directory and
+prints a markdown table.
+
+## Scenario shape
+
+Each scenario is a top-level TOML table keyed by name, with at least
+`requirements` and a fixed `datetime` (used as the
+`uploaded-prior-to` cutoff).  Optional knobs include constraints,
+marker overlay, dist policy, and build policy.
+
+## What the suites cover
+
+* Tight version-cluster cases (e.g. boto3, awscli).
+* Conflict graphs that have hit pip's default resolver budget
+  (numpy/scipy/scikit-learn matrices).
+* Universal-mode fork-explosion cases (xinference, vllm,
+  ultralytics, copick).
+
+The suites are diagnostic harnesses that flag regressions on pull
+requests.  Walltime is noisy; decision count and round count are
+the load-bearing numbers.

nab_python-0.0.4/benchmarks/_profile_runner.py

@@ -0,0 +1,139 @@
+r"""Single-scenario profiling runner.
+
+Usage:
+    # sampling profiler (requires .venv-3.15)
+    .venv-3.15/bin/python -m profiling.sampling run -r 5khz --flamegraph \
+        -o profile.html nab-python/benchmarks/_profile_runner.py <scenario>
+
+    # cProfile (any venv)
+    python nab-python/benchmarks/_profile_runner.py <scenario> --cprofile
+
+<scenario> is a bare name (first TOML match wins) or ``toml_stem:name``,
+e.g. ``pip-lowest:cburroughs-v3``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import cProfile
+import pstats
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib  # type: ignore[no-redef]
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+import scenarios as sc
+
+
+def find_scenario(spec: str) -> tuple[str, dict]:
+    if ":" in spec:
+        toml_stem, name = spec.split(":", 1)
+        toml_path = sc.SCENARIOS_DIR / f"{toml_stem}.toml"
+        try:
+            with toml_path.open("rb") as f:
+                data = tomllib.load(f)
+        except FileNotFoundError:
+            sys.exit(f"no TOML file for stem {toml_stem!r}")
+        if name not in data:
+            sys.exit(f"scenario {name!r} not found in {toml_stem}.toml")
+        return name, data[name]
+    for path in sorted(sc.SCENARIOS_DIR.glob("*.toml")):
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+        if spec in data:
+            return spec, data[spec]
+    sys.exit(f"scenario {spec!r} not found")
+
+
+def build_inputs(name: str, scenario: dict) -> dict:
+    python_version = scenario["python_version"]
+    requirement_strings = list(scenario["requirements"])
+    constraint_strings = scenario.get("constraints", [])
+    marker_environment = sc.parse_marker_environment(name, scenario)
+    build_policy_overrides = sc.parse_build_packages(name, scenario)
+
+    # BUILD_REMOTE + marker_environment overlay is unsupported; drop overrides.
+    if marker_environment and build_policy_overrides:
+        build_policy_overrides = {}
+
+    resolution_strategy = sc.ResolutionStrategy(scenario.get("resolution", "highest"))
+    vcs_config = sc.VcsConfig(
+        policy=sc.VcsPolicy(scenario.get("vcs_policy", "block")),
+        allowed_schemes=frozenset(scenario.get("vcs_allowed_schemes", [])),
+        allowed_repos=tuple(scenario.get("vcs_allowed_repos", [])),
+        require_pin=scenario.get("vcs_require_pin", True),
+    )
+
+    if scenario.get("project_name"):
+        requirement_strings += sc.expand_project_extras(
+            scenario["project_name"],
+            scenario.get("project_extras", []),
+            scenario.get("optional_dependencies", {}),
+        )
+
+    marker_env = sc.scenario_marker_env(python_version, marker_environment)
+    requirements = sc.parse_requirements(
+        requirement_strings, vcs_config=vcs_config, marker_environment=marker_env
+    )
+    constraints = (
+        sc.parse_requirements(
+            constraint_strings, vcs_config=vcs_config, marker_environment=marker_env
+        )
+        if constraint_strings
+        else None
+    )
+
+    datetime_str = scenario.get("datetime")
+    return {
+        "requirements": requirements,
+        "python_version": python_version,
+        "uploaded_prior_to": sc.parse_datetime(datetime_str) if datetime_str else None,
+        "constraints": constraints,
+        "marker_environment": marker_environment or None,
+        "indexes": sc.parse_indexes(name, scenario),
+        "index_overrides": sc.parse_index_overrides(name, scenario) or None,
+        "build_policy_overrides": build_policy_overrides or None,
+        "resolution_strategy": resolution_strategy,
+    }
+
+
+def report(name: str, data: dict) -> None:
+    stats = data["stats"]
+    state = "OK" if data["result"]["success"] else f"FAIL {data['result']['error']}"
+    print(
+        f"{name}: {state} in {stats['wall_time_seconds']}s, "
+        f"{stats['decisions']} decisions, {stats['conflicts']} conflicts"
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("scenario", help="bare name or toml_stem:name")
+    parser.add_argument(
+        "--cprofile",
+        action="store_true",
+        help="profile in-process and print the top functions by self time",
+    )
+    parser.add_argument("--limit", type=int, default=30)
+    args = parser.parse_args()
+
+    name, scenario = find_scenario(args.scenario)
+    inputs = build_inputs(name, scenario)
+
+    if not args.cprofile:
+        report(name, sc.resolve_scenario(**inputs))
+        return
+
+    profiler = cProfile.Profile()
+    data = profiler.runcall(sc.resolve_scenario, **inputs)
+    report(name, data)
+    pstats.Stats(profiler).sort_stats("tottime").print_stats(args.limit)
+
+
+if __name__ == "__main__":
+    main()

nab_python-0.0.4/benchmarks/cache/.gitignore

@@ -0,0 +1 @@
+*