pkdb 0.11.0__tar.gz

pkdb-0.11.0/.gitignore

@@ -0,0 +1,32 @@
+__pycache__/
+*.py[cod]
+*.log
+*.ods#
+*.xlsx#
+.env
+.env.*
+!.env.example
+.venv*/
+.cache/
+.pytest_cache/
+.ruff_cache/
+.coverage*
+coverage.xml
+htmlcov/
+dist/
+*.egg-info/
+.ipynb_checkpoints/
+.idea/
+/site/
+node_modules/
+.git-credentials
+*.dump
+*.sql.gz
+
+# Preserve ignored local data and caches from existing checkouts.
+/volumes/
+/static/
+media/
+.static_storage/
+.tox/
+.hypothesis/

pkdb-0.11.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2017-2026 Matthias König
+
+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.

pkdb-0.11.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: pkdb
+Version: 0.11.0
+Summary: Prepare, validate, query, and upload PK-DB studies
+Project-URL: Homepage, https://pk-db.com
+Project-URL: Documentation, https://matthiaskoenig.github.io/pkdb/
+Project-URL: Repository, https://github.com/matthiaskoenig/pkdb
+Project-URL: Issues, https://github.com/matthiaskoenig/pkdb/issues
+Author: Matthias König
+License-Expression: MIT
+License-File: LICENSE
+Keywords: pharmacokinetics,pk-db,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.15,>=3.14
+Requires-Dist: httpx2<3,>=2.13.0
+Requires-Dist: numpy<3,>=2.5.3
+Requires-Dist: openpyxl<4,>=3.1.5
+Requires-Dist: pandas<4,>=3.0.6
+Requires-Dist: pint<1,>=0.26.1
+Requires-Dist: pkpdutils<2,>=1.2.0
+Requires-Dist: pydantic<3,>=2.13.5
+Requires-Dist: scipy<2,>=1.18.1
+Description-Content-Type: text/markdown
+
+# PK-DB Python client
+
+Prepare, validate, query, and upload pharmacokinetic studies with the same scientific validation engine used by the PK-DB server. Python 3.14 is supported on Linux, macOS, and Windows.
+
+Install a published release with `pip install pkdb`, or install this checkout with `pip install ./python` from the repository root.
+
+Existing `pkdb_data` study folders work directly:
+
+```bash
+pkdb prepare studies/ExampleStudy
+pkdb validate studies/ExampleStudy --offline
+pkdb upload studies/ExampleStudy --endpoint https://pk-db.com
+```
+
+Preparation and validation work offline using the bundled vocabulary. Upload validates locally first and then the server validates the original files again. Set `PKDB_API_KEY` for authenticated operations and optionally `PKDB_ENDPOINT` for the default endpoint.
+
+```python
+from pkdb import prepare
+
+prepared = prepare("studies/ExampleStudy")
+print(prepared.study.sid)
+```
+
+See the [client documentation](https://matthiaskoenig.github.io/pkdb/python-client/) for vocabulary snapshots, structured reports, authentication, queries, and downloads. The source repository contains the separate `pkdb-server` distribution, which depends on the exact matching public client release.

pkdb-0.11.0/README.md

@@ -0,0 +1,24 @@
+# PK-DB Python client
+
+Prepare, validate, query, and upload pharmacokinetic studies with the same scientific validation engine used by the PK-DB server. Python 3.14 is supported on Linux, macOS, and Windows.
+
+Install a published release with `pip install pkdb`, or install this checkout with `pip install ./python` from the repository root.
+
+Existing `pkdb_data` study folders work directly:
+
+```bash
+pkdb prepare studies/ExampleStudy
+pkdb validate studies/ExampleStudy --offline
+pkdb upload studies/ExampleStudy --endpoint https://pk-db.com
+```
+
+Preparation and validation work offline using the bundled vocabulary. Upload validates locally first and then the server validates the original files again. Set `PKDB_API_KEY` for authenticated operations and optionally `PKDB_ENDPOINT` for the default endpoint.
+
+```python
+from pkdb import prepare
+
+prepared = prepare("studies/ExampleStudy")
+print(prepared.study.sid)
+```
+
+See the [client documentation](https://matthiaskoenig.github.io/pkdb/python-client/) for vocabulary snapshots, structured reports, authentication, queries, and downloads. The source repository contains the separate `pkdb-server` distribution, which depends on the exact matching public client release.

pkdb-0.11.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pkdb"
+version = "0.11.0"
+description = "Prepare, validate, query, and upload PK-DB studies"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Matthias König" }]
+keywords = ["pharmacokinetics", "validation", "pk-db"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+requires-python = ">=3.14,<3.15"
+dependencies = [
+  "pydantic>=2.13.5,<3",
+  "pandas>=3.0.6,<4",
+  "numpy>=2.5.3,<3",
+  "scipy>=1.18.1,<2",
+  "pint>=0.26.1,<1",
+  "openpyxl>=3.1.5,<4",
+  "pkpdutils>=1.2.0,<2",
+  "httpx2>=2.13.0,<3",
+]
+
+[project.urls]
+Homepage = "https://pk-db.com"
+Documentation = "https://matthiaskoenig.github.io/pkdb/"
+Repository = "https://github.com/matthiaskoenig/pkdb"
+Issues = "https://github.com/matthiaskoenig/pkdb/issues"
+
+[project.scripts]
+pkdb = "pkdb.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1", "ruff>=0.16.8", "ty>=0.0.83"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pkdb"]
+
+[tool.ruff]
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I", "UP"]
+
+[tool.ty.environment]
+python-version = "3.14"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers"

pkdb-0.11.0/src/pkdb/__init__.py

@@ -0,0 +1,22 @@
+"""PK-DB Python client and shared scientific preparation engine."""
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.11.0"
+
+from pkdb.domain.vocabulary import Vocabulary
+from pkdb.preparation import PreparedBundle, prepare
+
+if TYPE_CHECKING:
+    from pkdb.client import Client
+
+
+def __getattr__(name):
+    if name == "Client":
+        from pkdb.client import Client
+
+        return Client
+    raise AttributeError(name)
+
+
+__all__ = ["Client", "PreparedBundle", "Vocabulary", "__version__", "prepare"]

pkdb-0.11.0/src/pkdb/__main__.py

@@ -0,0 +1,3 @@
+from pkdb.cli import main
+
+raise SystemExit(main())

pkdb-0.11.0/src/pkdb/cache.py

@@ -0,0 +1,132 @@
+"""Explicit, content-addressed offline vocabulary snapshots."""
+
+import hashlib
+import json
+import os
+import sys
+from importlib.resources import files
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from urllib.parse import urlsplit, urlunsplit
+
+from pkdb.domain.vocabulary import Vocabulary, vocabulary_hash
+
+
+def endpoint_root(value: str) -> str:
+    url = urlsplit(value)
+    if (
+        url.scheme not in {"http", "https"}
+        or not url.hostname
+        or url.username
+        or url.password
+        or url.query
+        or url.fragment
+    ):
+        raise ValueError(
+            "Endpoint must be an HTTP(S) URL without credentials, query, or fragment"
+        )
+    # Reject invalid ports here, before any request is attempted.
+    _ = url.port
+    path = url.path.rstrip("/")
+    if path.endswith(("/api/v1", "/api/v2")):
+        path = path[:-7]
+    return urlunsplit((url.scheme.lower(), url.netloc.lower(), path, "", ""))
+
+
+def vocabulary_envelope(vocabulary: Vocabulary) -> dict:
+    return {
+        "schema_version": 1,
+        "vocabulary": vocabulary.model_dump(mode="json"),
+        "vocabulary_hash": vocabulary_hash(vocabulary),
+    }
+
+
+def parse_vocabulary(value: dict) -> Vocabulary:
+    if value.get("schema_version") != 1:
+        raise ValueError("Unsupported vocabulary snapshot schema")
+    vocabulary = Vocabulary.model_validate(value.get("vocabulary"))
+    if value.get("vocabulary_hash") != vocabulary_hash(vocabulary):
+        raise ValueError("Vocabulary snapshot hash does not match its contents")
+    return vocabulary
+
+
+def atomic_json(path: Path, value: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = None
+    try:
+        with NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, delete=False
+        ) as handle:
+            temporary = Path(handle.name)
+            json.dump(value, handle, ensure_ascii=False, allow_nan=False, indent=2)
+            handle.write("\n")
+        temporary.replace(path)
+    finally:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+
+
+def load_vocabulary(path: str | Path) -> Vocabulary:
+    value = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError("Expected a vocabulary snapshot object")
+    return parse_vocabulary(value)
+
+
+def bundled_vocabulary() -> Vocabulary:
+    return parse_vocabulary(
+        json.loads(
+            files("pkdb").joinpath("data/vocabulary.json").read_text(encoding="utf-8")
+        )
+    )
+
+
+def cache_directory() -> Path:
+    if value := os.environ.get("PKDB_CACHE_DIR"):
+        return Path(value)
+    if sys.platform == "win32":
+        root = Path(os.environ.get("LOCALAPPDATA", str(Path.home() / "AppData/Local")))
+    elif sys.platform == "darwin":
+        root = Path.home() / "Library/Caches"
+    else:
+        root = Path(os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache")))
+    return root / "pkdb"
+
+
+class VocabularyCache:
+    def __init__(self, directory: str | Path | None = None):
+        self.directory = Path(directory) if directory is not None else cache_directory()
+
+    def _pointer(self, endpoint: str) -> Path:
+        key = hashlib.sha256(endpoint_root(endpoint).encode()).hexdigest()
+        return self.directory / "endpoints" / f"{key}.json"
+
+    def store(self, endpoint: str, vocabulary: Vocabulary) -> Path:
+        digest = vocabulary_hash(vocabulary)
+        path = self.directory / "snapshots" / f"{digest}.json"
+        atomic_json(path, vocabulary_envelope(vocabulary))
+        atomic_json(self._pointer(endpoint), {"vocabulary_hash": digest})
+        return path
+
+    def load(self, endpoint: str) -> Vocabulary:
+        value = json.loads(self._pointer(endpoint).read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise ValueError("Invalid vocabulary cache index")
+        digest = value.get("vocabulary_hash")
+        if (
+            not isinstance(digest, str)
+            or len(digest) != 64
+            or any(c not in "0123456789abcdef" for c in digest)
+        ):
+            raise ValueError("Invalid vocabulary cache index")
+        try:
+            vocabulary = load_vocabulary(
+                self.directory / "snapshots" / f"{digest}.json"
+            )
+        except FileNotFoundError:
+            raise ValueError(
+                "Cached vocabulary snapshot is missing; synchronize again"
+            ) from None
+        if vocabulary_hash(vocabulary) != digest:
+            raise ValueError("Vocabulary cache index does not match snapshot")
+        return vocabulary

pkdb-0.11.0/src/pkdb/cli.py

@@ -0,0 +1,158 @@
+"""Prepare, validate, and upload existing PK-DB study folders."""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from pkdb import __version__
+from pkdb.cache import VocabularyCache, atomic_json, bundled_vocabulary
+from pkdb.client import Client
+from pkdb.domain.vocabulary import Vocabulary
+from pkdb.errors import ClientError
+from pkdb.preparation import prepare, study_folders
+from pkdb.schemas.validation import StudyValidationError
+
+
+def _redact(value, token):
+    if isinstance(value, str) and token:
+        return value.replace(token, "[redacted]")
+    if isinstance(value, dict):
+        return {key: _redact(item, token) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_redact(item, token) for item in value]
+    return value
+
+
+def main(argv=None, *, client=None) -> int:
+    parser = argparse.ArgumentParser(prog="pkdb", description=__doc__)
+    parser.add_argument("--version", action="version", version=f"pkdb {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in ("prepare", "validate", "upload"):
+        command = commands.add_parser(name)
+        command.add_argument(
+            "folder", type=Path, help="Existing study folder or parent directory"
+        )
+        command.add_argument(
+            "--endpoint", "--api-url", default=os.environ.get("PKDB_ENDPOINT")
+        )
+        command.add_argument(
+            "--vocabulary", type=Path, help="Pinned vocabulary snapshot JSON"
+        )
+        command.add_argument("--cache-dir", type=Path)
+        command.add_argument(
+            "--offline",
+            action="store_true",
+            help="Never contact the server (prepare/validate only)",
+        )
+        command.add_argument(
+            "--output",
+            type=Path,
+            help="JSON output file outside the study folder (one study only)",
+        )
+    vocabulary = commands.add_parser("vocabulary")
+    actions = vocabulary.add_subparsers(dest="action", required=True)
+    sync = actions.add_parser(
+        "sync", help="Explicitly retrieve and cache the endpoint's validation rules"
+    )
+    sync.add_argument("--endpoint", default=os.environ.get("PKDB_ENDPOINT"))
+    sync.add_argument("--cache-dir", type=Path)
+    sync.add_argument(
+        "--output", type=Path, help="Portable project vocabulary lock file"
+    )
+    args = parser.parse_args(argv)
+    if args.command == "upload" and args.offline:
+        parser.error("upload requires network access; use validate --offline")
+    token = os.environ.get("PKDB_API_KEY")
+    cache = VocabularyCache(args.cache_dir)
+    try:
+        if args.command == "vocabulary":
+            with Client(
+                args.endpoint, api_key=token, transport=client, cache=cache
+            ) as api:
+                snapshot = api.vocabulary()
+                if args.output:
+                    snapshot.save(args.output)
+                from pkdb.domain.vocabulary import vocabulary_hash
+
+                print(
+                    json.dumps(
+                        {
+                            "ok": True,
+                            "vocabulary_version": snapshot.version,
+                            "vocabulary_hash": vocabulary_hash(snapshot),
+                        }
+                    )
+                )
+            return 0
+        folders = study_folders(args.folder)
+        if args.output:
+            if len(folders) != 1:
+                raise ValueError("--output requires a single study folder")
+            if args.output.resolve().is_relative_to(folders[0].resolve()):
+                raise ValueError(
+                    "Write --output outside the study folder to keep source files unchanged"
+                )
+        if args.vocabulary:
+            snapshot = Vocabulary.load(args.vocabulary)
+        elif args.endpoint:
+            try:
+                snapshot = cache.load(args.endpoint)
+            except FileNotFoundError:
+                snapshot = bundled_vocabulary()
+        else:
+            snapshot = bundled_vocabulary()
+        if args.command == "upload" and (not args.endpoint or not token):
+            raise ValueError("Upload requires an endpoint and PKDB_API_KEY")
+    except (ValueError, OSError, ClientError) as error:
+        print(
+            json.dumps(_redact({"ok": False, "error": str(error)}, token)),
+            file=sys.stderr,
+        )
+        return 1
+    failed = False
+    for folder in folders:
+        result = {"path": str(folder), "ok": False}
+        try:
+            prepared = prepare(folder, vocabulary=snapshot)
+            result.update(sid=prepared.study.sid)
+            if args.command == "upload":
+                with Client(
+                    args.endpoint, api_key=token, transport=client, cache=cache
+                ) as api:
+                    result.update(api.upload(prepared).model_dump(mode="json"))
+            elif args.command == "prepare":
+                result.update(prepared.model_dump())
+            else:
+                result.update(
+                    report=prepared.report.model_dump(mode="json"),
+                    vocabulary_version=prepared.prepared.vocabulary_version,
+                    vocabulary_hash=prepared.vocabulary_hash,
+                    processing_version=prepared.prepared.processing_version,
+                )
+            result["ok"] = True
+        except StudyValidationError as error:
+            result.update(
+                error="Study validation failed",
+                report=error.report.model_dump(mode="json"),
+            )
+        except ClientError as error:
+            result.update(error=str(error), status_code=error.status_code)
+            if error.report:
+                result["report"] = error.report.model_dump(mode="json")
+        except (ValueError, OSError) as error:
+            result["error"] = str(error)
+        result = _redact(result, token)
+        if args.output:
+            try:
+                atomic_json(args.output, result)
+            except OSError as error:
+                result.update(ok=False, error=str(error))
+        print(json.dumps(result, ensure_ascii=False, allow_nan=False), flush=True)
+        failed |= not result["ok"]
+    return int(failed)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())