picsure 2.0.0__py3-none-any.whl

picsure/__init__.py

@@ -0,0 +1,78 @@
+"""PIC-SURE Python API adapter."""
+
+import os
+
+from picsure._models.clause import Clause, PhenotypicFilterType
+from picsure._models.clause_group import ClauseGroup, GroupOperator
+from picsure._models.count_result import CountResult
+from picsure._models.facet import FacetSet
+from picsure._models.genomic_filter import (
+    GenomicFilter,
+    GenomicFilterKey,
+    VariantFrequency,
+    VariantSeverity,
+)
+from picsure._models.query import Query
+from picsure._models.query_type import QueryType
+from picsure._models.session import Session
+from picsure._services.connect import connect
+from picsure._services.genomic_data import genomicConsequences
+from picsure._services.query_build import (
+    buildClause,
+    buildClauseGroup,
+    buildGenomicFilter,
+    buildQuery,
+)
+from picsure._services.query_edit import removeSubQuery, replaceClause
+from picsure._transport.platforms import Platform
+from picsure.errors import (
+    PicSureAuthError,
+    PicSureConnectionError,
+    PicSureError,
+    PicSureQueryError,
+    PicSureValidationError,
+)
+
+
+def set_dev_mode(enabled: bool) -> None:
+    """Set the ``PICSURE_DEV_MODE`` environment variable.
+
+    Affects the **next** call to :func:`connect`. Existing ``Session``
+    objects are not mutated; reconnect to pick up the change.
+    """
+    if enabled:
+        os.environ["PICSURE_DEV_MODE"] = "1"
+    else:
+        os.environ.pop("PICSURE_DEV_MODE", None)
+
+
+__all__ = [
+    "buildClause",
+    "buildClauseGroup",
+    "buildGenomicFilter",
+    "buildQuery",
+    "connect",
+    "genomicConsequences",
+    "removeSubQuery",
+    "replaceClause",
+    "set_dev_mode",
+    "Clause",
+    "ClauseGroup",
+    "CountResult",
+    "FacetSet",
+    "GenomicFilter",
+    "GenomicFilterKey",
+    "GroupOperator",
+    "PhenotypicFilterType",
+    "PicSureAuthError",
+    "PicSureConnectionError",
+    "PicSureError",
+    "PicSureQueryError",
+    "PicSureValidationError",
+    "Platform",
+    "Query",
+    "QueryType",
+    "Session",
+    "VariantFrequency",
+    "VariantSeverity",
+]

picsure/_data/variant_consequences.json

@@ -0,0 +1,35 @@
+[
+  {
+    "key": "High Severity",
+    "children": [
+      "splice_acceptor_variant",
+      "splice_donor_variant",
+      "stop_gained",
+      "frameshift_variant",
+      "stop_lost",
+      "start_lost"
+    ]
+  },
+  {
+    "key": "Medium Severity",
+    "children": [
+      "inframe_insertion",
+      "inframe_deletion",
+      "missense_variant",
+      "protein_altering_variant"
+    ]
+  },
+  {
+    "key": "Low Severity",
+    "children": [
+      "splice_region_variant",
+      "splice_donor_5th_base_variant",
+      "splice_donor_region_variant",
+      "splice_polypyrimidine_tract_variant",
+      "incomplete_terminal_codon_variant",
+      "start_retained_variant",
+      "stop_retained_variant",
+      "synonymous_variant"
+    ]
+  }
+]

picsure/_dev/__init__.py

@@ -0,0 +1 @@
+"""Developer-mode internals: config, events, buffer, redaction, reporting, timing."""

picsure/_dev/buffer.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import threading
+from collections import deque
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from picsure._dev.events import Event
+
+
+class EventBuffer:
+    """Thread-safe FIFO of dev-mode events with a fixed maximum size.
+
+    When full, the oldest entry is dropped on append.
+    """
+
+    def __init__(self, max_events: int) -> None:
+        if max_events <= 0:
+            raise ValueError("max_events must be positive")
+        self._deque: deque[Event] = deque(maxlen=max_events)
+        self._lock = threading.Lock()
+
+    def append(self, event: Event) -> None:
+        with self._lock:
+            self._deque.append(event)
+
+    def snapshot(self) -> list[Event]:
+        """Return a list copy of current events (snapshot at call time)."""
+        with self._lock:
+            return list(self._deque)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._deque.clear()
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._deque)

picsure/_dev/config.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+
+from picsure._dev.buffer import EventBuffer
+from picsure._dev.events import Event
+
+_ENV_MODE = "PICSURE_DEV_MODE"
+_ENV_MAX_EVENTS = "PICSURE_DEV_MAX_EVENTS"
+_DEFAULT_MAX_EVENTS = 1000
+_TRUTHY = {"1", "true", "yes"}
+
+_HTTP_LOGGER = logging.getLogger("picsure.http")
+_FN_LOGGER = logging.getLogger("picsure.fn")
+_CONNECT_LOGGER = logging.getLogger("picsure.connect")
+_ERROR_LOGGER = logging.getLogger("picsure.error")
+_DEV_WARNING_LOGGER = logging.getLogger("picsure.dev")
+
+_LOGGERS = {
+    "http": _HTTP_LOGGER,
+    "function": _FN_LOGGER,
+    "connect": _CONNECT_LOGGER,
+}
+
+
+def _env_truthy(raw: str | None) -> bool:
+    return raw is not None and raw.strip().lower() in _TRUTHY
+
+
+def _env_int(raw: str | None, default: int) -> int:
+    if raw is None:
+        return default
+    try:
+        value = int(raw)
+    except ValueError:
+        return default
+    return value if value > 0 else default
+
+
+def _logger_for(kind: str) -> logging.Logger:
+    return _LOGGERS.get(kind, _ERROR_LOGGER)
+
+
+def _format_bytes(n: int | None) -> str:
+    if n is None:
+        return "-"
+    if n < 1024:
+        return f"{n}B"
+    if n < 1024 * 1024:
+        return f"{n / 1024:.1f}KB"
+    return f"{n / (1024 * 1024):.1f}MB"
+
+
+def _format_event(event: Event) -> str:
+    parts: list[str] = []
+    if event.kind == "http":
+        status = event.status if event.status is not None else "-"
+        parts.append(f"{event.name} {status} {event.duration_ms:.0f}ms")
+        parts.append(f"in={_format_bytes(event.bytes_in)}")
+        parts.append(f"out={_format_bytes(event.bytes_out)}")
+        parts.append(f"retry={event.retry}")
+        if event.metadata.get("redacted"):
+            parts.append(f"[body redacted: {event.metadata['redacted']}]")
+    else:
+        parts.append(f"{event.name} {event.duration_ms:.0f}ms")
+        if event.error:
+            parts.append(f"error={event.error}")
+    return " ".join(parts)
+
+
+@dataclass
+class DevConfig:
+    """Resolved developer-mode config shared by transport and session layers."""
+
+    enabled: bool
+    max_events: int
+    buffer: EventBuffer = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.buffer = EventBuffer(self.max_events)
+
+    @classmethod
+    def from_env(cls, override: bool | None) -> DevConfig:
+        if override is None:
+            enabled = _env_truthy(os.environ.get(_ENV_MODE))
+        else:
+            enabled = override
+        max_events = _env_int(os.environ.get(_ENV_MAX_EVENTS), _DEFAULT_MAX_EVENTS)
+        return cls(enabled=enabled, max_events=max_events)
+
+    def emit(self, event: Event) -> None:
+        """Record an event. No-op when disabled. Never raises."""
+        if not self.enabled:
+            return
+        try:
+            self.buffer.append(event)
+            _logger_for(event.kind).debug(_format_event(event))
+        except Exception as exc:  # pragma: no cover — defensive
+            _DEV_WARNING_LOGGER.warning("dev-mode emit failed: %s", exc)

picsure/_dev/events.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """A single dev-mode event: HTTP call, function, connect, or error."""
+
+    timestamp: datetime
+    kind: str
+    name: str
+    duration_ms: float
+    bytes_in: int | None
+    bytes_out: int | None
+    status: int | None
+    retry: int
+    error: str | None
+    metadata: dict[str, Any] = field(default_factory=dict)

picsure/_dev/redaction.py

@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+_SENSITIVE_RESULT_TYPES = {
+    "DATAFRAME",
+    "DATAFRAME_TIMESERIES",
+    "DATAFRAME_PFB",
+}
+
+# PSAMA's /user/me returns the user's JWT in a `token` field alongside
+# `email` and other identity fields.  Treat any of these as secrets when
+# they appear in a PSAMA-pathed body.
+_PSAMA_SENSITIVE_KEYS = frozenset(
+    {
+        "email",
+        "token",
+        "access_token",
+        "refresh_token",
+        "password",
+        "secret",
+        "apikey",
+        "api_key",
+    }
+)
+
+
+def redact_headers(headers: dict[str, str]) -> dict[str, str]:
+    """Return a copy of headers with Authorization masked."""
+    out = dict(headers)
+    for key in list(out.keys()):
+        if key.lower() == "authorization":
+            out[key] = "Bearer ***"
+    return out
+
+
+def redact_for_log(
+    path: str,
+    method: str,
+    body: dict[str, Any] | list[Any] | None,
+) -> str | None:
+    """Return a safe string repr of a body, or None if it must not be logged.
+
+    Returning None signals "body is sensitive — log size only."
+    """
+    if body is None:
+        return ""
+
+    if _is_psama_path(path):
+        return json.dumps(_redact_psama_secrets(body))
+
+    # Suppress based on body SHAPE, not path: the async PFB export posts the
+    # same participant-bearing query body to /picsure/v3/query (and
+    # /status, /result), none of which end in /query/sync.
+    if _body_is_participant_like(body):
+        return None
+
+    # Default: safe to log
+    return json.dumps(body, default=str)
+
+
+def body_is_sensitive(
+    path: str,
+    method: str,
+    body: dict[str, Any] | list[Any] | None,
+) -> bool:
+    """Cheap predicate: would ``redact_for_log`` refuse to serialize this body?
+
+    Callers that only need the yes/no decision can use this to avoid the
+    full ``json.dumps`` round-trip in ``redact_for_log``.
+    """
+    if body is None:
+        return False
+    return _body_is_participant_like(body)
+
+
+def _is_psama_path(path: str) -> bool:
+    return path.startswith("/psama/")
+
+
+def _body_is_participant_like(body: Any) -> bool:
+    query = body.get("query") if isinstance(body, dict) else None
+    if not isinstance(query, dict):
+        return False
+    result_type = query.get("expectedResultType")
+    return result_type in _SENSITIVE_RESULT_TYPES
+
+
+def _redact_psama_secrets(body: Any) -> Any:
+    if isinstance(body, dict):
+        return {
+            k: (
+                "***"
+                if k.lower() in _PSAMA_SENSITIVE_KEYS and isinstance(v, str)
+                else _redact_psama_secrets(v)
+            )
+            for k, v in body.items()
+        }
+    if isinstance(body, list):
+        return [_redact_psama_secrets(item) for item in body]
+    return body

picsure/_dev/reporting.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from picsure._dev.events import Event
+
+_EVENT_COLS = [
+    "timestamp",
+    "kind",
+    "name",
+    "duration_ms",
+    "bytes_in",
+    "bytes_out",
+    "status",
+    "retry",
+    "error",
+    "metadata",
+]
+
+_STATS_COLS = [
+    "kind",
+    "name",
+    "calls",
+    "total_ms",
+    "avg_ms",
+    "min_ms",
+    "max_ms",
+    "bytes_in_total",
+    "bytes_out_total",
+    "retries",
+    "errors",
+]
+
+
+def events_to_df(events: list[Event]) -> pd.DataFrame:
+    if not events:
+        return pd.DataFrame(columns=_EVENT_COLS)
+    return pd.DataFrame([asdict(e) for e in events], columns=_EVENT_COLS)
+
+
+def stats_to_df(events: list[Event]) -> pd.DataFrame:
+    if not events:
+        return pd.DataFrame(columns=_STATS_COLS)
+
+    groups: dict[tuple[str, str], list[Event]] = defaultdict(list)
+    for event in events:
+        groups[(event.kind, event.name)].append(event)
+
+    rows = []
+    for (kind, name), batch in groups.items():
+        durations = [e.duration_ms for e in batch]
+        rows.append(
+            {
+                "kind": kind,
+                "name": name,
+                "calls": len(batch),
+                "total_ms": sum(durations),
+                "avg_ms": sum(durations) / len(batch),
+                "min_ms": min(durations),
+                "max_ms": max(durations),
+                "bytes_in_total": sum((e.bytes_in or 0) for e in batch),
+                "bytes_out_total": sum((e.bytes_out or 0) for e in batch),
+                "retries": sum(1 for e in batch if e.retry > 0),
+                "errors": sum(1 for e in batch if e.error is not None),
+            }
+        )
+    return pd.DataFrame(rows, columns=_STATS_COLS)

picsure/_dev/timing.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import functools
+import time
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from picsure._dev.events import Event
+
+if TYPE_CHECKING:
+    from picsure._dev.config import DevConfig
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def timed(name: str) -> Callable[[F], F]:
+    """Method decorator: emits a 'function' event on success, 'error' on exception.
+
+    Wrapped object must expose ``self._dev_config: DevConfig | None``.
+    When the attribute is missing or the config is disabled, the decorator
+    is a no-op.
+    """
+
+    def decorator(func: F) -> F:
+        @functools.wraps(func)
+        def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any:
+            cfg: DevConfig | None = getattr(self, "_dev_config", None)
+            if cfg is None or not cfg.enabled:
+                return func(self, *args, **kwargs)
+
+            start = time.monotonic()
+            try:
+                result = func(self, *args, **kwargs)
+            except Exception as exc:
+                if getattr(exc, "_picsure_dev_emitted", False):
+                    raise
+                duration_ms = (time.monotonic() - start) * 1000.0
+                cfg.emit(
+                    Event(
+                        timestamp=datetime.now(timezone.utc),
+                        kind="error",
+                        name=name,
+                        duration_ms=duration_ms,
+                        bytes_in=None,
+                        bytes_out=None,
+                        status=None,
+                        retry=0,
+                        error=type(exc).__name__,
+                        metadata={},
+                    )
+                )
+                raise
+
+            duration_ms = (time.monotonic() - start) * 1000.0
+            cfg.emit(
+                Event(
+                    timestamp=datetime.now(timezone.utc),
+                    kind="function",
+                    name=name,
+                    duration_ms=duration_ms,
+                    bytes_in=None,
+                    bytes_out=None,
+                    status=None,
+                    retry=0,
+                    error=None,
+                    metadata=_metadata_for(result),
+                )
+            )
+            return result
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def _metadata_for(result: Any) -> dict[str, Any]:
+    try:
+        import pandas as pd
+    except Exception:  # pragma: no cover — pandas is a hard dep
+        return {}
+    if isinstance(result, pd.DataFrame):
+        return {"df_rows": int(result.shape[0]), "df_cols": int(result.shape[1])}
+    if isinstance(result, int):
+        return {"result_type": "int"}
+    return {}

picsure/_models/clause.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class PhenotypicFilterType(Enum):
+    """Type of filter clause in a PIC-SURE query.
+
+    Use these constants with ``picsure.buildClause()``:
+
+    - ``FILTER`` — filter by categorical values or numeric range
+    - ``ANYRECORD`` — match records where the concept path *or any
+      descendant* has a value (wire: ``ANY_RECORD_OF``)
+    - ``REQUIRE`` — require the concept path to have a non-null value
+      (wire: ``REQUIRED``)
+
+    To include concept paths in query output without filtering, pass
+    them to ``picsure.buildQuery(includeConcepts=...)`` instead — output
+    columns are no longer a clause type.
+    """
+
+    FILTER = "filter"
+    ANYRECORD = "anyrecord"
+    REQUIRE = "require"
+
+
+_WIRE_NAME_BY_TYPE: dict[PhenotypicFilterType, str] = {
+    PhenotypicFilterType.FILTER: "FILTER",
+    PhenotypicFilterType.REQUIRE: "REQUIRED",
+    PhenotypicFilterType.ANYRECORD: "ANY_RECORD_OF",
+}
+
+# Reverse of _WIRE_NAME_BY_TYPE, exposed so query_load can rebuild
+# clauses from the wire payload without redefining the mapping.
+PHENOTYPIC_FILTER_TYPE_BY_WIRE_NAME: dict[str, PhenotypicFilterType] = {
+    v: k for k, v in _WIRE_NAME_BY_TYPE.items()
+}
+
+
+@dataclass(frozen=True)
+class Clause:
+    """A single filter clause in a PIC-SURE query.
+
+    Created by ``picsure.buildClause()``. Can be passed directly to
+    ``Session.runQuery()`` or combined with other clauses via
+    ``picsure.buildClauseGroup()``.
+
+    **Wire format.** :meth:`to_query_json` emits a v3 ``PhenotypicFilter``
+    leaf (or an ``OR`` ``PhenotypicSubquery`` of leaves for multi-key
+    clauses) per the ``/picsure/v3/query/sync`` contract.
+    """
+
+    keys: list[str]
+    type: PhenotypicFilterType
+    categories: list[str] | None = None
+    min: float | None = None
+    max: float | None = None
+
+    def concept_paths(self) -> list[str]:
+        """Concept paths this clause references, in order.
+
+        Used to fold a query's filter variables into the output ``select``
+        array so they are returned without being repeated in
+        ``includeConcepts``.
+        """
+        return list(self.keys)
+
+    def to_query_json(self) -> dict[str, object]:
+        """Serialize this clause as a v3 ``PhenotypicClause``.
+
+        Emits a ``PhenotypicFilter`` leaf for single-key clauses, or
+        an OR ``PhenotypicSubquery`` of per-key leaves when the clause
+        spans multiple keys.
+        """
+        leaves = [self._make_leaf(k) for k in self.keys]
+        if len(leaves) == 1:
+            return leaves[0]
+        return {
+            "operator": "OR",
+            "phenotypicClauses": leaves,
+            "not": False,
+        }
+
+    def _make_leaf(self, concept_path: str) -> dict[str, object]:
+        leaf: dict[str, object] = {
+            "phenotypicFilterType": _WIRE_NAME_BY_TYPE[self.type],
+            "conceptPath": concept_path,
+            "not": False,
+        }
+        if self.type == PhenotypicFilterType.FILTER:
+            if self.categories is not None:
+                leaf["values"] = list(self.categories)
+            if self.min is not None:
+                leaf["min"] = self.min
+            if self.max is not None:
+                leaf["max"] = self.max
+        return leaf

picsure/_models/clause_group.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from picsure._models.clause import Clause
+
+
+class GroupOperator(Enum):
+    """Logical operator for combining clauses in a group.
+
+    - ``AND`` — all clauses must match
+    - ``OR`` — at least one clause must match
+    """
+
+    AND = "AND"
+    OR = "OR"
+
+
+@dataclass(frozen=True)
+class ClauseGroup:
+    """A group of clauses combined with AND or OR.
+
+    Created by ``picsure.buildClauseGroup()``. Can contain both
+    ``Clause`` and nested ``ClauseGroup`` objects for arbitrarily
+    deep nesting.
+
+    **Wire format.** :meth:`to_query_json` emits a v3
+    ``PhenotypicSubquery`` (``operator`` / ``phenotypicClauses``) per
+    the ``/picsure/v3/query/sync`` contract. The previous wire format
+    is not supported.
+    """
+
+    clauses: list[Clause | ClauseGroup]
+    operator: GroupOperator
+
+    def concept_paths(self) -> list[str]:
+        """All concept paths referenced anywhere in this group, depth-first.
+
+        Recurses uniformly through nested groups because each child —
+        ``Clause`` or ``ClauseGroup`` — implements ``concept_paths()``.
+        """
+        return [path for child in self.clauses for path in child.concept_paths()]
+
+    def to_query_json(self) -> dict[str, object]:
+        """Serialize this group as a v3 ``PhenotypicSubquery``."""
+        return {
+            "operator": self.operator.value,
+            "phenotypicClauses": [child.to_query_json() for child in self.clauses],
+            "not": False,
+        }