scistacklog
The shared logging facade for every scistack layer. This is the lowest-level
package in the stack — it has no dependencies, and every other layer (scifor,
scidb, sciduckdb, …) emits through it or through a plain
logging.getLogger("<layer>") child logger that it covers.
Design
Two audiences, so two files, fed by one emit stream:
-
journal (
scistack.logbeside the database) — for the scientist. One block per run: what ran, the counts, how long, and each failure labelled with who can fix it. Nothing about the framework's internals.── 2026-10-22 17:55:18 clean_asia (run=a3f2c1d9) ───────────────────── finished with 34 failures: ✓ 0 completed ✗ 34 failed – 0 no data 2m 14s ✗ Error in your function clean_asia — 34 combos AttributeError: 'StringArray' object has no attribute 'split' at C:\lab\clean_asia.py:42 in parse_level levels = col.split(",") combos: subject=2204674; subject=2204675; subject=2204676; subject=2204677; subject=2204678 (+29 more) Failed combos saved nothing; completed combos were kept. -
debug file (
scistack-debug.logbeside it) — for whoever debugs SciStack. Everything, at DEBUG by default, capped at 10 MB × 5. Every line written during a run carries therun=<id>the journal block names.2026-10-22 17:55:18.001 INFO [scifor] run=a3f2c1d9 for_each(clean_asia) — 34 iterations: subject=… 2026-10-22 17:55:18.120 DEBUG [scifor] run=a3f2c1d9 failure_from_exception: AttributeError in clean_asia -> blame=user_code via … -
console (stderr) — the narrative for the person watching, at INFO. Time-only timestamps; level prefix only at WARN and above.
The debug file is a superset of the journal: each block is also logged there
(as one [journal] record). scidb.configure_database() points both files
beside the database (scidb.model.log.attach_log_file); directly:
from scistacklog import Log
Log.set_path("proj/scistack-debug.log", journal_path="proj/scistack.log")
Log.set_level("INFO", sink="file") # a quieter debug file
Log.set_level("DEBUG") # both sinks
or set the SCIDB_LOG_LEVEL environment variable (applies to both sinks),
or pass -v to the scidb CLI.
Writing to the journal
with Log.run("compute_psd") as run: # one block per outermost run
run.add_summary(summary_event) # scifor's end-of-run summary
run.count("saved", 114)
Log.journal_note("PSD: 3 columns hold text", key="psd-text") # once per key
Who-can-fix-it (blame) is decided by scifor.failures.classify_blame and
arrives in the event; scistacklog.journal.blame_headline is the one wording.
See docs/claude/logging-architecture.md.
Usage
from scistacklog import Log
Log.info("for_each(compute_psd) — 120 iterations", layer="scifor")
Log.debug("combo detail: %s", combo, layer="scifor")
Log.error("save failed", layer="scidb", exc_info=True)
layer must be one of scistacklog.LAYERS:
scidb, scifor, sciduck, scicanonicalhash, scistack, scistack_gui,
scistackplot, scistackplotdb, scistackstats, scistackstatsdb, matlab.
Timing a hot path
with Log.timer("save_batch(PSD)", extra="114 items") as t:
with t.phase("canonical_hash"): ...
with t.phase("commit"): ...
One INFO summary on exit — [timing] save_batch(PSD): 114 items, TOTAL=0.412s (canonical_hash=0.310s, commit=0.102s) — plus a per-phase table at DEBUG.
TOTAL= appears on the summary line and nowhere else; MATLAB's timing archives
grep for it.
live=True for anything that can run for minutes. A summary is a
post-mortem, and an operation that has not finished yet has no post-mortem: a
25-minute figure save (scistack.log 2026-09-11) logged nothing at all, and a save
that timed out logged nothing ever. A live timer announces each phase as it
starts and as it ends, and enables t.note(...) for progress inside a long
phase:
with Log.timer("save_figure", layer="scistack_gui", live=True) as t:
with t.phase("resolve", extra="2 figure(s)"):
t.note("figure %d/%d", 1, 2)
[timing] save_figure: resolve started — 2 figure(s)
[timing] save_figure: figure 1/2
[timing] save_figure: resolve done in 771.402s
[timing] save_figure: TOTAL=773.918s (resolve=771.402s, render_and_write=2.511s)
t.note is silent on a quiet timer, so the same instrumented code serves a
fast path without flooding it.
Contracts
- caplog: level filtering happens on the two handlers, never on the
loggers — every record propagates to the root logger, so pytest's
caplogcaptures everything regardless of sink levels.Log.*(...)with the default layer emits on logger"scidb", unchanged from the historical implementation. - MATLAB:
scimatlab's+scifor/Log.m(and its member-free subclass+scidb/Log.m) delegates to this class viapy.scistacklog.Log.*(the defining module; MATLAB static dispatch cannot go through thescidb.model.logre-export). The numeric level scale (DEBUG=0 … ERROR=3) and positional call shapes are frozen for that bridge.
Metadata
Release files for scistacklog 0.4.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| scistacklog-0.4.2.tar.gz | 17.4 kB | With provenance | Details for scistacklog-0.4.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| scistacklog-0.4.2-py3-none-any.whl | Python 3 | none | any | Details for scistacklog-0.4.2-py3-none-any.whl |
Total release size: 35.4 kB
Release files / scistacklog-0.4.2.tar.gz
| Download URL | scistacklog-0.4.2.tar.gz |
|---|---|
| Size | 17.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
deae1ce1ff77aab17424ef964ebe4cf680974a9b23584185b5be13fed34a6f4a
|
|
BLAKE2b-256 checksum How to use checksums |
cec702bb73259eee651725cc67af9514a01d0c8722d2cfff5cc6d411826b191f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / scistacklog-0.4.2-py3-none-any.whl
| Download URL | scistacklog-0.4.2-py3-none-any.whl |
|---|---|
| Size | 18.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
05adbb032b215322b823077643acb67deb3ac34c116be6663d2996815c71a27a
|
|
BLAKE2b-256 checksum How to use checksums |
35ec1d8dcab3278b2a8a1e6b956864baadf4be7eff0924efccde97acd201c517
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for scistacklog 0.4.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for scistacklog-0.4.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.