cuiman 0.3.0__tar.gz → 0.4.0__tar.gz

{cuiman-0.3.0 → cuiman-0.4.0}/.gitignore

@@ -205,4 +205,4 @@ cython_debug/
 .cursorindexingignore
 
 # Downloaded font assets
-docs/assets/fonts/*.ttf
+docs/assets/downloaded/

{cuiman-0.3.0 → cuiman-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cuiman
-Version: 0.3.0
+Version: 0.4.0
 Summary: Provides a client Python API, GUI, and CLI for servers compliant with OGC API - Processes
 Project-URL: Documentation, https://eo-tools.github.io/eozilla
 Project-URL: Repository, https://github.com/eo-tools/eozilla
@@ -28,7 +28,7 @@ Classifier: Topic :: Software Development
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: authlib<1.9,>=1.8
-Requires-Dist: gavicore>=0.3.0
+Requires-Dist: gavicore>=0.4.0
 Requires-Dist: httpx2
 Requires-Dist: ipython
 Requires-Dist: joserfc<2,>=1.6
@@ -39,6 +39,8 @@ Requires-Dist: pyyaml
 Requires-Dist: remotestate<1,>=0.3.4
 Requires-Dist: typer<1,>=0.26.0
 Requires-Dist: uri-template
+Provides-Extra: stac
+Requires-Dist: pystac<1.16,>=1.15.2; extra == 'stac'
 Description-Content-Type: text/markdown
 
 # Eozilla Cuiman

{cuiman-0.3.0 → cuiman-0.4.0}/cuiman/api/__init__.py

@@ -2,6 +2,8 @@
 #  Permissions are hereby granted under the terms of the Apache 2.0 License:
 #  https://opensource.org/license/apache-2-0.
 
+from gavicore.models.core import JobResults
+
 from .async_client import AsyncClient
 from .client import Client
 from .config import ClientConfig
@@ -16,3 +18,14 @@ __all__ = [
     "JobMonitor",
     "JobOptions",
 ]
+
+
+def _repr_job_results_as_html(self: JobResults) -> str:
+    """Render job outputs in notebooks without fetching or displaying data."""
+    from .assets.job_results import _job_results_html
+
+    return _job_results_html(self)
+
+
+# Install Cuiman's presentation without introducing a gavicore dependency on it.
+JobResults._repr_html_ = _repr_job_results_as_html  # type: ignore[attr-defined]

cuiman-0.4.0/cuiman/api/assets/__init__.py

@@ -0,0 +1,76 @@
+#  Copyright (c) 2026 by the Eozilla team and contributors
+#  Permissions are hereby granted under the terms of the Apache 2.0 License:
+#  https://opensource.org/license/apache-2-0.
+
+"""Notebook display utilities for STAC assets and job results."""
+
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Sequence
+
+from gavicore.models.core import JobResults, QualifiedValue
+
+from .common import _get_items_expression
+from .stac import as_stac_asset
+
+if TYPE_CHECKING:
+    from pystac import Asset, Item, ItemCollection
+
+__all__ = ["as_stac_asset", "display_assets"]
+
+
+async def display_assets(
+    items: "JobResults | QualifiedValue | dict[str, Any] | Item | Sequence[Item] | ItemCollection",
+    *,
+    roles: str | Iterable[str] | None = None,
+    previews: bool = True,
+    open_asset: "Callable[[Asset], Any] | None" = None,
+) -> None:
+    """Render job result tables or grouped STAC assets and optional previews.
+
+    Args:
+        items: JobResults, STAC objects, or inline STAC JSON dictionaries
+            (optionally wrapped in QualifiedValue).
+        roles: Show assets matching any of these roles. A string matches one
+            role, None shows all assets, and an empty iterable matches none.
+            Job result rows are not filtered by roles.
+        previews: Open and display thumbnail, overview, and visual assets.
+            Set to ``False`` to prevent asset preview reads. Geometry previews
+            remain enabled. Asset previews are independent of the table's
+            role filter; unreadable or unsupported previews are skipped.
+        open_asset: A synchronous or asynchronous asset opener. If omitted,
+            asset previews are skipped; tables and geometry maps remain enabled.
+            Job result tables never open linked outputs.
+    """
+    await _display_assets(
+        items,
+        expression=_get_items_expression("display_assets"),
+        roles=roles,
+        previews=previews,
+        open_asset=open_asset,
+    )
+
+
+async def _display_assets(
+    items: "JobResults | QualifiedValue | dict[str, Any] | Item | Sequence[Item] | ItemCollection",
+    *,
+    expression: str | None,
+    roles: str | Iterable[str] | None = None,
+    previews: bool = True,
+    open_asset: "Callable[[Asset], Any] | None" = None,
+) -> None:
+    """Dispatch notebook display without importing optional STAC dependencies."""
+    if isinstance(items, JobResults):
+        from IPython.display import display
+
+        from .job_results import _render_job_results
+
+        display(_render_job_results(items, expression=expression))
+    else:
+        from .stac import _display_stac_assets
+
+        await _display_stac_assets(
+            items,
+            expression=expression,
+            roles=roles,
+            previews=previews,
+            open_asset=open_asset,
+        )

cuiman-0.4.0/cuiman/api/assets/common.py

@@ -0,0 +1,208 @@
+#  Copyright (c) 2026 by the Eozilla team and contributors
+#  Permissions are hereby granted under the terms of the Apache 2.0 License:
+#  https://opensource.org/license/apache-2-0.
+
+"""Shared notebook styles, links, copy buttons, and caller expressions."""
+
+from html import escape
+from inspect import currentframe
+from types import FrameType
+from urllib.parse import unquote, urlsplit
+
+
+def _stac_label(value: object) -> str | None:
+    """Recognize inline STAC items and collections without optional imports."""
+    if not isinstance(value, dict):
+        return None
+    if (
+        value.get("type") == "Feature"
+        and isinstance(value.get("stac_version"), str)
+        and isinstance(value.get("assets"), dict)
+    ):
+        return "STAC Item"
+    features = value.get("features")
+    if (
+        value.get("type") == "FeatureCollection"
+        and isinstance(features, list)
+        and features
+        and all(_stac_label(feature) == "STAC Item" for feature in features)
+    ):
+        return "STAC ItemCollection"
+    return None
+
+
+def _styles() -> str:
+    """Return the shared asset table and card styles."""
+    return (
+        "<style>"
+        ".cuiman-assets-card{border-radius:12px;box-shadow:0 3px 12px #0001}"
+        ".cuiman-assets-map{border-radius:8px}"
+        ".cuiman-assets{font:14px/1.5 system-ui,sans-serif;color:inherit}"
+        ".cuiman-assets header{padding:0;"
+        "overflow-wrap:anywhere}"
+        ".cuiman-assets header strong{font-size:20px;font-weight:650}"
+        ".cuiman-assets-meta{opacity:.65;font-size:12px;margin-top:4px}"
+        ".cuiman-assets-properties{display:grid;grid-template-columns:minmax(100px,auto) 1fr;"
+        "gap:4px 16px;margin:14px 0 0;font-size:12px;max-height:180px;overflow:auto}"
+        ".cuiman-assets-properties dt{opacity:.6;font-weight:400}"
+        ".cuiman-assets-properties dd{margin:0;overflow-wrap:anywhere}"
+        ".cuiman-assets-table{overflow-x:auto;padding:8px 20px 16px}"
+        # Outrank notebook HTML table rules in both plain HTML and widget outputs.
+        ".cuiman-assets .cuiman-assets-table table{width:100%;border-collapse:collapse;"
+        "text-align:left;background:transparent}"
+        ".cuiman-assets .cuiman-assets-table table th{font-size:11px;text-transform:uppercase;"
+        "letter-spacing:.06em;opacity:.6;font-weight:600;text-align:left}"
+        ".cuiman-assets .cuiman-assets-table table td,"
+        ".cuiman-assets .cuiman-assets-table table th{padding:10px 12px;"
+        "border-bottom:1px solid #8882;text-align:left}"
+        ".cuiman-assets .cuiman-assets-table table td:first-child{font-weight:600}"
+        ".cuiman-assets .cuiman-assets-table table td:last-child,"
+        ".cuiman-assets .cuiman-assets-table table th:last-child{width:32px;text-align:center}"
+        ".cuiman-assets .cuiman-assets-table table tbody tr:last-child td{border-bottom:0}"
+        ".cuiman-assets .cuiman-assets-table table tbody tr:nth-child(odd){background:#8881}"
+        ".cuiman-assets .cuiman-assets-table table tbody tr:nth-child(even){background:transparent}"
+        ".cuiman-assets .cuiman-assets-table table tbody tr:hover{background:#8882}"
+        ".cuiman-assets a{color:#3b9fa5;text-decoration:none}"
+        ".cuiman-assets a:hover{text-decoration:underline}"
+        ".cuiman-assets-empty{padding:0 20px}"
+        ".cuiman-assets-previews figure{margin:0;width:160px;min-width:0}"
+        ".cuiman-assets-previews img{display:block;width:100%;"
+        "height:140px;object-fit:contain;background:#8881;border-radius:8px}"
+        ".cuiman-assets-previews figcaption{font:12px/1.5 system-ui,sans-serif;"
+        "opacity:.65;padding:8px 2px}"
+        "</style>"
+    )
+
+
+def _render_link(href: str) -> str:
+    """Render a file link, escaping labels and rejecting active URL schemes."""
+    path = urlsplit(href.replace("\\", "/")).path.rstrip("/")
+    filename = unquote(path.rsplit("/", 1)[-1]) or href
+    scheme = urlsplit(href).scheme.lower()
+
+    if scheme in ("", "http", "https", "file"):
+        return (
+            f"<a href='{escape(href, quote=True)}' "
+            "style='overflow-wrap:anywhere'>"
+            f"{escape(filename)}</a>"
+        )
+    else:
+        return escape(filename)
+
+
+def _copy_button(expression: str) -> str:
+    """Render a button that copies an escaped Python access expression."""
+    return (
+        f"<button data-copy='{escape(expression, quote=True)}' "
+        "type='button' title='Copy expression' aria-label='Copy expression' "
+        "style='background:transparent;border:0;padding:0.25em;"
+        "color:inherit;cursor:pointer;line-height:0' "
+        'onclick="(async b => {'
+        "try { await navigator.clipboard.writeText(b.dataset.copy); "
+        "b.title = 'Copied'; } "
+        "catch (_) { window.prompt('Copy expression:', b.dataset.copy); }"
+        '})(this)">'
+        "<svg xmlns='http://www.w3.org/2000/svg' width='18' height='18' "
+        "viewBox='0 0 24 24' fill='none' stroke='currentColor' "
+        "stroke-width='2' stroke-linecap='round' stroke-linejoin='round' "
+        "aria-hidden='true' focusable='false'>"
+        "<rect x='9' y='9' width='13' height='13' rx='2'/>"
+        "<path d='M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9"
+        "a2 2 0 0 1 2 2v1'/></svg></button>"
+    )
+
+
+def _get_items_expression(function_name: str = "show_assets") -> str | None:
+    """Capture the public caller's items expression without retaining its frame."""
+    frame = currentframe()
+    try:
+        caller = frame.f_back.f_back if frame and frame.f_back else None
+        expression = _get_call_argument_source(caller, function_name)
+    finally:
+        del frame
+    if expression is None:
+        return None
+
+    import ast
+
+    node = ast.parse(f"({expression})", mode="eval").body
+    # Attribute access binds correctly to these expressions without parentheses.
+    return (
+        expression
+        if isinstance(node, (ast.Name, ast.Attribute, ast.Subscript, ast.Call))
+        else f"({expression})"
+    )
+
+
+def _get_call_argument_source(
+    frame: FrameType | None, function_name: str
+) -> str | None:
+    """Recover the items argument from the caller's cached source, without eval.
+
+    Instruction positions distinguish calls on the same line and aliases.
+    When positions are unavailable, accept only one matching named call.
+    Missing source and ambiguous calls return None.
+    """
+    import ast
+    import dis
+    import linecache
+
+    if frame is None:
+        return None
+    source = "".join(linecache.getlines(frame.f_code.co_filename, frame.f_globals))
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+
+    positions = next(
+        (
+            instruction.positions
+            for instruction in dis.get_instructions(frame.f_code, show_caches=True)
+            if instruction.offset == frame.f_lasti
+        ),
+        None,
+    )
+    position_span = (
+        tuple(positions)
+        if positions is not None and all(value is not None for value in positions)
+        else None
+    )
+    candidates = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Call, ast.Await)):
+            continue
+        call = node.value if isinstance(node, ast.Await) else node
+        if not isinstance(call, ast.Call):
+            continue
+        if position_span is not None:
+            span = (node.lineno, node.end_lineno, node.col_offset, node.end_col_offset)
+            if span != position_span:
+                continue
+        else:
+            if not isinstance(node, ast.Call):
+                continue
+            name = (
+                call.func.id
+                if isinstance(call.func, ast.Name)
+                else call.func.attr
+                if isinstance(call.func, ast.Attribute)
+                else None
+            )
+            if name != function_name or not (
+                node.lineno <= frame.f_lineno <= (node.end_lineno or node.lineno)
+            ):
+                continue
+        candidates.append(call)
+
+    if len(candidates) != 1:
+        return None
+    call = candidates[0]
+    argument = (
+        call.args[0]
+        if call.args
+        else next((kw.value for kw in call.keywords if kw.arg == "items"), None)
+    )
+    if argument is None or isinstance(argument, ast.Starred):
+        return None
+    return ast.get_source_segment(source, argument)

cuiman-0.4.0/cuiman/api/assets/job_results.py

@@ -0,0 +1,71 @@
+# Copyright (c) 2026 by the Eozilla team and contributors
+# Permissions are hereby granted under the terms of the Apache 2.0 License:
+# https://opensource.org/license/apache-2-0.
+
+"""Notebook tables for raw job outputs, without fetching linked resources."""
+
+from html import escape
+from json import dumps
+from typing import Any
+
+from gavicore.models.core import JobResults, Link, QualifiedValue
+
+from .common import _copy_button, _render_link, _stac_label, _styles
+
+
+def _render_value(value: Any) -> str:
+    """Render JSON scalars directly and structured values as expandable JSON."""
+    if isinstance(value, (dict, list)):
+        return (
+            f"<details><summary>{_stac_label(value) or 'JSON'}</summary>"
+            "<pre style='max-height:320px;overflow:auto;white-space:pre-wrap'>"
+            f"{escape(dumps(value, ensure_ascii=False, indent=2))}</pre></details>"
+        )
+    return escape(dumps(value, ensure_ascii=False))
+
+
+def _render_job_results(results: JobResults, *, expression: str | None = None):
+    """Build an output table with safe links and copyable root access expressions."""
+    from IPython.display import HTML
+
+    return HTML(_job_results_html(results, expression=expression))
+
+
+def _job_results_html(results: JobResults, *, expression: str | None = None) -> str:
+    """Return the shared output table HTML without display or optional imports."""
+    rows = []
+    json_values = results.model_dump(mode="json", by_alias=True) or {}
+    for name, result in (results.root or {}).items():
+        media_type = ""
+        if isinstance(result, Link):
+            kind = "Link"
+            media_type = result.type or ""
+            value_html = _render_link(result.href)
+        elif isinstance(result, QualifiedValue):
+            kind = "Inline"
+            media_type = result.mediaType or ""
+            value_html = _render_value(json_values[name]["value"])
+        else:
+            kind = "Inline"
+            value_html = _render_value(json_values[name])
+        access = f"{expression or 'results'}.root[{name!r}]"
+        rows.append(
+            "<tr>"
+            f"<td>{escape(name)}</td><td>{kind}</td>"
+            f"<td>{escape(media_type)}</td><td>{value_html}</td>"
+            f"<td>{_copy_button(access)}</td></tr>"
+        )
+    table = (
+        "<div class='cuiman-assets-table'><table>"
+        "<thead><tr><th>Output</th><th>Kind</th><th>Media type</th>"
+        "<th>Value / location</th><th>Code</th></tr></thead>"
+        f"<tbody>{''.join(rows)}</tbody></table></div>"
+        if rows
+        else "<p class='cuiman-assets-empty'><em>No outputs</em></p>"
+    )
+    return (
+        _styles() + "<section class='cuiman-assets cuiman-assets-card' "
+        "style='border:1px solid #8884;overflow:hidden;margin:12px 0 24px'>"
+        "<header style='padding:16px 20px 8px'><strong>Job results</strong></header>"
+        f"{table}</section>"
+    )