daftar 0.2.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 (40) hide show
  1. {daftar-0.2.0 → daftar-0.3.1}/CHANGELOG.md +81 -0
  2. {daftar-0.2.0/src/daftar.egg-info → daftar-0.3.1}/PKG-INFO +7 -2
  3. {daftar-0.2.0 → daftar-0.3.1}/README.md +3 -1
  4. {daftar-0.2.0 → daftar-0.3.1}/TROUBLESHOOTING.md +65 -0
  5. {daftar-0.2.0 → daftar-0.3.1}/examples/adapter_usage.py +38 -1
  6. {daftar-0.2.0 → daftar-0.3.1}/pyproject.toml +3 -2
  7. daftar-0.3.1/src/daftar/__version__.py +1 -0
  8. daftar-0.3.1/src/daftar/adapters/__init__.py +61 -0
  9. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/adapters/base.py +33 -0
  10. daftar-0.3.1/src/daftar/adapters/brian2_adapter.py +443 -0
  11. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/adapters/cpm_adapter.py +7 -6
  12. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/adapters/jaxley_adapter.py +7 -6
  13. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/adapters/meltingpot_adapter.py +7 -6
  14. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/capture.py +13 -1
  15. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/cli.py +50 -0
  16. {daftar-0.2.0 → daftar-0.3.1/src/daftar.egg-info}/PKG-INFO +7 -2
  17. {daftar-0.2.0 → daftar-0.3.1}/src/daftar.egg-info/SOURCES.txt +1 -0
  18. {daftar-0.2.0 → daftar-0.3.1}/src/daftar.egg-info/requires.txt +4 -0
  19. {daftar-0.2.0 → daftar-0.3.1}/tests/test_adapters_live.py +155 -4
  20. {daftar-0.2.0 → daftar-0.3.1}/tests/test_core.py +1 -1
  21. daftar-0.2.0/src/daftar/__version__.py +0 -1
  22. daftar-0.2.0/src/daftar/adapters/__init__.py +0 -37
  23. {daftar-0.2.0 → daftar-0.3.1}/LICENSE +0 -0
  24. {daftar-0.2.0 → daftar-0.3.1}/MANIFEST.in +0 -0
  25. {daftar-0.2.0 → daftar-0.3.1}/PUBLISHING.md +0 -0
  26. {daftar-0.2.0 → daftar-0.3.1}/ROADMAP.md +0 -0
  27. {daftar-0.2.0 → daftar-0.3.1}/examples/daftar_in_notebooks.ipynb +0 -0
  28. {daftar-0.2.0 → daftar-0.3.1}/examples/demo_end_to_end.py +0 -0
  29. {daftar-0.2.0 → daftar-0.3.1}/setup.cfg +0 -0
  30. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/__init__.py +0 -0
  31. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/diff.py +0 -0
  32. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/manifest.py +0 -0
  33. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/notebook.py +0 -0
  34. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/run.py +0 -0
  35. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/store.py +0 -0
  36. {daftar-0.2.0 → daftar-0.3.1}/src/daftar/sweep.py +0 -0
  37. {daftar-0.2.0 → daftar-0.3.1}/src/daftar.egg-info/dependency_links.txt +0 -0
  38. {daftar-0.2.0 → daftar-0.3.1}/src/daftar.egg-info/entry_points.txt +0 -0
  39. {daftar-0.2.0 → daftar-0.3.1}/src/daftar.egg-info/top_level.txt +0 -0
  40. {daftar-0.2.0 → daftar-0.3.1}/tests/test_notebook.py +0 -0
@@ -1,5 +1,86 @@
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
+
36
+ ## 0.3.0 — Brian2
37
+
38
+ Brian2 hides more of what determines the answer than any other framework daftar
39
+ supports, which makes it the best argument yet for domain adapters.
40
+
41
+ **The integration method is chosen for you and then forgotten.** Brian2's
42
+ default is not a method but a candidate list, `('exact', 'euler', 'heun')`,
43
+ tried in order until one accepts the equations. Which one wins depends on the
44
+ equations, so a model that integrated `exact` silently falls back to `euler`
45
+ after an edit that makes the system non-linear — changing every result.
46
+
47
+ Brian2 stores the winner nowhere. `state_updater.method_choice` still holds the
48
+ list you never chose from, and the decision appears only in a log line. The
49
+ adapter records both:
50
+
51
+ ```
52
+ param.group.G.method_choice ('exact', 'euler', 'heun') what was permitted
53
+ param.group.G.method_resolved exact what actually ran
54
+ ```
55
+
56
+ Resolution is done by reproducing Brian2's own selection rather than by reading
57
+ its log. That matters: `apply_stateupdater` is cached, so the log line is
58
+ emitted only the first time a set of equations is seen in a process. An earlier
59
+ draft read the log and recorded the method on run 1 and nothing on run 2 —
60
+ making the field appear and disappear between runs, and show up as a spurious
61
+ cause in every diff.
62
+
63
+ **`codegen.target` defaults to `auto`**, which resolves to Cython where a
64
+ compiler exists and NumPy where one does not. The same script takes different
65
+ code paths on a laptop and on a cluster, and neither the script nor the
66
+ preference records which happened. `brian2.codegen_resolved` does.
67
+
68
+ **Fixed: `track(seed=...)` did not seed Brian2.** `brian2.seed()` delegates to
69
+ the current device; seeding numpy does not reach it. Without this,
70
+ `connect(p=0.05)` draws a different synaptic graph on every run, so two
71
+ otherwise identical runs differ with nothing in the manifest to explain it.
72
+ Core seeding now calls it and records `seed.brian2`.
73
+
74
+ Also recorded: the network schedule (reordering thresholds, synapses and resets
75
+ changes results without touching model code), equation hashes with differential
76
+ and parameter variable names, threshold/reset/refractory, per-group `dt`,
77
+ realised synapse counts and delay ranges, `core.default_float_dtype`, and
78
+ monitor output as comparable scalars rather than traces.
79
+
80
+ Four live tests against a real Brian2 network. Two identical runs now diff to
81
+ `identical` including the synapse count, which is the check that proves the
82
+ seeding fix.
83
+
3
84
  ## 0.2.0 — notebooks
4
85
 
5
86
  Notebooks are where provenance dies, and until now daftar was no better there
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.2.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
@@ -21,6 +21,8 @@ Provides-Extra: cpm
21
21
  Requires-Dist: cpm-toolbox; extra == "cpm"
22
22
  Provides-Extra: meltingpot
23
23
  Requires-Dist: dm-meltingpot; extra == "meltingpot"
24
+ Provides-Extra: brian2
25
+ Requires-Dist: brian2; extra == "brian2"
24
26
  Provides-Extra: dev
25
27
  Requires-Dist: pytest>=7; extra == "dev"
26
28
  Requires-Dist: numpy; extra == "dev"
@@ -31,6 +33,7 @@ Provides-Extra: all
31
33
  Requires-Dist: jaxley; extra == "all"
32
34
  Requires-Dist: cpm-toolbox; extra == "all"
33
35
  Requires-Dist: dm-meltingpot; extra == "all"
36
+ Requires-Dist: brian2; extra == "all"
34
37
  Dynamic: license-file
35
38
 
36
39
  # daftar
@@ -126,7 +129,7 @@ Three consequences of taking that seriously:
126
129
  |---|---|
127
130
  | `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
128
131
  | `param.*` | everything you chose, including defaults you never passed |
129
- | `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
132
+ | `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
130
133
  | `input.*` | sha256 and size of every declared input file or directory |
131
134
  | `env.*` | interpreter, OS, versions of packages the run imported, **and where each was installed from** |
132
135
  | `result.*` | scalar outcomes worth comparing |
@@ -173,6 +176,7 @@ daftar diff r-4f21ab r-88c07e # what changed, and whether it mattered
173
176
  daftar vary -l my-sweep # which fields differ across many runs
174
177
  daftar replay r-4f21ab # what it would take to reproduce this
175
178
  daftar export r-4f21ab -o run.zip
179
+ daftar doctor # which adapters work here, and why not
176
180
  ```
177
181
 
178
182
  `diff` exits 0 if the second run reproduces the first and 1 otherwise, so it
@@ -310,6 +314,7 @@ knowing something a generic tracker cannot infer.
310
314
  |---|---|
311
315
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
312
316
  | `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
317
+ | `brian2` | **the integration method Brian2 actually chose** (its default is a candidate list, and the winner is stored nowhere), resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
313
318
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
314
319
 
315
320
  All three are verified against live installs by `tests/test_adapters_live.py`,
@@ -91,7 +91,7 @@ Three consequences of taking that seriously:
91
91
  |---|---|
92
92
  | `code.*` | git commit, branch, dirty flag, **hash of uncommitted changes**, entrypoint, argv |
93
93
  | `param.*` | everything you chose, including defaults you never passed |
94
- | `seed.*` | seeds **applied** to `random`, numpy, torch; the JAX root key |
94
+ | `seed.*` | seeds **applied** to `random`, numpy, torch, **Brian2's device RNG**; the JAX root key |
95
95
  | `input.*` | sha256 and size of every declared input file or directory |
96
96
  | `env.*` | interpreter, OS, versions of packages the run imported, **and where each was installed from** |
97
97
  | `result.*` | scalar outcomes worth comparing |
@@ -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
@@ -275,6 +276,7 @@ knowing something a generic tracker cannot infer.
275
276
  |---|---|
276
277
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
277
278
  | `cpm` | parameter **bounds and priors**, estimator and its scipy method/tolerance, per-participant convergence counts, cohort hash |
279
+ | `brian2` | **the integration method Brian2 actually chose** (its default is a candidate list, and the winner is stored nowhere), resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
278
280
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
279
281
 
280
282
  All three are verified against live installs by `tests/test_adapters_live.py`,
@@ -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
@@ -63,6 +63,42 @@ with daftar.track("bandit-fit", seed=7) as run:
63
63
  # and nothing in the output tells you which you have.
64
64
  '''
65
65
 
66
+ # ---------------------------------------------------------------- Brian2 ---
67
+ BRIAN2 = '''
68
+ from brian2 import *
69
+ import daftar
70
+ from daftar.adapters import brian2 as b2a
71
+
72
+ eqs = """dv/dt = (I-v)/tau : 1
73
+ I : 1
74
+ tau : second"""
75
+ G = NeuronGroup(100, eqs, threshold="v>1", reset="v=0", name="G")
76
+ G.I = "1.5 + 0.5*rand()"; G.tau = 10*ms
77
+ S = Synapses(G, G, on_pre="v_post += 0.05", name="S"); S.connect(p=0.05)
78
+ net = Network(G, S, SpikeMonitor(G, name="spikes"))
79
+
80
+ with daftar.track("balanced-net", seed=42) as run:
81
+ b2a.run_network(net, 1*second, run)
82
+
83
+ # Recorded automatically:
84
+ # group.G.method_choice = (exact, euler, heun) <- what was permitted
85
+ # group.G.method_resolved = exact <- what actually ran
86
+ # brian2.codegen_resolved = cython (auto) <- auto means machine-dependent
87
+ # brian2.prefs.core.default_float_dtype = float64
88
+ # network.schedule = [start, groups, thresholds, synapses, resets, end]
89
+ # synapses.S.n_synapses = 496 <- p=0.05 is drawn, not declared
90
+ # result.monitor.spikes.num_spikes
91
+ #
92
+ # method_resolved is the one to watch. Brian2's default is a candidate list, not
93
+ # a method: a model that integrated `exact` silently falls back to `euler` after
94
+ # an edit that makes the equations non-linear. Brian2 stores the winner nowhere
95
+ # -- it only mentions it in a log line, once per process.
96
+ #
97
+ # Note also that daftar.track(seed=...) now calls brian2.seed(). Seeding numpy
98
+ # does not reach Brian2's device RNG, so without it `connect(p=0.05)` draws a
99
+ # different graph every run.
100
+ '''
101
+
66
102
  # ------------------------------------------------------------ MeltingPot ---
67
103
  MELTINGPOT = '''
68
104
  import daftar
@@ -120,7 +156,8 @@ def main():
120
156
 
121
157
  print("\nReference usage:")
122
158
  for title, snippet in (
123
- ("Jaxley", JAXLEY), ("cpm", CPM), ("MeltingPot", MELTINGPOT),
159
+ ("Jaxley", JAXLEY), ("cpm", CPM), ("Brian2", BRIAN2),
160
+ ("MeltingPot", MELTINGPOT),
124
161
  ):
125
162
  print(f"\n{'-' * 70}\n{title}\n{'-' * 70}{snippet}")
126
163
  print(f"\n{'-' * 70}\nConcordia -- why it is not here yet\n{'-' * 70}{CONCORDIA_NOTE}")
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "daftar"
7
- version = "0.2.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"
@@ -29,9 +29,10 @@ Issues = "https://github.com/aslansd/daftar/issues"
29
29
  jaxley = ["jaxley"]
30
30
  cpm = ["cpm-toolbox"]
31
31
  meltingpot = ["dm-meltingpot"]
32
+ brian2 = ["brian2"]
32
33
  dev = ["pytest>=7", "numpy", "ipython"]
33
34
  notebook = ["ipython"]
34
- all = ["jaxley", "cpm-toolbox", "dm-meltingpot"]
35
+ all = ["jaxley", "cpm-toolbox", "dm-meltingpot", "brian2"]
35
36
 
36
37
  [project.scripts]
37
38
  daftar = "daftar.cli:main"
@@ -0,0 +1 @@
1
+ __version__ = "0.3.1"
@@ -0,0 +1,61 @@
1
+ """Framework adapters.
2
+
3
+ Import is lazy on purpose: someone with Jaxley but not MeltingPot installed must
4
+ still be able to ``import daftar``. Nothing here imports a target framework
5
+ at module load.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from . import brian2_adapter, cpm_adapter, jaxley_adapter, meltingpot_adapter
11
+ from .base import (
12
+ AVAILABLE, BROKEN, MISSING, Adapter, AdapterRegistry, probe_import,
13
+ record_optional, safe,
14
+ )
15
+
16
+ registry = AdapterRegistry()
17
+ registry.register("jaxley", jaxley_adapter)
18
+ registry.register("cpm", cpm_adapter)
19
+ registry.register("meltingpot", meltingpot_adapter)
20
+ registry.register("brian2", brian2_adapter)
21
+
22
+ jaxley = jaxley_adapter
23
+ cpm = cpm_adapter
24
+ meltingpot = meltingpot_adapter
25
+ brian2 = brian2_adapter
26
+
27
+
28
+ def available() -> list[str]:
29
+ """Adapters whose target framework is importable right now."""
30
+ return registry.available()
31
+
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
+
51
+ def get(name: str):
52
+ return registry.get(name)
53
+
54
+
55
+ __all__ = [
56
+ "registry", "available", "get",
57
+ "jaxley", "cpm", "meltingpot", "brian2",
58
+ "jaxley_adapter", "cpm_adapter", "meltingpot_adapter", "brian2_adapter",
59
+ "Adapter", "AdapterRegistry", "safe", "record_optional",
60
+ "status", "probe_import", "AVAILABLE", "MISSING", "BROKEN",
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>")