pykardia 0.1.0.dev1__py3-none-any.whl

pykardia/__init__.py

@@ -0,0 +1,139 @@
+"""PyKardia: revertible effects and reactive services."""
+
+from pykardia import fs, guest, hmr, include, loader, logger_console, prelude, timer
+from pykardia.catalog import catalog
+from pykardia.core import (
+    AccessError,
+    AggregateError,
+    AlreadyProvided,
+    Check,
+    ConfigCommitted,
+    Context,
+    Deps,
+    Disposal,
+    Disposer,
+    EffectHandle,
+    EffectMeta,
+    EffectScope,
+    ErasedConfig,
+    Error,
+    Event,
+    Exporter,
+    Fiber,
+    FiberId,
+    FiberState,
+    ForeignBinding,
+    IdTable,
+    ImplId,
+    Inactive,
+    InactiveEffect,
+    Inject,
+    Injected,
+    Interrupted,
+    Issue,
+    JsonValue,
+    Key,
+    Level,
+    Logger,
+    Message,
+    NoConfig,
+    NotProvided,
+    Overlay,
+    Panicked,
+    PathSegment,
+    Plugin,
+    PluginDef,
+    PluginInserted,
+    PluginRemoved,
+    PyKardiaError,
+    RealmId,
+    Registry,
+    Replaced,
+    RuntimeKey,
+    Service,
+    ServiceChanged,
+    Settle,
+    StatusChanged,
+    Svc,
+    TypeMismatch,
+    Undeclared,
+    ValidationError,
+    decode,
+    hyphenate,
+    merge_shallow,
+)
+from pykardia.decorators import plugin, service
+from pykardia.version import __version__
+
+__all__: list[str] = [
+    "AccessError",
+    "AggregateError",
+    "AlreadyProvided",
+    "Check",
+    "ConfigCommitted",
+    "Context",
+    "Deps",
+    "Disposal",
+    "Disposer",
+    "EffectHandle",
+    "EffectMeta",
+    "EffectScope",
+    "ErasedConfig",
+    "Error",
+    "Event",
+    "Exporter",
+    "Fiber",
+    "FiberId",
+    "FiberState",
+    "ForeignBinding",
+    "IdTable",
+    "ImplId",
+    "Inactive",
+    "InactiveEffect",
+    "Inject",
+    "Injected",
+    "Interrupted",
+    "Issue",
+    "JsonValue",
+    "PyKardiaError",
+    "Key",
+    "Level",
+    "Logger",
+    "Message",
+    "NoConfig",
+    "NotProvided",
+    "Overlay",
+    "Panicked",
+    "PathSegment",
+    "Plugin",
+    "PluginDef",
+    "PluginInserted",
+    "PluginRemoved",
+    "RealmId",
+    "Registry",
+    "Replaced",
+    "RuntimeKey",
+    "Service",
+    "ServiceChanged",
+    "Settle",
+    "StatusChanged",
+    "Svc",
+    "TypeMismatch",
+    "Undeclared",
+    "ValidationError",
+    "__version__",
+    "catalog",
+    "decode",
+    "fs",
+    "guest",
+    "hmr",
+    "hyphenate",
+    "include",
+    "loader",
+    "logger_console",
+    "merge_shallow",
+    "plugin",
+    "prelude",
+    "service",
+    "timer",
+]

pykardia/__main__.py

@@ -0,0 +1,5 @@
+"""Module execution entry for the pykardia command-line application."""
+
+from pykardia.cli import main
+
+raise SystemExit(main())

pykardia/catalog.py

@@ -0,0 +1,17 @@
+"""Unified catalog for built-in plugins and their original Cordis package aliases."""
+
+from pykardia.fs import FsPlugin
+from pykardia.include import IncludePlugin
+from pykardia.loader import Catalog, builtins
+from pykardia.logger_console import ConsolePlugin
+from pykardia.timer import TimerPlugin
+
+
+def catalog() -> Catalog:
+    """Create a fresh catalog with all built-ins and no implicit HMR module graph."""
+    result = builtins()
+    result.register(TimerPlugin).alias("@cordisjs/plugin-timer", "timer")
+    result.register(ConsolePlugin).alias("@cordisjs/plugin-logger-console", "logger-console")
+    result.register(FsPlugin).alias("@cordisjs/plugin-fs-node", "fs")
+    result.register(IncludePlugin).alias("@cordisjs/plugin-include", "include")
+    return result

pykardia/cli.py

@@ -0,0 +1,103 @@
+"""Run a live file-backed pykardia application until Ctrl-C."""
+
+import asyncio
+import signal
+import sys
+from collections.abc import Awaitable
+from pathlib import Path
+from types import FrameType
+
+from pykardia.catalog import catalog
+from pykardia.core.context import Context
+from pykardia.core.plugin import PluginDef
+from pykardia.fs import FsPlugin
+from pykardia.hmr import DylibSource, Hmr, ModuleCode, ModuleGraph, ModuleSource, WasmSource
+from pykardia.loader import Catalog, Loader, Resolver
+from pykardia.logger_console import ConsoleConfig, ConsoleExporter
+
+
+def main() -> int:
+    """Start with the first path argument, defaulting to pykardia.yml."""
+    return asyncio.run(start(sys.argv[1] if len(sys.argv) > 1 else "pykardia.yml"))
+
+
+async def start(path: str) -> int:
+    """Report startup or cleanup errors through the app logger and return its exit status."""
+    root = Context()
+    status = 0
+    try:
+        await run(root, path)
+    except Exception as error:
+        root.logger_named("app").log_error(error)
+        status = 1
+    try:
+        await root.fiber().dispose()
+    except Exception as error:
+        root.logger_named("app").log_error(error)
+        status = 1
+    return status
+
+
+async def run(root: Context, path: str) -> None:
+    """Boot console, fs, loader and watched include in source order, then await Ctrl-C."""
+    root.add_exporter(ConsoleExporter(ConsoleConfig()))
+    root.plugin(FsPlugin, None)
+    plugins = catalog()
+    graph = ModuleGraph(GuestFiles())
+    plugins.register_def("hmr", Hmr.plugin(graph)).alias("@cordisjs/plugin-hmr", "hmr")
+    resolver = Plugins(plugins, graph, Path(path).absolute().parent)
+    await root.plugin_def(Loader.plugin(resolver)).settled()
+    loader = root.get(Loader).arc()
+    loader.set_logs(True)
+    id = await loader.create({"name": "include", "config": {"path": path, "watch": True}})
+    fiber = loader.resolve(id).inner_fiber()
+    if fiber is not None and (error := fiber.error()) is not None:
+        raise error
+    await interrupted()
+
+
+async def interrupted() -> None:
+    """Wait for Ctrl-C or Windows Ctrl-Break and restore the previous signal handlers."""
+    loop = asyncio.get_running_loop()
+    stopped = asyncio.Event()
+    signals = (signal.SIGINT, signal.SIGBREAK) if sys.platform == "win32" else (signal.SIGINT,)
+    previous = {number: signal.getsignal(number) for number in signals}
+
+    def stop(number: int, frame: FrameType | None) -> None:
+        """Wake the event loop even when it is waiting on Windows I/O."""
+        loop.call_soon_threadsafe(stopped.set)
+
+    for number in signals:
+        signal.signal(number, stop)
+    try:
+        await stopped.wait()
+    finally:
+        for number, handler in previous.items():
+            signal.signal(number, handler)
+
+
+class Plugins(Resolver):
+    """Resolve built-in names before loading guest paths relative to the root config file."""
+
+    def __init__(self, plugins: Catalog, graph: ModuleGraph, base: Path) -> None:
+        """Retain a shared catalog, module graph and lexical base directory."""
+        self.catalog, self.graph, self.base = plugins, graph, base
+
+    def resolve(self, name: str) -> Awaitable[PluginDef]:
+        """Snapshot built-ins or import the corresponding guest module."""
+        if self.catalog.get(name) is not None:
+            return self.catalog.resolve(name)
+        return self.graph.resolve(str(self.base / name))
+
+
+class GuestFiles(ModuleSource):
+    """Select WASM for .wasm/.wat and the native C ABI for other file extensions."""
+
+    def __init__(self) -> None:
+        """Retain one shared WASM engine and a native loader."""
+        self.wasm, self.dylib = WasmSource(), DylibSource()
+
+    def load(self, id: str) -> ModuleCode:
+        """Load the selected real backend without treating executables as CLI process guests."""
+        source = self.wasm if Path(id).suffix in (".wasm", ".wat") else self.dylib
+        return source.load(id)

pykardia/core/__init__.py

@@ -0,0 +1,103 @@
+"""Core runtime entry points."""
+
+from pykardia.core.cleanup import Disposal, Disposer
+from pykardia.core.config import ErasedConfig, Issue, NoConfig, PathSegment, ValidationError, decode
+from pykardia.core.context import Context, merge_shallow
+from pykardia.core.deps import Deps, Injected
+from pykardia.core.effect import EffectHandle, EffectMeta, EffectScope
+from pykardia.core.error import (
+    AccessError,
+    AggregateError,
+    AlreadyProvided,
+    Error,
+    ForeignBinding,
+    Inactive,
+    InactiveEffect,
+    Interrupted,
+    NotProvided,
+    Panicked,
+    PyKardiaError,
+    TypeMismatch,
+    Undeclared,
+)
+from pykardia.core.events import (
+    ConfigCommitted,
+    Event,
+    PluginInserted,
+    PluginRemoved,
+    Replaced,
+    ServiceChanged,
+    StatusChanged,
+)
+from pykardia.core.fiber import Fiber, Settle
+from pykardia.core.id_table import IdTable
+from pykardia.core.key import FiberId, ImplId, Key, RealmId
+from pykardia.core.logger import Exporter, Level, Logger, Message, hyphenate
+from pykardia.core.plugin import Inject, Plugin, PluginDef, RuntimeKey
+from pykardia.core.registry import Registry
+from pykardia.core.scope import Overlay
+from pykardia.core.service import Service, Svc
+from pykardia.core.state import Check
+from pykardia.core.status import FiberState
+from pykardia.core.value import JsonValue
+
+__all__: list[str] = [
+    "AccessError",
+    "AggregateError",
+    "AlreadyProvided",
+    "Check",
+    "ConfigCommitted",
+    "Context",
+    "Deps",
+    "Disposal",
+    "Disposer",
+    "EffectHandle",
+    "EffectMeta",
+    "EffectScope",
+    "ErasedConfig",
+    "Error",
+    "Event",
+    "Exporter",
+    "Fiber",
+    "FiberId",
+    "FiberState",
+    "ForeignBinding",
+    "IdTable",
+    "ImplId",
+    "Inactive",
+    "InactiveEffect",
+    "Inject",
+    "Injected",
+    "Interrupted",
+    "Issue",
+    "JsonValue",
+    "PyKardiaError",
+    "Key",
+    "Level",
+    "Logger",
+    "Message",
+    "NoConfig",
+    "NotProvided",
+    "Overlay",
+    "Panicked",
+    "PathSegment",
+    "Plugin",
+    "PluginDef",
+    "PluginInserted",
+    "PluginRemoved",
+    "RealmId",
+    "Registry",
+    "Replaced",
+    "RuntimeKey",
+    "Service",
+    "ServiceChanged",
+    "Settle",
+    "StatusChanged",
+    "Svc",
+    "TypeMismatch",
+    "Undeclared",
+    "ValidationError",
+    "decode",
+    "hyphenate",
+    "merge_shallow",
+]

pykardia/core/cleanup.py

@@ -0,0 +1,128 @@
+"""Reversible actions with a synchronous prefix and sequential LIFO cleanup."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Generator
+from typing import Protocol
+
+from pykardia.core.runtime import Completion, Runtime
+
+
+class Disposal:
+    """Observe cleanup that has already started and proceeds without its observer."""
+
+    def __init__(self, completion: Completion[None]) -> None:
+        """Wrap the runtime-owned result of a cleanup sequence."""
+        self._completion = completion
+        self._consumed = False
+
+    def is_ready(self) -> bool:
+        """Return whether cleanup finished synchronously, even after async completion."""
+        return self._completion.is_ready()
+
+    def _take_ready(self) -> None:
+        """Consume a synchronous result, matching Disposal::Ready's one-shot result."""
+        if not self._consumed:
+            self._consumed = True
+            self._completion.result()
+
+    async def wait(self) -> None:
+        """Observe cleanup without propagating waiter cancellation into its task."""
+        if self.is_ready():
+            self._take_ready()
+        else:
+            await self._completion
+
+    def __await__(self) -> Generator[object, None, None]:
+        """Wait for the cleanup's result."""
+        return self.wait().__await__()
+
+
+class Disposable(Protocol):
+    """An effect handle whose inverse can join another cleanup sequence."""
+
+    def dispose(self) -> Disposal:
+        """Start cleanup and return its completion."""
+        ...
+
+
+class Disposer:
+    """An inverse consumed at most once; its callback runs when disposal starts."""
+
+    def __init__(self, action: Callable[[], Awaitable[None] | None]) -> None:
+        """Retain a callback that may finish immediately or return asynchronous work."""
+        self._action: Callable[[], Awaitable[None] | None] | None = action
+
+    @classmethod
+    def new(cls, action: Callable[[], None]) -> Disposer:
+        """Create a synchronous inverse; exceptions become cleanup failures."""
+        return cls(action)
+
+    fallible = new
+
+    @classmethod
+    def future(cls, action: Callable[[], Awaitable[None]]) -> Disposer:
+        """Create an asynchronous inverse with a synchronously invoked factory."""
+        return cls(action)
+
+    try_future = future
+
+    @classmethod
+    def from_handle(cls, handle: Disposable) -> Disposer:
+        """Adopt a nested handle without turning synchronous cleanup asynchronous."""
+        return cls(handle.dispose)
+
+    def call(self) -> Awaitable[None] | None:
+        """Consume the inverse and return only its unfinished asynchronous portion."""
+        action, self._action = self._action, None
+        if action is None:
+            return None
+        result = action()
+        if isinstance(result, Disposal) and result.is_ready():
+            result._take_ready()
+            return None
+        return result
+
+
+def run_sequence(runtime: Runtime, disposers: list[Disposer]) -> Disposal:
+    """Run inverses newest first, continuing after failures and reporting the first.
+
+    Synchronous callbacks run before this function returns. From the first awaitable
+    onward, the runtime owns a task which runs the remainder strictly in sequence.
+    """
+    rest = list(disposers)
+    first_error: BaseException | None = None
+    while rest:
+        try:
+            pending = rest.pop().call()
+        except (Exception, asyncio.CancelledError) as error:
+            if first_error is None:
+                first_error = error
+            continue
+        if pending is not None:
+            return Disposal(runtime.spawn(_finish_sequence(pending, rest, first_error)))
+    return Disposal(
+        Completion.ready(None) if first_error is None else Completion.failed(first_error)
+    )
+
+
+async def _finish_sequence(
+    pending: Awaitable[None], rest: list[Disposer], first_error: BaseException | None
+) -> None:
+    """Finish the first pending inverse, then run all remaining inverses in order."""
+    try:
+        await pending
+    except (Exception, asyncio.CancelledError) as error:
+        if first_error is None:
+            first_error = error
+    while rest:
+        try:
+            following = rest.pop().call()
+            if following is not None:
+                await following
+        except (Exception, asyncio.CancelledError) as error:
+            if first_error is None:
+                first_error = error
+    if first_error is not None:
+        raise first_error