obkit 0.0.1__tar.gz

obkit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omnibenchmark Contributors
+
+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.

obkit-0.0.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: obkit
+Version: 0.0.1
+Summary: Utility toolkit for omnibenchmark modules and Snakemake workflows
+Author: Omnibenchmark Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Omnibenchmark Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://omnibenchmark.org
+Project-URL: Repository, https://github.com/omnibenchmark/obkit
+Project-URL: Issues, https://github.com/omnibenchmark/obkit/issues
+Keywords: omnibenchmark,snakemake,benchmarking,logging,profiling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# obkit
+
+Utility toolkit for [omnibenchmark](https://omnibenchmark.org) modules and
+Snakemake workflows. Pure stdlib, zero runtime dependencies.
+
+The R implementation lives in the same repository under `r/obkit`.
+
+## Install
+
+```bash
+pip install obkit
+```
+
+## Modules
+
+| module        | purpose |
+|---------------|---------|
+| `obkit.logger` | Structured JSONL lifecycle event logging — drop phase-boundary anchors into a log file so downstream tooling can attribute profiler samples to named phases of a rule. |
+| `obkit.prof`   | Parse and align profiler output (denet, Snakemake bench files) with logger events for per-phase resource attribution. *(in progress)* |
+
+## Usage
+
+```python
+from obkit.logger import init_logger, emit
+
+init_logger("/path/to/logdir")
+emit("align", "start")
+# ... do work ...
+emit("align", "end", attrs={"reads": 12345})
+```
+
+Events are written to `omnibench-events.jsonl` inside the directory passed to
+`init_logger`. See the [wire format spec](https://github.com/omnibenchmark/obkit/blob/main/docs/spec-logger.md)
+for the record schema.
+
+## Status
+
+v0.1, pre-release. Wire format is stable; API may still shift.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

obkit-0.0.1/README.md

@@ -0,0 +1,42 @@
+# obkit
+
+Utility toolkit for [omnibenchmark](https://omnibenchmark.org) modules and
+Snakemake workflows. Pure stdlib, zero runtime dependencies.
+
+The R implementation lives in the same repository under `r/obkit`.
+
+## Install
+
+```bash
+pip install obkit
+```
+
+## Modules
+
+| module        | purpose |
+|---------------|---------|
+| `obkit.logger` | Structured JSONL lifecycle event logging — drop phase-boundary anchors into a log file so downstream tooling can attribute profiler samples to named phases of a rule. |
+| `obkit.prof`   | Parse and align profiler output (denet, Snakemake bench files) with logger events for per-phase resource attribution. *(in progress)* |
+
+## Usage
+
+```python
+from obkit.logger import init_logger, emit
+
+init_logger("/path/to/logdir")
+emit("align", "start")
+# ... do work ...
+emit("align", "end", attrs={"reads": 12345})
+```
+
+Events are written to `omnibench-events.jsonl` inside the directory passed to
+`init_logger`. See the [wire format spec](https://github.com/omnibenchmark/obkit/blob/main/docs/spec-logger.md)
+for the record schema.
+
+## Status
+
+v0.1, pre-release. Wire format is stable; API may still shift.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

obkit-0.0.1/obkit/logger/__init__.py

@@ -0,0 +1,63 @@
+import json
+import os
+import socket
+import sys
+from datetime import datetime, timezone
+
+_state = {
+    "log_file": None,
+    "warned_uninit": False,
+}
+
+
+def init_logger(path):
+    if not isinstance(path, str) or not path:
+        raise ValueError("init_logger(): 'path' must be a non-empty string")
+    os.makedirs(path, exist_ok=True)
+    log_file = os.path.join(os.path.realpath(path), "omnibench-events.jsonl")
+    _state["log_file"] = log_file
+    _state["warned_uninit"] = False
+    return log_file
+
+
+def _iso_ts():
+    now = datetime.now(timezone.utc)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def emit(event, phase, attrs=None):
+    if not isinstance(event, str) or not event:
+        raise ValueError("emit(): 'event' must be a non-empty string")
+    if phase not in ("start", "end"):
+        raise ValueError('emit(): \'phase\' must be "start" or "end"')
+
+    log_file = _state["log_file"]
+    if log_file is None:
+        if not _state["warned_uninit"]:
+            print(
+                "obkit: emit() called before init_logger(); events discarded.",
+                file=sys.stderr,
+            )
+            _state["warned_uninit"] = True
+        return False
+
+    rec = {
+        "ts": _iso_ts(),
+        "event": event,
+        "phase": phase,
+        "pid": os.getpid(),
+        "host": socket.gethostname(),
+    }
+    if attrs is not None:
+        if not isinstance(attrs, dict):
+            raise ValueError("emit(): 'attrs' must be a dict")
+        rec["attrs"] = attrs
+
+    try:
+        line = json.dumps(rec, separators=(",", ":"))
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+        return True
+    except Exception as e:
+        print(f"obkit: emit() write failed: {e}", file=sys.stderr)
+        return False

obkit-0.0.1/obkit/prof/__init__.py

@@ -0,0 +1,2 @@
+# prof — parse and align profiling outputs (denet, Snakemake bench files)
+# with logger events for per-phase resource attribution.

obkit-0.0.1/obkit.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: obkit
+Version: 0.0.1
+Summary: Utility toolkit for omnibenchmark modules and Snakemake workflows
+Author: Omnibenchmark Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Omnibenchmark Contributors
+        
+        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.
+        
+Project-URL: Homepage, https://omnibenchmark.org
+Project-URL: Repository, https://github.com/omnibenchmark/obkit
+Project-URL: Issues, https://github.com/omnibenchmark/obkit/issues
+Keywords: omnibenchmark,snakemake,benchmarking,logging,profiling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# obkit
+
+Utility toolkit for [omnibenchmark](https://omnibenchmark.org) modules and
+Snakemake workflows. Pure stdlib, zero runtime dependencies.
+
+The R implementation lives in the same repository under `r/obkit`.
+
+## Install
+
+```bash
+pip install obkit
+```
+
+## Modules
+
+| module        | purpose |
+|---------------|---------|
+| `obkit.logger` | Structured JSONL lifecycle event logging — drop phase-boundary anchors into a log file so downstream tooling can attribute profiler samples to named phases of a rule. |
+| `obkit.prof`   | Parse and align profiler output (denet, Snakemake bench files) with logger events for per-phase resource attribution. *(in progress)* |
+
+## Usage
+
+```python
+from obkit.logger import init_logger, emit
+
+init_logger("/path/to/logdir")
+emit("align", "start")
+# ... do work ...
+emit("align", "end", attrs={"reads": 12345})
+```
+
+Events are written to `omnibench-events.jsonl` inside the directory passed to
+`init_logger`. See the [wire format spec](https://github.com/omnibenchmark/obkit/blob/main/docs/spec-logger.md)
+for the record schema.
+
+## Status
+
+v0.1, pre-release. Wire format is stable; API may still shift.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

obkit-0.0.1/obkit.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+obkit/__init__.py
+obkit.egg-info/PKG-INFO
+obkit.egg-info/SOURCES.txt
+obkit.egg-info/dependency_links.txt
+obkit.egg-info/requires.txt
+obkit.egg-info/top_level.txt
+obkit/logger/__init__.py
+obkit/prof/__init__.py
+tests/test_emit.py
+tests/test_init.py

obkit-0.0.1/obkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

obkit-0.0.1/obkit.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[dev]
+pytest>=7
+ruff>=0.6

obkit-0.0.1/obkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+obkit

obkit-0.0.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "obkit"
+version = "0.0.1"
+description = "Utility toolkit for omnibenchmark modules and Snakemake workflows"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.9"
+authors = [{ name = "Omnibenchmark Contributors" }]
+keywords = ["omnibenchmark", "snakemake", "benchmarking", "logging", "profiling"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Logging",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://omnibenchmark.org"
+Repository = "https://github.com/omnibenchmark/obkit"
+Issues = "https://github.com/omnibenchmark/obkit/issues"
+
+[tool.setuptools.packages.find]
+include = ["obkit*"]
+exclude = ["tests*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

obkit-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

obkit-0.0.1/tests/test_emit.py

@@ -0,0 +1,53 @@
+import json
+import re
+import tempfile
+
+import pytest
+
+from obkit.logger import emit, init_logger
+
+
+def read_events(log_file):
+    with open(log_file) as f:
+        return [json.loads(line) for line in f if line.strip()]
+
+
+def test_emit_writes_required_fields_in_jsonl():
+    with tempfile.TemporaryDirectory() as d:
+        log_file = init_logger(d)
+
+        emit("align", "start")
+        emit("align", "end", attrs={"nreads": 12345, "ok": True})
+
+        events = read_events(log_file)
+        assert len(events) == 2
+
+        ts_pattern = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$")
+        for e in events:
+            assert all(k in e for k in ("ts", "event", "phase", "pid", "host"))
+            assert ts_pattern.match(e["ts"])
+            assert e["event"] == "align"
+
+        assert events[0]["phase"] == "start"
+        assert events[1]["phase"] == "end"
+        assert events[1]["attrs"]["nreads"] == 12345
+        assert events[1]["attrs"]["ok"] is True
+
+
+def test_emit_validates_phase():
+    with tempfile.TemporaryDirectory() as d:
+        init_logger(d)
+        with pytest.raises(ValueError, match=r"start.*end"):
+            emit("x", "begin")
+        with pytest.raises(ValueError, match=r"non-empty"):
+            emit("", "start")
+
+
+def test_emit_appends_across_calls_does_not_truncate():
+    with tempfile.TemporaryDirectory() as d:
+        log_file = init_logger(d)
+        for i in range(5):
+            emit(f"e{i}", "start")
+        with open(log_file) as f:
+            lines = f.readlines()
+        assert len(lines) == 5

obkit-0.0.1/tests/test_init.py

@@ -0,0 +1,38 @@
+import os
+import tempfile
+
+import pytest
+
+from obkit.logger import _state, emit, init_logger
+
+
+def test_init_logger_creates_missing_directory_and_returns_log_path():
+    with tempfile.TemporaryDirectory() as base:
+        d = os.path.join(base, "new-subdir")
+        assert not os.path.exists(d)
+        p = init_logger(d)
+        assert os.path.isdir(d)
+        assert os.path.basename(p) == "omnibench-events.jsonl"
+
+
+def test_init_logger_rejects_bad_input():
+    with pytest.raises((ValueError, TypeError)):
+        init_logger("")
+    with pytest.raises((ValueError, TypeError)):
+        init_logger(None)
+    with pytest.raises((ValueError, TypeError)):
+        init_logger(["a", "b"])
+
+
+def test_emit_without_init_warns_once_and_noops(capsys):
+    _state["log_file"] = None
+    _state["warned_uninit"] = False
+
+    result = emit("x", "start")
+    captured = capsys.readouterr()
+    assert "before init_logger" in captured.err
+    assert result is False
+
+    emit("x", "end")
+    captured2 = capsys.readouterr()
+    assert captured2.err == ""