dcccpy 0.1.2__tar.gz

dcccpy-0.1.2/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include src/dcccpy/vendor *

dcccpy-0.1.2/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: dcccpy
+Version: 0.1.2
+Summary: Python wrapper for the DCCCcore PET biomarker command-line tool
+Author: DCCCSlicer contributors
+License-Expression: CC-BY-NC-ND-4.0
+Project-URL: Homepage, https://github.com/tctco/DCCCSlicer
+Project-URL: Repository, https://github.com/tctco/DCCCSlicer
+Project-URL: Issues, https://github.com/tctco/DCCCSlicer/issues
+Keywords: PET,neuroimaging,centiloid,DCCC,DCCCSlicer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: nibabel>=5
+Provides-Extra: linux-runtime
+Requires-Dist: dcccpy-linux-runtime==0.1.0; extra == "linux-runtime"
+
+# dcccpy
+
+`dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
+DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
+small Python API for running common PET biomarker workflows.
+
+## Install
+
+The default package is slim:
+
+```bash
+pip install dcccpy
+```
+
+The first call downloads the matching `DCCCcore` release package into the local
+user cache if no native runtime is otherwise available. The slim package also
+installs `nibabel` for image loading and nibabel-style image inputs.
+
+For Linux users who prefer `pip install` to include the native runtime and avoid
+first-run download:
+
+```bash
+pip install "dcccpy[linux-runtime]"
+```
+
+## Python API
+
+```python
+import dcccpy
+
+result = dcccpy.centiloid("amyloid_pet.nii", skip_normalization=True)
+print(result.metrics)
+print(result.output)
+```
+
+The `output` argument is optional for single-image Python calls. When omitted,
+`dcccpy` creates a temporary output NIfTI path and returns it in the result.
+Relative input and output paths are resolved from the current Python working
+directory before `DCCCcore` is invoked.
+
+```python
+result = dcccpy.centiloid("amyloid_pet.nii")
+print(result.output)           # temporary output path
+print(result.metrics.get("fbp"))
+```
+
+The wrapper accepts nibabel-style image objects with `to_filename()`:
+
+```python
+import nibabel as nib
+import dcccpy
+
+image = nib.load("amyloid_pet.nii.gz")
+result = dcccpy.centiloid(image, skip_normalization=True)
+output_image = result.load_output()
+```
+
+Common helpers mirror `DCCCcore` subcommands:
+
+```python
+dcccpy.centiloid("amyloid.nii", suvr=True)
+dcccpy.centaurz("tau.nii", report_detailed_regions=True)
+dcccpy.fillstates("fdg.nii", tracer="fdg")
+dcccpy.normalize("pet.nii", iterative=True)
+dcccpy.run(["centiloid", "--input", "a.nii", "--output", "b.nii"])
+```
+
+Each helper returns `DCCCResult` with:
+
+- `returncode`
+- `stdout` / `stderr`
+- `output`
+- `metrics`, parsed from numeric lines in stdout
+- `load_output()`, which loads the output with nibabel
+
+## Command Line
+
+`dcccpy` also forwards raw arguments to `DCCCcore`:
+
+```bash
+dcccpy --help
+dcccpy centiloid --input amyloid_pet.nii --output result.nii
+```
+
+## Runtime lookup
+
+At runtime, `dcccpy` looks for `DCCCcore` in this order:
+
+1. `DCCCPY_DCCCCORE` environment variable.
+2. A vendored binary inside the installed `dcccpy` wheel.
+3. A binary from `dcccpy-linux-runtime`, installed by `dcccpy[linux-runtime]`.
+4. The local dcccpy cache populated by automatic download.
+5. `DCCCcore` on `PATH`.
+6. Automatic download from GitHub releases, unless disabled.
+
+Useful environment variables:
+
+- `DCCCPY_DCCCCORE`: exact path to a `DCCCcore` executable.
+- `DCCCPY_AUTO_DOWNLOAD=0`: disable first-run automatic download.
+- `DCCCPY_CACHE_DIR`: override the runtime cache directory.
+- `DCCCPY_RELEASE_REPO`: override the GitHub release repository.
+- `DCCCPY_DCCCCORE_URL`: override the release asset URL.
+
+## Runtime Packaging
+
+Release wheels should vendor the matching `DCCCcore` runtime tree before build:
+
+```bash
+python scripts/vendor_dccccore.py --version 4.2.3 --release-platform ubuntu-latest-x64
+python -m build --wheel
+```
+
+The source tree intentionally does not commit the vendored runtime because it
+contains large ONNX model and NIfTI runtime assets.
+
+The preferred distribution layout is:
+
+- `dcccpy`: slim Python package with nibabel; downloads runtime on first use.
+- `dcccpy-linux-runtime`: optional Linux runtime wheel.
+- `dcccpy[linux-runtime]`: installs both packages.
+
+## Packaging note
+
+The Linux `DCCCcore-4.2.3-ubuntu-latest-x64.zip` release asset contains the
+native executable, `libtbb`, ONNX registration/decoupling models, configuration
+files, and NIfTI template/mask assets. That full runtime is the correct unit to
+vendor for a wheel that works immediately after `pip install dcccpy`.
+
+The full Linux runtime wheel is about 167 MB for version 4.2.3, so a public
+PyPI upload may require a file size limit increase unless a future release
+splits a smaller runtime profile from the full `DCCCcore` package.

dcccpy-0.1.2/README.md

@@ -0,0 +1,131 @@
+# dcccpy
+
+`dcccpy` is a Python wrapper for the `DCCCcore` command-line tool from
+DCCCSlicer. It keeps the native C++ core as the execution engine and provides a
+small Python API for running common PET biomarker workflows.
+
+## Install
+
+The default package is slim:
+
+```bash
+pip install dcccpy
+```
+
+The first call downloads the matching `DCCCcore` release package into the local
+user cache if no native runtime is otherwise available. The slim package also
+installs `nibabel` for image loading and nibabel-style image inputs.
+
+For Linux users who prefer `pip install` to include the native runtime and avoid
+first-run download:
+
+```bash
+pip install "dcccpy[linux-runtime]"
+```
+
+## Python API
+
+```python
+import dcccpy
+
+result = dcccpy.centiloid("amyloid_pet.nii", skip_normalization=True)
+print(result.metrics)
+print(result.output)
+```
+
+The `output` argument is optional for single-image Python calls. When omitted,
+`dcccpy` creates a temporary output NIfTI path and returns it in the result.
+Relative input and output paths are resolved from the current Python working
+directory before `DCCCcore` is invoked.
+
+```python
+result = dcccpy.centiloid("amyloid_pet.nii")
+print(result.output)           # temporary output path
+print(result.metrics.get("fbp"))
+```
+
+The wrapper accepts nibabel-style image objects with `to_filename()`:
+
+```python
+import nibabel as nib
+import dcccpy
+
+image = nib.load("amyloid_pet.nii.gz")
+result = dcccpy.centiloid(image, skip_normalization=True)
+output_image = result.load_output()
+```
+
+Common helpers mirror `DCCCcore` subcommands:
+
+```python
+dcccpy.centiloid("amyloid.nii", suvr=True)
+dcccpy.centaurz("tau.nii", report_detailed_regions=True)
+dcccpy.fillstates("fdg.nii", tracer="fdg")
+dcccpy.normalize("pet.nii", iterative=True)
+dcccpy.run(["centiloid", "--input", "a.nii", "--output", "b.nii"])
+```
+
+Each helper returns `DCCCResult` with:
+
+- `returncode`
+- `stdout` / `stderr`
+- `output`
+- `metrics`, parsed from numeric lines in stdout
+- `load_output()`, which loads the output with nibabel
+
+## Command Line
+
+`dcccpy` also forwards raw arguments to `DCCCcore`:
+
+```bash
+dcccpy --help
+dcccpy centiloid --input amyloid_pet.nii --output result.nii
+```
+
+## Runtime lookup
+
+At runtime, `dcccpy` looks for `DCCCcore` in this order:
+
+1. `DCCCPY_DCCCCORE` environment variable.
+2. A vendored binary inside the installed `dcccpy` wheel.
+3. A binary from `dcccpy-linux-runtime`, installed by `dcccpy[linux-runtime]`.
+4. The local dcccpy cache populated by automatic download.
+5. `DCCCcore` on `PATH`.
+6. Automatic download from GitHub releases, unless disabled.
+
+Useful environment variables:
+
+- `DCCCPY_DCCCCORE`: exact path to a `DCCCcore` executable.
+- `DCCCPY_AUTO_DOWNLOAD=0`: disable first-run automatic download.
+- `DCCCPY_CACHE_DIR`: override the runtime cache directory.
+- `DCCCPY_RELEASE_REPO`: override the GitHub release repository.
+- `DCCCPY_DCCCCORE_URL`: override the release asset URL.
+
+## Runtime Packaging
+
+Release wheels should vendor the matching `DCCCcore` runtime tree before build:
+
+```bash
+python scripts/vendor_dccccore.py --version 4.2.3 --release-platform ubuntu-latest-x64
+python -m build --wheel
+```
+
+The source tree intentionally does not commit the vendored runtime because it
+contains large ONNX model and NIfTI runtime assets.
+
+The preferred distribution layout is:
+
+- `dcccpy`: slim Python package with nibabel; downloads runtime on first use.
+- `dcccpy-linux-runtime`: optional Linux runtime wheel.
+- `dcccpy[linux-runtime]`: installs both packages.
+
+## Packaging note
+
+The Linux `DCCCcore-4.2.3-ubuntu-latest-x64.zip` release asset contains the
+native executable, `libtbb`, ONNX registration/decoupling models, configuration
+files, and NIfTI template/mask assets. That full runtime is the correct unit to
+vendor for a wheel that works immediately after `pip install dcccpy`.
+
+The full Linux runtime wheel is about 167 MB for version 4.2.3, so a public
+PyPI upload may require a file size limit increase unless a future release
+splits a smaller runtime profile from the full `DCCCcore` package.

dcccpy-0.1.2/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dcccpy"
+version = "0.1.2"
+description = "Python wrapper for the DCCCcore PET biomarker command-line tool"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "CC-BY-NC-ND-4.0"
+authors = [
+  { name = "DCCCSlicer contributors" }
+]
+dependencies = [
+  "nibabel>=5",
+]
+keywords = ["PET", "neuroimaging", "centiloid", "DCCC", "DCCCSlicer"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+[project.urls]
+Homepage = "https://github.com/tctco/DCCCSlicer"
+Repository = "https://github.com/tctco/DCCCSlicer"
+Issues = "https://github.com/tctco/DCCCSlicer/issues"
+
+[project.optional-dependencies]
+linux-runtime = ["dcccpy-linux-runtime==0.1.0"]
+
+[project.scripts]
+dcccpy = "dcccpy.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dcccpy = ["py.typed", "vendor/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dcccpy-0.1.2/setup.cfg

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

dcccpy-0.1.2/setup.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+from setuptools import setup
+
+
+try:
+    from wheel.bdist_wheel import bdist_wheel
+except Exception:  # pragma: no cover - wheel is provided by build-system.requires
+    bdist_wheel = None
+
+
+if bdist_wheel is not None:
+    def has_vendored_runtime() -> bool:
+        vendor_root = Path(__file__).resolve().parent / "src" / "dcccpy" / "vendor" / "dccccore"
+        return vendor_root.exists() and any(vendor_root.rglob("DCCCcore*"))
+
+
+    class BinaryWheel(bdist_wheel):
+        """Mark wheels as platform-specific when vendored DCCCcore is present."""
+
+        def finalize_options(self):
+            super().finalize_options()
+            if has_vendored_runtime():
+                self.root_is_pure = False
+
+        def get_tag(self):
+            if not has_vendored_runtime():
+                return super().get_tag()
+            _, _, platform_tag = super().get_tag()
+            return "py3", "none", platform_tag
+
+    setup(cmdclass={"bdist_wheel": BinaryWheel})
+else:
+    setup()

dcccpy-0.1.2/src/dcccpy/__init__.py

@@ -0,0 +1,42 @@
+"""Python wrapper for the native DCCCcore executable."""
+
+from .core import (
+    DCCCResult,
+    adad,
+    abetaindex,
+    abetaload,
+    adni_pet_core,
+    centaur,
+    centaurz,
+    centiloid,
+    dccccore_path,
+    fillstates,
+    normalize,
+    parse_metrics,
+    rigid,
+    run,
+    suvr,
+)
+from .runtime import DCCCCORE_VERSION, DCCCcoreDownloadError, DCCCcoreNotFoundError, download_dccccore
+
+__all__ = [
+    "DCCCResult",
+    "DCCCCORE_VERSION",
+    "DCCCcoreDownloadError",
+    "DCCCcoreNotFoundError",
+    "adad",
+    "abetaindex",
+    "abetaload",
+    "adni_pet_core",
+    "centaur",
+    "centaurz",
+    "centiloid",
+    "dccccore_path",
+    "download_dccccore",
+    "fillstates",
+    "normalize",
+    "parse_metrics",
+    "rigid",
+    "run",
+    "suvr",
+]

dcccpy-0.1.2/src/dcccpy/cli.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import sys
+
+from .core import run
+from .runtime import DCCCcoreDownloadError, DCCCcoreNotFoundError
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        result = run(args, check=False)
+    except (DCCCcoreDownloadError, DCCCcoreNotFoundError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 127
+
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, file=sys.stderr, end="")
+    return result.returncode