daftar 0.3.0__tar.gz → 0.3.1__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 (39) hide show
  1. {daftar-0.3.0 → daftar-0.3.1}/CHANGELOG.md +33 -0
  2. {daftar-0.3.0/src/daftar.egg-info → daftar-0.3.1}/PKG-INFO +2 -1
  3. {daftar-0.3.0 → daftar-0.3.1}/README.md +1 -0
  4. {daftar-0.3.0 → daftar-0.3.1}/TROUBLESHOOTING.md +65 -0
  5. {daftar-0.3.0 → daftar-0.3.1}/pyproject.toml +1 -1
  6. daftar-0.3.1/src/daftar/__version__.py +1 -0
  7. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/__init__.py +23 -1
  8. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/base.py +33 -0
  9. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/brian2_adapter.py +7 -6
  10. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/cpm_adapter.py +7 -6
  11. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/jaxley_adapter.py +7 -6
  12. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/adapters/meltingpot_adapter.py +7 -6
  13. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/cli.py +50 -0
  14. {daftar-0.3.0 → daftar-0.3.1/src/daftar.egg-info}/PKG-INFO +2 -1
  15. {daftar-0.3.0 → daftar-0.3.1}/tests/test_adapters_live.py +22 -4
  16. daftar-0.3.0/src/daftar/__version__.py +0 -1
  17. {daftar-0.3.0 → daftar-0.3.1}/LICENSE +0 -0
  18. {daftar-0.3.0 → daftar-0.3.1}/MANIFEST.in +0 -0
  19. {daftar-0.3.0 → daftar-0.3.1}/PUBLISHING.md +0 -0
  20. {daftar-0.3.0 → daftar-0.3.1}/ROADMAP.md +0 -0
  21. {daftar-0.3.0 → daftar-0.3.1}/examples/adapter_usage.py +0 -0
  22. {daftar-0.3.0 → daftar-0.3.1}/examples/daftar_in_notebooks.ipynb +0 -0
  23. {daftar-0.3.0 → daftar-0.3.1}/examples/demo_end_to_end.py +0 -0
  24. {daftar-0.3.0 → daftar-0.3.1}/setup.cfg +0 -0
  25. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/__init__.py +0 -0
  26. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/capture.py +0 -0
  27. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/diff.py +0 -0
  28. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/manifest.py +0 -0
  29. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/notebook.py +0 -0
  30. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/run.py +0 -0
  31. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/store.py +0 -0
  32. {daftar-0.3.0 → daftar-0.3.1}/src/daftar/sweep.py +0 -0
  33. {daftar-0.3.0 → daftar-0.3.1}/src/daftar.egg-info/SOURCES.txt +0 -0
  34. {daftar-0.3.0 → daftar-0.3.1}/src/daftar.egg-info/dependency_links.txt +0 -0
  35. {daftar-0.3.0 → daftar-0.3.1}/src/daftar.egg-info/entry_points.txt +0 -0
  36. {daftar-0.3.0 → daftar-0.3.1}/src/daftar.egg-info/requires.txt +0 -0
  37. {daftar-0.3.0 → daftar-0.3.1}/src/daftar.egg-info/top_level.txt +0 -0
  38. {daftar-0.3.0 → daftar-0.3.1}/tests/test_core.py +0 -0
  39. {daftar-0.3.0 → daftar-0.3.1}/tests/test_notebook.py +0 -0
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.3.1
4
+
5
+ **A framework that is installed but broken is no longer reported as absent.**
6
+ Every adapter's `is_available()` was a bare `try: import x except: return False`,
7
+ so an import that failed for *any* reason looked exactly like a package that was
8
+ never installed. The live tests then skipped quietly and nothing said why.
9
+
10
+ This surfaced with Brian2: `pip install brian2` on Python 3.11 resolves to 2.9.0
11
+ (the newest supporting that interpreter), which calls `ndarray.ptp` — removed in
12
+ NumPy 2.0. It imports with an `AttributeError`, the tests skipped, and the output
13
+ was indistinguishable from Brian2 not being installed at all.
14
+
15
+ Adapters now expose `availability() -> (status, reason)` with three states:
16
+ `available`, `missing`, and **`broken`** carrying the exception. Live tests skip
17
+ with that reason attached rather than a generic "not installed".
18
+
19
+ **New: `daftar doctor`.** Reports the interpreter, the daftar version, and every
20
+ adapter's status with the reason for any failure. Exits 1 if anything is broken,
21
+ so it is usable in CI. It generalises the ad-hoc `diagnose_jaxley.py`.
22
+
23
+ ```
24
+ daftar 0.3.1
25
+ python 3.11.16 on Darwin arm64
26
+
27
+ brian2 BROKEN AttributeError: type object 'numpy.ndarray' has no attribute 'ptp'
28
+ cpm ok
29
+ jaxley ok
30
+ meltingpot ok
31
+ ```
32
+
33
+ `TROUBLESHOOTING.md` documents the Brian2 / NumPy 2 / Python 3.12 trap and why
34
+ downgrading NumPy is the wrong fix.
35
+
3
36
  ## 0.3.0 — Brian2
4
37
 
5
38
  Brian2 hides more of what determines the answer than any other framework daftar
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.3.0
3
+ Version: 0.3.1
4
4
  Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
5
5
  Author: Aslan Satary Dizaji
6
6
  License-Expression: Apache-2.0
@@ -176,6 +176,7 @@ daftar diff r-4f21ab r-88c07e # what changed, and whether it mattered
176
176
  daftar vary -l my-sweep # which fields differ across many runs
177
177
  daftar replay r-4f21ab # what it would take to reproduce this
178
178
  daftar export r-4f21ab -o run.zip
179
+ daftar doctor # which adapters work here, and why not
179
180
  ```
180
181
 
181
182
  `diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
@@ -138,6 +138,7 @@ daftar diff r-4f21ab r-88c07e # what changed, and whether it mattered
138
138
  daftar vary -l my-sweep # which fields differ across many runs
139
139
  daftar replay r-4f21ab # what it would take to reproduce this
140
140
  daftar export r-4f21ab -o run.zip
141
+ daftar doctor # which adapters work here, and why not
141
142
  ```
142
143
 
143
144
  `diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
@@ -225,6 +225,54 @@ wrong".
225
225
 
226
226
  ---
227
227
 
228
+ ## Brian2: `type object 'numpy.ndarray' has no attribute 'ptp'`
229
+
230
+ Brian2 is installed and imports fail. The adapter tests skip, and older daftar
231
+ versions skipped *silently* because a broken import looked identical to an
232
+ absent package. Run `daftar doctor` to see the difference.
233
+
234
+ **The cause is a three-way version trap:**
235
+
236
+ | | |
237
+ |---|---|
238
+ | NumPy 2.0 removed `ndarray.ptp` | you have numpy 2.x |
239
+ | brian2 ≤ 2.9 still calls it | so it cannot import under numpy 2 |
240
+ | brian2 ≥ 2.10 fixed it, and **requires Python ≥ 3.12** | your env is Python 3.11 |
241
+
242
+ So `pip install brian2` on Python 3.11 correctly resolves to 2.9.0 — the newest
243
+ release that supports your interpreter — and that release cannot work with the
244
+ NumPy you have. **On Python 3.11 there is no brian2 version compatible with
245
+ NumPy 2.x.**
246
+
247
+ ### Fix: a Python 3.12 environment
248
+
249
+ ```bash
250
+ conda create --name daftar312 python=3.12
251
+ conda activate daftar312
252
+ pip install daftar brian2 jaxley cpm-toolbox pytest
253
+ python -c "import brian2; print(brian2.__version__)" # expect >= 2.10
254
+ daftar doctor
255
+ ```
256
+
257
+ ### Why not just downgrade NumPy instead
258
+
259
+ `pip install "numpy<2"` would fix Brian2 and break the rest of the environment:
260
+ jaxley, cpm-toolbox and pandas 3.x in your setup all expect NumPy 2. Pinning
261
+ NumPy back to satisfy one framework is how an environment becomes unreproducible
262
+ in the way this whole package exists to detect.
263
+
264
+ ### If you must stay on Python 3.11
265
+
266
+ Keep two environments: 3.11 for MeltingPot (whose `dmlab2d` wheel coverage is
267
+ narrow) and 3.12 for Brian2. The adapter tests skip cleanly in whichever
268
+ framework is absent, so both environments give a green suite.
269
+
270
+ Do not attempt to have every adapter live in one environment. Four research
271
+ frameworks with independent release schedules will eventually make that
272
+ impossible, and the honest answer is to test each where it works.
273
+
274
+ ---
275
+
228
276
  ## MeltingPot will not install
229
277
 
230
278
  `dm-meltingpot` depends on `dmlab2d`, whose wheel coverage is narrow and weakest
@@ -270,6 +318,23 @@ wrong, and re-running `daftar replay` on an old run now prints correctly.
270
318
 
271
319
  ---
272
320
 
321
+ ## Which adapters actually work here?
322
+
323
+ ```bash
324
+ daftar doctor
325
+ ```
326
+
327
+ Reports the daftar version, the interpreter, and every adapter as `ok`,
328
+ `not installed`, or **`BROKEN`** with the exception that caused it. Exit code is
329
+ 1 if anything is broken, so it works in CI.
330
+
331
+ `BROKEN` means the framework is installed and will not import — an incompatible
332
+ NumPy, a missing shared library, a clash with another package. That is fixable
333
+ and worth knowing about; "not installed" usually is not. Conflating the two is
334
+ how a broken environment goes unnoticed for weeks.
335
+
336
+ ---
337
+
273
338
  ## Adapter tests pass but a manifest field says `<unavailable>`
274
339
 
275
340
  Working as designed, and worth understanding. `adapters/base.py` wraps every
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "daftar"
7
- version = "0.3.0"
7
+ version = "0.3.1"
8
8
  description = "Record what produced each computational result: environment, code, parameters, seeds, inputs."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -0,0 +1 @@
1
+ __version__ = "0.3.1"
@@ -8,7 +8,10 @@ at module load.
8
8
  from __future__ import annotations
9
9
 
10
10
  from . import brian2_adapter, cpm_adapter, jaxley_adapter, meltingpot_adapter
11
- from .base import Adapter, AdapterRegistry, record_optional, safe
11
+ from .base import (
12
+ AVAILABLE, BROKEN, MISSING, Adapter, AdapterRegistry, probe_import,
13
+ record_optional, safe,
14
+ )
12
15
 
13
16
  registry = AdapterRegistry()
14
17
  registry.register("jaxley", jaxley_adapter)
@@ -27,6 +30,24 @@ def available() -> list[str]:
27
30
  return registry.available()
28
31
 
29
32
 
33
+ def status() -> dict[str, tuple[str, str]]:
34
+ """``{adapter: (status, reason)}`` for every registered adapter.
35
+
36
+ Distinguishes an absent framework from a broken one. A framework that is
37
+ installed but fails to import -- an incompatible NumPy, a missing shared
38
+ library -- is a situation the user can fix, and it must not be reported the
39
+ same way as one they simply have not installed.
40
+ """
41
+ out: dict[str, tuple[str, str]] = {}
42
+ for name in registry.all():
43
+ mod = registry.get(name)
44
+ try:
45
+ out[name] = mod.availability()
46
+ except Exception as exc: # pragma: no cover - defensive
47
+ out[name] = (BROKEN, f"{type(exc).__name__}: {exc}")
48
+ return out
49
+
50
+
30
51
  def get(name: str):
31
52
  return registry.get(name)
32
53
 
@@ -36,4 +57,5 @@ __all__ = [
36
57
  "jaxley", "cpm", "meltingpot", "brian2",
37
58
  "jaxley_adapter", "cpm_adapter", "meltingpot_adapter", "brian2_adapter",
38
59
  "Adapter", "AdapterRegistry", "safe", "record_optional",
60
+ "status", "probe_import", "AVAILABLE", "MISSING", "BROKEN",
39
61
  ]
@@ -80,6 +80,39 @@ def safe(fn, default=None):
80
80
  return default
81
81
 
82
82
 
83
+ #: An adapter's target framework is in one of three states, and conflating the
84
+ #: last two is how a broken environment gets mistaken for an absent one.
85
+ AVAILABLE = "available"
86
+ MISSING = "missing"
87
+ BROKEN = "broken"
88
+
89
+
90
+ def probe_import(module_name: str) -> tuple[str, str]:
91
+ """Try to import a framework. Returns ``(status, reason)``.
92
+
93
+ ``ImportError`` means the package is not installed, which is ordinary and
94
+ uninteresting. **Any other exception means it is installed and broken** --
95
+ an incompatible NumPy, a missing shared library, a version clash with
96
+ another package. Those two cases need different responses from the user and
97
+ must not look identical.
98
+
99
+ This distinction exists because a bare ``try: import x except: False``
100
+ reports a broken install as an absent one. The test suite then skips
101
+ quietly, the adapter is never exercised, and nothing anywhere says why.
102
+ """
103
+ try:
104
+ __import__(module_name)
105
+ return AVAILABLE, ""
106
+ except ImportError as exc:
107
+ # A broken C extension also raises ImportError, so check the message.
108
+ text = str(exc)
109
+ if "No module named" in text:
110
+ return MISSING, "not installed"
111
+ return BROKEN, f"{type(exc).__name__}: {text}"
112
+ except Exception as exc:
113
+ return BROKEN, f"{type(exc).__name__}: {exc}"
114
+
115
+
83
116
  def record_optional(run: Run, key: str, fn, *, kind: str = "param") -> None:
84
117
  """Record ``fn()`` under ``key``, or note that it could not be read."""
85
118
  value = safe(fn, default="<unavailable>")
@@ -35,7 +35,7 @@ import re
35
35
  from typing import Any
36
36
 
37
37
  from ..run import Run
38
- from .base import safe
38
+ from .base import AVAILABLE, probe_import, safe
39
39
 
40
40
  name = "brian2"
41
41
 
@@ -49,12 +49,13 @@ _METHOD_PATTERNS = (
49
49
  )
50
50
 
51
51
 
52
+ def availability() -> tuple[str, str]:
53
+ """``(status, reason)`` -- see ``adapters.base.probe_import``."""
54
+ return probe_import("brian2")
55
+
56
+
52
57
  def is_available() -> bool:
53
- try:
54
- import brian2 # noqa: F401
55
- return True
56
- except Exception:
57
- return False
58
+ return availability()[0] == AVAILABLE
58
59
 
59
60
 
60
61
  def _sha(text: str) -> str:
@@ -26,17 +26,18 @@ import hashlib
26
26
  from typing import Any
27
27
 
28
28
  from ..run import Run
29
- from .base import safe
29
+ from .base import AVAILABLE, probe_import, safe
30
30
 
31
31
  name = "cpm"
32
32
 
33
33
 
34
+ def availability() -> tuple[str, str]:
35
+ """``(status, reason)`` -- see ``adapters.base.probe_import``."""
36
+ return probe_import("cpm")
37
+
38
+
34
39
  def is_available() -> bool:
35
- try:
36
- import cpm # noqa: F401
37
- return True
38
- except Exception:
39
- return False
40
+ return availability()[0] == AVAILABLE
40
41
 
41
42
 
42
43
  # --------------------------------------------------------------------------
@@ -22,7 +22,7 @@ import sys
22
22
  from typing import Any
23
23
 
24
24
  from ..run import Run
25
- from .base import safe
25
+ from .base import AVAILABLE, probe_import, safe
26
26
 
27
27
  name = "jaxley"
28
28
 
@@ -38,12 +38,13 @@ INTEGRATE_DEFAULTS = {
38
38
  }
39
39
 
40
40
 
41
+ def availability() -> tuple[str, str]:
42
+ """``(status, reason)`` -- see ``adapters.base.probe_import``."""
43
+ return probe_import("jaxley")
44
+
45
+
41
46
  def is_available() -> bool:
42
- try:
43
- import jaxley # noqa: F401
44
- return True
45
- except Exception:
46
- return False
47
+ return availability()[0] == AVAILABLE
47
48
 
48
49
 
49
50
  def _jax_config(run: Run) -> None:
@@ -27,17 +27,18 @@ import hashlib
27
27
  from typing import Any, Callable, Sequence
28
28
 
29
29
  from ..run import Run
30
- from .base import safe
30
+ from .base import AVAILABLE, probe_import, safe
31
31
 
32
32
  name = "meltingpot"
33
33
 
34
34
 
35
+ def availability() -> tuple[str, str]:
36
+ """``(status, reason)`` -- see ``adapters.base.probe_import``."""
37
+ return probe_import("meltingpot")
38
+
39
+
35
40
  def is_available() -> bool:
36
- try:
37
- import meltingpot # noqa: F401
38
- return True
39
- except Exception:
40
- return False
41
+ return availability()[0] == AVAILABLE
41
42
 
42
43
 
43
44
  def _config_hash(config: Any) -> str:
@@ -101,6 +101,53 @@ def cmd_vary(args) -> int:
101
101
  return 0
102
102
 
103
103
 
104
+ def cmd_doctor(args) -> int:
105
+ """Report the environment and every adapter's status, with reasons."""
106
+ import platform
107
+
108
+ from . import adapters
109
+ from .__version__ import __version__
110
+ from .adapters.base import AVAILABLE, BROKEN
111
+
112
+ print(f"daftar {__version__}")
113
+ print(f"python {platform.python_version()} on {platform.system()} "
114
+ f"{platform.machine()}")
115
+ print()
116
+
117
+ table = adapters.status()
118
+ width = max(len(n) for n in table)
119
+ broken = []
120
+ for name in sorted(table):
121
+ state, reason = table[name]
122
+ mark = {AVAILABLE: "ok", BROKEN: "BROKEN"}.get(state, "-")
123
+ line = f" {name.ljust(width)} {mark:<7}"
124
+ if state != AVAILABLE and reason:
125
+ line += f" {reason}"
126
+ print(line)
127
+ if state == BROKEN:
128
+ broken.append((name, reason))
129
+
130
+ if broken:
131
+ print()
132
+ print("An adapter's framework is installed but will not import. That is")
133
+ print("not the same as it being absent, and it is usually fixable:")
134
+ for name, reason in broken:
135
+ print(f" - {name}: {reason}")
136
+ print()
137
+ print("See TROUBLESHOOTING.md. Common cause: the framework predates a")
138
+ print("major NumPy release, and the version that supports current NumPy")
139
+ print("needs a newer Python than this environment has.")
140
+
141
+ store = _store(args)
142
+ print()
143
+ print(f"run store: {store.dir}"
144
+ + ("" if store.runs_dir.exists() else " (not initialised)"))
145
+ if store.runs_dir.exists():
146
+ print(f"runs recorded: {len(store.list_ids())}")
147
+
148
+ return 1 if broken else 0
149
+
150
+
104
151
  def cmd_reindex(args) -> int:
105
152
  n = _store(args).reindex()
106
153
  print(f"Reindexed {n} run(s).")
@@ -152,6 +199,9 @@ def build_parser() -> argparse.ArgumentParser:
152
199
  s.add_argument("-l", "--label")
153
200
  s.set_defaults(func=cmd_vary)
154
201
 
202
+ s = sub.add_parser("doctor", help="report environment and adapter status")
203
+ s.set_defaults(func=cmd_doctor)
204
+
155
205
  s = sub.add_parser("reindex", help="rebuild the index from manifests")
156
206
  s.set_defaults(func=cmd_reindex)
157
207
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.3.0
3
+ Version: 0.3.1
4
4
  Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
5
5
  Author: Aslan Satary Dizaji
6
6
  License-Expression: Apache-2.0
@@ -176,6 +176,7 @@ daftar diff r-4f21ab r-88c07e # what changed, and whether it mattered
176
176
  daftar vary -l my-sweep # which fields differ across many runs
177
177
  daftar replay r-4f21ab # what it would take to reproduce this
178
178
  daftar export r-4f21ab -o run.zip
179
+ daftar doctor # which adapters work here, and why not
179
180
  ```
180
181
 
181
182
  `diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
@@ -34,10 +34,23 @@ def store(tmp_path, monkeypatch):
34
34
 
35
35
 
36
36
  def _require(name: str):
37
- return pytest.mark.skipif(
38
- not daftar.adapters.get(name).is_available(),
39
- reason=f"{name} not installed",
40
- )
37
+ """Skip with a reason that distinguishes absent from broken.
38
+
39
+ A framework that is installed but fails to import is a different situation
40
+ from one that was never installed, and the user can act on it. Reporting
41
+ both as "not installed" is how a broken environment goes unnoticed: the
42
+ suite skips quietly and nothing anywhere says why.
43
+ """
44
+ state, reason = daftar.adapters.get(name).availability()
45
+ if state == daftar.adapters.AVAILABLE:
46
+ return pytest.mark.skipif(False, reason="")
47
+ if state == daftar.adapters.BROKEN:
48
+ return pytest.mark.skipif(
49
+ True,
50
+ reason=(f"{name} is INSTALLED BUT BROKEN -- {reason}. "
51
+ f"Run `daftar doctor`; see TROUBLESHOOTING.md"),
52
+ )
53
+ return pytest.mark.skipif(True, reason=f"{name} not installed")
41
54
 
42
55
 
43
56
  def _jaxley_is_usable() -> tuple[bool, str]:
@@ -341,6 +354,11 @@ def test_at_least_report_what_is_installed():
341
354
  mark = "yes" if name in available else "no"
342
355
  print(f" {name:<12} {mark}")
343
356
 
357
+ print("\nadapter status:")
358
+ for name, (state, reason) in sorted(daftar.adapters.status().items()):
359
+ detail = f" {reason}" if reason else ""
360
+ print(f" {name:<12} {state}{detail}")
361
+
344
362
  print("\nframework versions:")
345
363
  for dist in ("jaxley", "jax", "jaxlib", "cpm-toolbox", "dm-meltingpot",
346
364
  "dmlab2d", "numpy", "scipy"):
@@ -1 +0,0 @@
1
- __version__ = "0.3.0"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes