sbml4humans 0.6.1__tar.gz

sbml4humans-0.6.1/.gitignore

@@ -0,0 +1,28 @@
+# python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# node
+node_modules/
+frontend/dist/
+# the build of the frontend which ships with the python package (npm run build:package)
+backend/sbml4humans/resources/frontend/
+frontend/playwright-report/
+frontend/test-results/
+
+# the documentation site built by zensical
+site/
+
+# editors, operating system
+.idea/
+.vscode/
+*~
+.DS_Store
+
+# brainstorming sessions of the superpowers plugin
+.superpowers/

sbml4humans-0.6.1/.python-version

@@ -0,0 +1 @@
+3.14

sbml4humans-0.6.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: sbml4humans
+Version: 0.6.1
+Summary: Interactive, human readable reports of SBML models, in the browser and from python.
+Project-URL: Homepage, https://sbml4humans.de
+Project-URL: Documentation, https://matthiaskoenig.github.io/sbml4humans/
+Project-URL: Repository, https://github.com/matthiaskoenig/sbml4humans
+Author-email: Matthias König <konigmatt@googlemail.com>
+License-Expression: MIT
+Keywords: COMBINE archive,SBML,computational modelling,report,systems biology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.14
+Requires-Dist: fastapi>=0.141.1
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: lxml>=6.0.0
+Requires-Dist: numpy>=2.2.2
+Requires-Dist: pint>=0.25.3
+Requires-Dist: platformdirs>=4.4
+Requires-Dist: pydantic>=2.12
+Requires-Dist: pymetadata>=0.6.2
+Requires-Dist: python-libsbml>=5.21.1
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: uvicorn>=0.52.4
+Description-Content-Type: text/markdown
+
+# SBML4Humans
+
+SBML4Humans creates interactive, human readable reports of [SBML](https://sbml.org) models: one table per element type, a search over everything, and an inspector which follows every reference between the objects of a model, for SBML core and the packages comp, fbc, qual and distrib.
+
+The package opens the report of a file of your machine in the browser. The file is read by a local server and never leaves the machine:
+
+```python
+from sbml4humans import show
+
+show("model.xml")
+```
+
+```bash
+sbml4humans model.xml
+```
+
+The web application is at [sbml4humans.de](https://sbml4humans.de), the documentation at [matthiaskoenig.github.io/sbml4humans](https://matthiaskoenig.github.io/sbml4humans/), with [Reports from python](https://matthiaskoenig.github.io/sbml4humans/python/) for this package, and the source at [github.com/matthiaskoenig/sbml4humans](https://github.com/matthiaskoenig/sbml4humans).
+
+SBML4Humans is released under the MIT license. If you use it in your work, please cite it as the [documentation](https://matthiaskoenig.github.io/sbml4humans/#how-to-cite) describes.

sbml4humans-0.6.1/README.md

@@ -0,0 +1,19 @@
+# SBML4Humans
+
+SBML4Humans creates interactive, human readable reports of [SBML](https://sbml.org) models: one table per element type, a search over everything, and an inspector which follows every reference between the objects of a model, for SBML core and the packages comp, fbc, qual and distrib.
+
+The package opens the report of a file of your machine in the browser. The file is read by a local server and never leaves the machine:
+
+```python
+from sbml4humans import show
+
+show("model.xml")
+```
+
+```bash
+sbml4humans model.xml
+```
+
+The web application is at [sbml4humans.de](https://sbml4humans.de), the documentation at [matthiaskoenig.github.io/sbml4humans](https://matthiaskoenig.github.io/sbml4humans/), with [Reports from python](https://matthiaskoenig.github.io/sbml4humans/python/) for this package, and the source at [github.com/matthiaskoenig/sbml4humans](https://github.com/matthiaskoenig/sbml4humans).
+
+SBML4Humans is released under the MIT license. If you use it in your work, please cite it as the [documentation](https://matthiaskoenig.github.io/sbml4humans/#how-to-cite) describes.

sbml4humans-0.6.1/pyproject.toml

@@ -0,0 +1,148 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sbml4humans"
+dynamic = ["version"]
+description = "Interactive, human readable reports of SBML models, in the browser and from python."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+keywords = ["SBML", "systems biology", "computational modelling", "report", "COMBINE archive"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+authors = [
+    {name = "Matthias König", email = "konigmatt@googlemail.com"},
+]
+dependencies = [
+    # the report: libsbml reads the models, lxml renders the math with xslt,
+    # pint formats the units, pymetadata handles combine archives and annotations
+    "python-libsbml>=5.21.1",
+    "lxml>=6.0.0",
+    "numpy>=2.2.2",
+    "pint>=0.25.3",
+    "pymetadata>=0.6.2",
+    "pydantic>=2.12",
+    # the http api
+    "fastapi>=0.141.1",
+    "uvicorn>=0.52.4",
+    "python-multipart>=0.0.32",
+    # downloading models from urls, and the client of the local server of `show`
+    "httpx>=0.28.1",
+    # the state file of the local server of `show`, in the cache directory of the user
+    "platformdirs>=4.4",
+]
+
+[project.scripts]
+sbml4humans = "sbml4humans.cli:main"
+
+[project.urls]
+Homepage = "https://sbml4humans.de"
+Documentation = "https://matthiaskoenig.github.io/sbml4humans/"
+Repository = "https://github.com/matthiaskoenig/sbml4humans"
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.5.1",
+    "pytest>=9.1.1",
+    "ruff>=0.16.6",
+    "ty>=0.0.78",
+    "zensical>=0.0.60",
+]
+
+[tool.hatch.version]
+path = "sbml4humans/__init__.py"
+
+[tool.bumpversion]
+# the version of sbml4humans is the version of the backend package, the frontend
+# follows it. Run from this directory: `uv run bump-my-version bump minor`.
+# No tag: the bump is merged into develop with squash or rebase, which rewrites
+# the commit, so the tag is created on develop after the merge (see docs/development.md)
+current_version = "0.6.1"
+commit = true
+tag = false
+tag_name = "{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+message = "Bump version: {current_version} → {new_version}"
+
+[[tool.bumpversion.files]]
+filename = "sbml4humans/__init__.py"
+
+[[tool.bumpversion.files]]
+filename = "../frontend/package.json"
+search = "\"version\": \"{current_version}\""
+replace = "\"version\": \"{new_version}\""
+
+# the lock carries the version of the package twice, at its root and as the entry of the
+# package itself; the search names the package, so that a dependency which shares the number
+# of a version is left alone
+[[tool.bumpversion.files]]
+filename = "../frontend/package-lock.json"
+search = "\"name\": \"sbml4humans\",\n  \"version\": \"{current_version}\""
+replace = "\"name\": \"sbml4humans\",\n  \"version\": \"{new_version}\""
+
+[[tool.bumpversion.files]]
+filename = "../frontend/package-lock.json"
+search = "\"name\": \"sbml4humans\",\n      \"version\": \"{current_version}\""
+replace = "\"name\": \"sbml4humans\",\n      \"version\": \"{new_version}\""
+
+# the frontend which `sbml4humans.show` serves is built into the package before the wheel
+# (`npm run build:package` in frontend/). It is git ignored, which hatch takes as excluded,
+# so it is named as an artifact of the build.
+[tool.hatch.build]
+artifacts = ["sbml4humans/resources/frontend/**"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["sbml4humans"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 88
+target-version = "py314"
+
+[tool.ruff.lint]
+# Pyflakes (`F`) and a subset of pycodestyle (`E`), plus:
+#   W    pycodestyle warnings
+#   I    import sorting
+#   D    docstrings (google convention, see [tool.ruff.lint.pydocstyle])
+#   UP   pyupgrade, keeps the code on current python syntax
+#   B    bugbear, likely bugs and design problems
+#   C4   comprehensions
+#   SIM  simplifications
+#   RET  return statements
+#   G    logging format, lazy `%s` instead of f-strings
+#   PIE  misc lints
+#   RUF  ruff specific rules
+select = [
+    "E4", "E7", "E9", "F", "W", "I", "D", "UP", "B", "C4", "SIM", "RET", "G", "PIE", "RUF",
+]
+ignore = [
+    # names such as `König` are not ambiguous unicode, they are german
+    "RUF001",
+    "RUF002",
+    "RUF003",
+]
+
+[tool.ruff.lint.isort]
+lines-after-imports = 2
+known-first-party = ["sbml4humans"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ty.src]
+include = ["sbml4humans", "tests"]
+
+[tool.ty.terminal]
+# warnings are failures: keep the codebase free of any diagnostic
+error-on-warning = true

sbml4humans-0.6.1/sbml4humans/__init__.py

@@ -0,0 +1,16 @@
+"""sbml4humans, the human readable report of SBML models.
+
+`sbml4humans.sbmlinfo` creates the report of an SBML document, `sbml4humans.api`
+serves it over http for the sbml4humans frontend, and `sbml4humans.show` opens
+the report of a local file in the browser:
+
+    from sbml4humans import show
+    show("model.xml")
+"""
+
+__version__ = "0.6.1"
+
+from sbml4humans.viewer import show, stop
+
+
+__all__ = ["__version__", "show", "stop"]

sbml4humans-0.6.1/sbml4humans/annotations.py

@@ -0,0 +1,54 @@
+"""Resolution of annotation resources.
+
+Used by the frontend to display information (label, description, cross
+references) for the identifiers in the annotations of a model.
+"""
+
+from typing import Any
+
+from pymetadata.core.annotation import RDFAnnotation, RDFAnnotationData
+from pymetadata.core.miriam import BQB
+
+
+# fields the report shows as text; the Ontology Lookup Service reports a missing
+# definition as an empty list, which ends up in the description of the term
+TEXT_FIELDS = (
+    "resource_normalized",
+    "collection",
+    "term",
+    "label",
+    "description",
+    "url",
+)
+
+# fields the report shows as messages; a failing request is collected as the error itself
+MESSAGE_FIELDS = ("errors", "warnings")
+
+
+def _text(value: Any) -> str | None:
+    """Convert a field to text; a field which carries no text has no value."""
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _messages(value: Any) -> list[str]:
+    """Convert a field to a list of messages."""
+    if not isinstance(value, list):
+        return []
+    return [str(message) for message in value]
+
+
+def annotation_info(resource: str) -> dict[str, Any]:
+    """Resolve the information of an annotation resource.
+
+    Args:
+        resource: identifier of the resource (url or MIRIAM urn).
+    """
+    annotation = RDFAnnotation(qualifier=BQB.IS, resource=resource)
+    data = RDFAnnotationData(annotation=annotation).to_dict()
+    for field in TEXT_FIELDS:
+        data[field] = _text(data.get(field))
+    for field in MESSAGE_FIELDS:
+        data[field] = _messages(data.get(field))
+    return data

sbml4humans-0.6.1/sbml4humans/api.py

@@ -0,0 +1,207 @@
+"""The http api of sbml4humans.
+
+Served with `uvicorn sbml4humans.api:api`.
+
+Error contract: the frontend expects every response with status 200. Failures
+are reported in the body as `{"errors": [message, traceback], "warnings": [],
+"info": {...}}`, with the query parameters of the request as `info`.
+
+A report endpoint returns its `ReportResponse` as it is. FastAPI takes an
+instance of the response model without validating it again and writes its JSON
+in one pass of pydantic, which applies the configuration of the model: camelCase
+keys and an infinite value or a value which is not a number as the strings
+`"Infinity"`, `"-Infinity"` and `"NaN"`.
+"""
+
+import logging
+import traceback
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+import httpx
+from fastapi import FastAPI, Request, UploadFile
+from fastapi.concurrency import run_in_threadpool
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import RequestResponseEndpoint
+from starlette.responses import Response
+
+from sbml4humans import __version__
+from sbml4humans.annotations import annotation_info
+from sbml4humans.examples import ExampleMetaData, load_examples
+from sbml4humans.model import ReportResponse
+from sbml4humans.report import report_for_bytes, report_for_path
+
+
+logger = logging.getLogger(__name__)
+
+DOWNLOAD_TIMEOUT = 60.0  # [s]
+
+
+class ExampleNotFoundError(KeyError):
+    """Raised for an unknown example id."""
+
+    def __init__(self, example_id: str) -> None:
+        """Create the error for the unknown example id."""
+        super().__init__(example_id)
+        self.example_id = example_id
+
+    def __str__(self) -> str:
+        """Message for the frontend."""
+        return f"example for id does not exist '{self.example_id}'"
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI) -> AsyncIterator[None]:
+    """Read the examples on startup, so that the first requests are fast."""
+    load_examples()
+    yield
+
+
+api = FastAPI(
+    title="sbml4humans",
+    description="sbml4humans backend api",
+    version=__version__,
+    terms_of_service="https://github.com/matthiaskoenig/sbml4humans/blob/main/frontend/privacy_notice.md",
+    contact={
+        "name": "Matthias König",
+        "url": "https://livermetabolism.com",
+        "email": "konigmatt@googlemail.com",
+    },
+    license_info={
+        "name": "MIT",
+        "url": "https://opensource.org/license/MIT",
+    },
+    openapi_tags=[
+        {"name": "examples", "description": "Query examples."},
+        {"name": "reports", "description": "Create report data."},
+        {"name": "metadata", "description": "Query metadata."},
+    ],
+    lifespan=lifespan,
+)
+
+
+def error_response(request: Request, exc: Exception) -> JSONResponse:
+    """Report an exception to the frontend in the body of a 200 response."""
+    logger.error("%s %s failed: %s", request.method, request.url.path, exc)
+    return JSONResponse(
+        status_code=200,
+        content={
+            "errors": [
+                str(exc),
+                "".join(traceback.format_exception(exc)),
+            ],
+            "warnings": [],
+            "info": dict(request.query_params),
+        },
+    )
+
+
+def add_error_contract(app: FastAPI) -> None:
+    """Make every failure of the app an error response with status 200.
+
+    Starlette's own exception handling runs in the outermost
+    `ServerErrorMiddleware`, outside a `CORSMiddleware`, so its responses carry
+    no CORS headers. The middleware of the contract has to be added before the
+    `CORSMiddleware`, which makes it the innermost one (Starlette wraps
+    middleware in the order they are added, most recent outermost), so the
+    `CORSMiddleware` wraps it and adds its headers to the error response as it
+    would to any other response.
+    """
+
+    @app.middleware("http")
+    async def error_response_middleware(
+        request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        """Turn an exception of any endpoint into an error response."""
+        try:
+            return await call_next(request)
+        except Exception as exc:
+            return error_response(request, exc)
+
+    # Safety net for exceptions raised outside the middleware stack above, for
+    # example during request parsing before `error_response_middleware` runs.
+    app.add_exception_handler(Exception, error_response)
+    app.add_exception_handler(RequestValidationError, error_response)
+
+
+add_error_contract(api)
+api.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def download(url: str) -> bytes:
+    """Download the content behind url."""
+    response = httpx.get(url, follow_redirects=True, timeout=DOWNLOAD_TIMEOUT)
+    response.raise_for_status()
+    return response.content
+
+
+@api.get("/api/examples", tags=["examples"])
+def examples() -> dict[str, list[dict[str, Any]]]:
+    """List the metadata of all examples."""
+    return {
+        "examples": [
+            example.model_dump(exclude={"file"}) for example in load_examples().values()
+        ]
+    }
+
+
+@api.get(
+    "/api/examples/{example_id}",
+    tags=["examples"],
+    response_model=ReportResponse,
+    response_model_by_alias=True,
+)
+def example(example_id: str) -> ReportResponse:
+    """Create the report data of an example."""
+    example: ExampleMetaData | None = load_examples().get(example_id)
+    if example is None:
+        raise ExampleNotFoundError(example_id)
+    return report_for_path(example.file, trusted=True)
+
+
+@api.post(
+    "/api/file",
+    tags=["reports"],
+    response_model=ReportResponse,
+    response_model_by_alias=True,
+)
+def report_from_file(source: UploadFile) -> ReportResponse:
+    """Create the report data of an uploaded SBML file or COMBINE archive."""
+    return report_for_bytes(source.file.read())
+
+
+@api.get(
+    "/api/url",
+    tags=["reports"],
+    response_model=ReportResponse,
+    response_model_by_alias=True,
+)
+def report_from_url(url: str) -> ReportResponse:
+    """Create the report data of an SBML file or COMBINE archive behind a url."""
+    return report_for_bytes(download(url))
+
+
+@api.post(
+    "/api/content",
+    tags=["reports"],
+    response_model=ReportResponse,
+    response_model_by_alias=True,
+)
+async def report_from_content(request: Request) -> ReportResponse:
+    """Create the report data of the SBML content in the request body."""
+    content = await request.body()
+    return await run_in_threadpool(report_for_bytes, content)
+
+
+@api.get("/api/annotation_resource", tags=["metadata"])
+def annotation_resource(resource: str) -> dict[str, Any]:
+    """Resolve the information of an annotation resource (url or MIRIAM urn)."""
+    return annotation_info(resource)

sbml4humans-0.6.1/sbml4humans/cli.py

@@ -0,0 +1,46 @@
+"""The command `sbml4humans`: the report of a local file in the browser."""
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from sbml4humans import __version__
+from sbml4humans.viewer import show, stop
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command and return its exit code."""
+    parser = argparse.ArgumentParser(
+        prog="sbml4humans",
+        description=(
+            "Open the report of an SBML file or COMBINE archive in the browser. The "
+            "file is read by a local server and never leaves this machine."
+        ),
+    )
+    parser.add_argument("path", nargs="?", help="SBML file or COMBINE archive")
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="print the url of the report without opening it",
+    )
+    parser.add_argument("--stop", action="store_true", help="end the local server")
+    parser.add_argument("--version", action="version", version=__version__)
+    arguments = parser.parse_args(argv)
+
+    if arguments.stop:
+        stopped = stop()
+        print("the local server stopped" if stopped else "no local server is running")
+        return 0
+    if arguments.path is None:
+        parser.error("the path of an SBML file or COMBINE archive is required")
+    try:
+        url = show(arguments.path, open_browser=not arguments.no_browser)
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"sbml4humans: {error}", file=sys.stderr)
+        return 1
+    print(url)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())