"""The Fluksio engine.

Inside a node, ``import fluksio`` is not this package: the worker installs a
reporter of its own under that name before any node code runs, so what a node
gets is :mod:`fluksio_worker.worker_main`'s ``emit`` and ``save_artifact``.
The stubs below stand in the same place everywhere else, and say so rather
than failing as a missing attribute.

Nothing is imported from the rest of the package here. Every ``from fluksio.x
import y`` in the engine passes through this module, and an import cycle or a
second of start-up cost would both begin here.
"""

from importlib.metadata import PackageNotFoundError
from importlib.metadata import version as _version
from typing import Any

try:
    __version__ = _version("fluksio")
except PackageNotFoundError:  # pragma: no cover - a checkout that was never installed
    __version__ = "0.0.0+unknown"

_OUTSIDE = (
    "fluksio.{name}() only works inside a node: the worker running it installs "
    "the real one. There is nothing to {verb} out here."
)


def emit(**ports: Any) -> None:
    """Publish values on a node's declared output ports, mid-run."""
    raise RuntimeError(_OUTSIDE.format(name="emit", verb="emit to"))


def save_artifact(
    source: Any, name: str = "", media_type: str = "application/octet-stream"
) -> dict[str, Any]:
    """Put bytes in the artifact store and return a reference to them."""
    raise RuntimeError(_OUTSIDE.format(name="save_artifact", verb="save to"))


def load_artifact(ref: dict[str, Any]) -> bytes:
    """Read back what an artifact reference points at."""
    raise RuntimeError(_OUTSIDE.format(name="load_artifact", verb="load from"))