eosframes 1.1.0__py3-none-any.whl

eosframes/exceptions.py

@@ -0,0 +1,20 @@
+"""Custom exceptions for the ``eosframes`` library."""
+
+
+class EosframesError(Exception):
+    """Sole exception type raised by ``eosframes``.
+
+    Every validation failure inside the library — naming-convention
+    violations, model-ID / version mismatches, attempts to overwrite an
+    existing output, malformed scaler JSONs, HTTP failures from the model
+    hub — surfaces as ``EosframesError``. Users only need to catch this one
+    exception class to handle any library-level problem.
+
+    Examples
+    --------
+    >>> from eosframes import EosframesError, write_csv
+    >>> try:
+    ...     write_csv(df, "results.csv")  # missing model ID in path
+    ... except EosframesError as e:
+    ...     print(f"eosframes refused the write: {e}")
+    """

eosframes/hub.py

@@ -0,0 +1,152 @@
+"""Fetch Ersilia model information from GitHub.
+
+This module reaches out to ``raw.githubusercontent.com/ersilia-os/<model_id>``
+to retrieve metadata (``fetch_metadata``) and per-version column
+definitions (``fetch_columns``). ``fetch_columns`` first tries the
+semver tag for *version* (``v<N>`` → ``v<N>.0.0``), then falls back to
+``main``; ``fetch_metadata`` fetches from ``main`` directly.
+
+All HTTP calls have a 15 s timeout. Failures are surfaced as
+:class:`~eosframes.EosframesError` with a hint pointing at the
+``ersilia-os`` repo URL.
+"""
+
+import io
+import json
+import re
+
+import pandas as pd
+import requests
+
+from .exceptions import EosframesError
+from .logger import get_logger
+
+_GITHUB_RAW = "https://raw.githubusercontent.com/ersilia-os/{model_id}/{ref}/{filename}"
+_METADATA_CANDIDATES = ["metadata.json", "metadata.yml", "metadata.yaml"]
+_RUN_COLUMNS_PATH = "model/framework/columns/run_columns.csv"
+
+
+def _version_to_ref(version: str) -> str:
+    """Map a short version string ``v<N>`` to its semver git tag ``v<N>.0.0``.
+
+    Anything that doesn't match the short form is returned unchanged,
+    so callers can pass already-resolved refs (full SHAs, branch
+    names) without surprise rewriting.
+    """
+    m = re.match(r"^v(\d+)$", version)
+    if m:
+        return f"v{m.group(1)}.0.0"
+    return version
+
+
+def _raw_url(model_id: str, ref: str, filename: str) -> str:
+    """Build a ``raw.githubusercontent.com`` URL for *filename* at *ref*."""
+    return _GITHUB_RAW.format(model_id=model_id, ref=ref, filename=filename)
+
+
+def fetch_metadata(model_id: str) -> dict:
+    """Fetch metadata for an Ersilia model from GitHub.
+
+    Probes ``main`` for ``metadata.json``, ``metadata.yml`` and
+    ``metadata.yaml`` in that order, returning the first one that
+    responds with HTTP 200. YAML files require ``pyyaml`` to be
+    installed.
+
+    Parameters
+    ----------
+    model_id : str
+        Ersilia model identifier.
+
+    Returns
+    -------
+    dict
+        Raw metadata as a dictionary.
+
+    Raises
+    ------
+    EosframesError
+        If none of the candidate metadata files exist on the model's
+        ``main`` branch, or if a YAML metadata file is found but
+        ``pyyaml`` is not installed.
+    """
+    logger = get_logger()
+    for filename in _METADATA_CANDIDATES:
+        url = _raw_url(model_id, "main", filename)
+        logger.debug("GET %s", url)
+        resp = requests.get(url, timeout=15)
+        if resp.status_code == 200:
+            logger.info("Fetched metadata for %s from %s", model_id, filename)
+            if filename.endswith(".json"):
+                return json.loads(resp.text)
+            try:
+                import yaml
+
+                return yaml.safe_load(resp.text)
+            except ImportError as exc:
+                raise EosframesError(
+                    f"Model '{model_id}' has a YAML metadata file but 'pyyaml' is not "
+                    "installed. Install it with: pip install pyyaml"
+                ) from exc
+        logger.debug(
+            "Metadata candidate %s returned HTTP %d for %s",
+            filename,
+            resp.status_code,
+            model_id,
+        )
+    raise EosframesError(
+        f"Could not fetch metadata for model '{model_id}'. "
+        f"Make sure the repo exists at https://github.com/ersilia-os/{model_id}"
+    )
+
+
+def fetch_columns(model_id: str, version: str) -> pd.DataFrame:
+    """Fetch the ``run_columns.csv`` for an Ersilia model version from GitHub.
+
+    Tries the semver tag for *version* first (``v<N>`` → ``v<N>.0.0``),
+    then falls back to ``main``. The first ref returning HTTP 200 wins.
+
+    Parameters
+    ----------
+    model_id : str
+        Ersilia model identifier.
+    version : str
+        Version string matching ``v\\d+``. Resolved by :func:`_version_to_ref`.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Parsed ``run_columns.csv``, typically with columns ``name``,
+        ``type``, ``direction``, ``description``.
+
+    Raises
+    ------
+    EosframesError
+        If neither the tagged ref nor ``main`` returns the file.
+    """
+    logger = get_logger()
+    refs_to_try = list(
+        dict.fromkeys([_version_to_ref(version), "main"])
+    )  # ordered, unique
+    for ref in refs_to_try:
+        url = _raw_url(model_id, ref, _RUN_COLUMNS_PATH)
+        logger.debug("GET %s", url)
+        resp = requests.get(url, timeout=15)
+        if resp.status_code == 200:
+            logger.info(
+                "Fetched run_columns.csv for %s @ %s (resolved from version=%s)",
+                model_id,
+                ref,
+                version,
+            )
+            return pd.read_csv(io.StringIO(resp.text))
+        logger.debug(
+            "run_columns.csv at %s returned HTTP %d for %s",
+            ref,
+            resp.status_code,
+            model_id,
+        )
+    raise EosframesError(
+        f"Could not fetch run_columns.csv for model '{model_id}' at any of "
+        f"the candidate refs {refs_to_try}. "
+        f"Make sure the repo exists at https://github.com/ersilia-os/{model_id}"
+    )

eosframes/logger.py

@@ -0,0 +1,127 @@
+"""Singleton logger for the ``eosframes`` library.
+
+The logger is named ``eosframes`` and configured once on first access. It
+prefers ``rich.logging.RichHandler`` for human-friendly CLI output, falling
+back to a plain stderr ``StreamHandler`` with a compact ``HH:MM:SS LEVEL
+message`` format. Output goes to ``stderr`` so it stays out of piped stdout.
+
+The default level is ``INFO`` — operational progress messages from
+:mod:`eosframes.ops`, :mod:`eosframes.read`, and :mod:`eosframes.write` are
+visible immediately. Two ways to change it:
+
+* **Environment** — ``EOSFRAMES_LOG_LEVEL=DEBUG`` (or ``WARNING`` /
+  ``ERROR`` / ``CRITICAL``) before the process starts.
+* **Programmatic** — :func:`set_verbosity` toggles between ``DEBUG`` and
+  ``INFO``. Useful in notebooks and library callers.
+
+Level colour styling matches ``ersilia-os/lazy-qsar`` (debug=cyan,
+info=blue, warning=yellow, error=red, critical=white-on-red).
+"""
+
+import logging
+import os
+import sys
+
+_logger = None  # singleton
+
+_LEVEL_THEME = {
+    "logging.level.debug": "bold cyan",
+    "logging.level.info": "bold blue",
+    "logging.level.warning": "bold yellow",
+    "logging.level.error": "bold red",
+    "logging.level.critical": "bold white on red",
+}
+
+
+def get_logger() -> logging.Logger:
+    """Return the singleton ``eosframes`` logger.
+
+    The logger is configured on first call and reused thereafter. Subsequent
+    calls return the same instance without re-installing handlers.
+
+    Behaviour
+    ---------
+    * Uses ``rich.logging.RichHandler`` (on a stderr ``Console``) when
+      ``rich`` is importable, falling back to ``logging.StreamHandler`` on
+      stderr.
+    * Default level is ``INFO``. Override with the ``EOSFRAMES_LOG_LEVEL``
+      environment variable (case-insensitive: ``DEBUG`` / ``INFO`` /
+      ``WARNING`` / ``ERROR`` / ``CRITICAL``) or with :func:`set_verbosity`
+      at runtime. Invalid env values fall back to ``INFO``.
+    * ``propagate = False`` so library records don't bubble up to the root
+      logger and produce duplicate output in host applications.
+
+    Returns
+    -------
+    logging.Logger
+        The shared ``eosframes`` logger instance.
+    """
+    global _logger
+    if _logger is not None:
+        return _logger
+
+    logger = logging.getLogger("eosframes")
+    logger.setLevel(_resolve_level())
+    # Don't double-log via the root logger when callers configure their own
+    # handlers (e.g. a Flask/Django app importing eosframes).
+    logger.propagate = False
+
+    if not logger.handlers:
+        logger.addHandler(_build_handler())
+
+    _logger = logger
+    return _logger
+
+
+def set_verbosity(verbose: bool) -> None:
+    """Toggle verbose (``DEBUG``) logging on or off.
+
+    ``verbose=True`` lowers the level to ``DEBUG`` (everything visible);
+    ``verbose=False`` restores it to ``INFO`` — the default operational
+    level, where progress messages from readers, writers, and ops are still
+    shown but per-HTTP-probe / per-chunk traces are hidden. Warnings and
+    errors are emitted at both settings.
+
+    Parameters
+    ----------
+    verbose : bool
+    """
+    logger = get_logger()
+    logger.setLevel(logging.DEBUG if verbose else logging.INFO)
+
+
+def _build_handler() -> logging.Handler:
+    """Build the singleton stderr handler, preferring rich's ``RichHandler``."""
+    try:
+        from rich.console import Console
+        from rich.logging import RichHandler
+        from rich.theme import Theme
+
+        console = Console(stderr=True, theme=Theme(_LEVEL_THEME))
+        handler: logging.Handler = RichHandler(
+            console=console,
+            rich_tracebacks=True,
+            show_path=False,
+            show_time=True,
+            markup=False,
+            log_time_format="%H:%M:%S",
+        )
+        handler.setFormatter(logging.Formatter("%(message)s"))
+        return handler
+    except ImportError:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(
+            logging.Formatter(
+                "%(asctime)s %(levelname)-8s %(message)s", datefmt="%H:%M:%S"
+            )
+        )
+        return handler
+
+
+def _resolve_level() -> int:
+    """Resolve the logging level from ``EOSFRAMES_LOG_LEVEL``, defaulting to INFO."""
+    raw = os.environ.get("EOSFRAMES_LOG_LEVEL", "").strip().upper()
+    if not raw:
+        return logging.INFO
+    level = logging.getLevelName(raw)
+    return level if isinstance(level, int) else logging.INFO