polyplug-abi 0.1.0__py3-none-any.whl

polyplug_abi/__init__.py

@@ -0,0 +1,159 @@
+"""polyplug_abi — ABI types for the polyplug plugin runtime.
+
+This package provides the frozen ABI types that match the Rust ABI exactly.
+"""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from typing import Optional
+
+from polyplug_abi.abi import (
+    POLYPLUG_ABI_VERSION,
+    AbiErrorCode,
+    Compatibility,
+    StringView,
+    Buffer,
+    Version,
+    AbiError,
+    GuestContractHandle,
+    GuestContractInstance,
+    HostContractInstance,
+    HostContractInterface,
+    VmLoaderData,
+    NativeDispatch,
+    VmDispatch,
+    GuestContractInterface,
+    HostApi,
+    PluginDescriptor,
+    BundleInitContext,
+    Array,
+    DependencyInfo,
+    RuntimeConfig,
+    DispatchType,
+    DispatchMechanisms,
+    ArenaOverflowBlock,
+    CallArena,
+    LogLevel,
+    fnv1a_64,
+    guest_contract_id,
+    host_contract_id,
+    bundle_id,
+    FNV_OFFSET,
+    FNV_PRIME,
+)
+from polyplug_abi.string_view_helper import (
+    to_str,
+    strip_prefix,
+    starts_with,
+    ends_with,
+    split,
+    bytes_as_view,
+)
+
+
+class ReloadPhaseType(IntEnum):
+    """Type tag for ReloadPhase variants."""
+
+    Preparing = 0
+    Reloaded = 1
+    Failed = 2
+    Unloading = 3
+
+
+class ReloadPhase:
+    """Python representation of hot-reload phase notification.
+
+    Mirrors the ABI ``ReloadPhase`` struct exactly — there is no retry-count
+    field in the ABI.
+
+    Attributes:
+        type: The phase type (Preparing, Reloaded, Failed, or Unloading), or
+            the raw ``int`` discriminant when the runtime reports a phase this
+            SDK version does not know (the conversion is total — see
+            ``polyplug.runtime``).
+        bundle_id: The FNV-1a hash of the bundle name.
+        bundle_name: The human-readable bundle name.
+        reason: Failure reason string (valid only for Failed).
+    """
+
+    def __init__(
+        self,
+        type: ReloadPhaseType | int,
+        bundle_id: int,
+        bundle_name: str,
+        reason: Optional[str] = None,
+    ) -> None:
+        self.type: ReloadPhaseType | int = type
+        self.bundle_id: int = bundle_id
+        self.bundle_name: str = bundle_name
+        self.reason: Optional[str] = reason
+
+    def is_preparing(self) -> bool:
+        """Return True if this is a Preparing phase."""
+        return self.type == ReloadPhaseType.Preparing
+
+    def is_reloaded(self) -> bool:
+        """Return True if this is a Reloaded phase."""
+        return self.type == ReloadPhaseType.Reloaded
+
+    def is_failed(self) -> bool:
+        """Return True if this is a Failed phase."""
+        return self.type == ReloadPhaseType.Failed
+
+    def is_unloading(self) -> bool:
+        """Return True if this is an Unloading phase."""
+        return self.type == ReloadPhaseType.Unloading
+
+    def __repr__(self) -> str:
+        type_name: str = (
+            self.type.name
+            if isinstance(self.type, ReloadPhaseType)
+            else f"Unknown({self.type})"
+        )
+        return (
+            f"ReloadPhase(type={type_name}, bundle_id={self.bundle_id}, "
+            f"bundle_name={self.bundle_name!r}, reason={self.reason!r})"
+        )
+
+
+__all__ = [
+    "POLYPLUG_ABI_VERSION",
+    "AbiErrorCode",
+    "Compatibility",
+    "StringView",
+    "Buffer",
+    "Version",
+    "AbiError",
+    "GuestContractHandle",
+    "GuestContractInstance",
+    "HostContractInstance",
+    "HostContractInterface",
+    "VmLoaderData",
+    "NativeDispatch",
+    "VmDispatch",
+    "GuestContractInterface",
+    "HostApi",
+    "PluginDescriptor",
+    "BundleInitContext",
+    "Array",
+    "DependencyInfo",
+    "RuntimeConfig",
+    "DispatchType",
+    "DispatchMechanisms",
+    "LogLevel",
+    "fnv1a_64",
+    "guest_contract_id",
+    "host_contract_id",
+    "bundle_id",
+    "FNV_OFFSET",
+    "FNV_PRIME",
+    "ReloadPhaseType",
+    "ReloadPhase",
+    "to_str",
+    "strip_prefix",
+    "starts_with",
+    "ends_with",
+    "split",
+    "bytes_as_view",
+]

polyplug_abi/abi.py

@@ -0,0 +1,7 @@
+# Re-export all types from the auto-generated abi module.
+# The canonical file is at sdks/python/abi/abi.py.
+# This shared package makes the types available via `from polyplug_abi import ...`.
+try:
+    from abi.abi import *  # noqa: F401,F403
+except ImportError:
+    from polyplug.abi.abi import *  # noqa: F401,F403

polyplug_abi/string_view_helper.py

@@ -0,0 +1,113 @@
+"""polyplug_abi — String helper functions for StringView."""
+
+from __future__ import annotations
+
+import ctypes
+
+from polyplug_abi.abi import StringView
+
+
+def to_str(sv: StringView) -> str:
+    """Convert StringView to Python str.
+
+    A null/zero-length view decodes to ``""``. A non-null view whose bytes are
+    NOT valid UTF-8 raises ``UnicodeDecodeError`` — the strict ``bytes.decode``
+    never silently substitutes replacement characters for a readable-but-invalid
+    view.
+
+    Args:
+        sv: StringView from polyplug ABI
+
+    Returns:
+        Python string (UTF-8 decoded)
+
+    Raises:
+        UnicodeDecodeError: if the viewed bytes are not valid UTF-8.
+    """
+    if not sv.ptr or sv.len == 0:
+        return ""
+    data = ctypes.cast(sv.ptr, ctypes.POINTER(ctypes.c_char * sv.len)).contents
+    return bytes(data).decode("utf-8")
+
+
+def strip_prefix(sv: StringView, prefix: str) -> str:
+    """Strip prefix from StringView if present, otherwise return original string.
+
+    Args:
+        sv: StringView from polyplug ABI
+        prefix: Prefix string to strip
+
+    Returns:
+        String with prefix removed if it was present, otherwise original string
+    """
+    s: str = to_str(sv)
+    if s.startswith(prefix):
+        return s[len(prefix) :]
+    return s
+
+
+def starts_with(sv: StringView, prefix: str) -> bool:
+    """Check if StringView starts with prefix.
+
+    Args:
+        sv: StringView from polyplug ABI
+        prefix: Prefix string to check for
+
+    Returns:
+        True if the string starts with the prefix, False otherwise
+    """
+    return to_str(sv).startswith(prefix)
+
+
+def ends_with(sv: StringView, suffix: str) -> bool:
+    """Check if StringView ends with suffix.
+
+    Args:
+        sv: StringView from polyplug ABI
+        suffix: Suffix string to check for
+
+    Returns:
+        True if the string ends with the suffix, False otherwise
+    """
+    return to_str(sv).endswith(suffix)
+
+
+def split(sv: StringView, delimiter: str) -> list[str]:
+    """Split StringView by a literal delimiter, keeping empty segments.
+
+    Args:
+        sv: StringView from polyplug ABI
+        delimiter: Literal delimiter string to split by
+
+    Returns:
+        [] for a null/empty view, [s] for an empty delimiter, otherwise the
+        segments around every occurrence of the delimiter (empties kept)
+    """
+    s: str = to_str(sv)
+    if not s:
+        return []
+    if not delimiter:
+        return [s]
+    return s.split(delimiter)
+
+
+def bytes_as_view(data: bytes) -> StringView:
+    """Build a borrowed ``StringView`` over a bytes object's internal buffer.
+
+    The caller MUST keep ``data`` alive for as long as the view is read —
+    ctypes does not root ``data`` through the view's raw pointer field. Bind
+    the bytes to a local (or other owner) that outlives every read of the
+    view; never build a view over a temporary such as ``s.encode("utf-8")``
+    passed inline. Empty bytes produce a null view (``ptr=None, len=0``),
+    which is legal at the ABI boundary.
+
+    Args:
+        data: caller-owned UTF-8 bytes backing the view.
+
+    Returns:
+        StringView borrowing ``data``'s buffer (null view for empty bytes).
+    """
+    if not data:
+        return StringView(ptr=None, len=0)
+    addr: int = ctypes.cast(ctypes.c_char_p(data), ctypes.c_void_p).value or 0
+    return StringView(ptr=addr, len=len(data))

polyplug_abi-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: polyplug-abi
+Version: 0.1.0
+Summary: ABI types for the polyplug plugin runtime
+License: MIT
+Project-URL: Homepage, https://github.com/polyplug/polyplug
+Project-URL: Documentation, https://github.com/polyplug/polyplug#readme
+Project-URL: Repository, https://github.com/polyplug/polyplug.git
+Project-URL: Issues, https://github.com/polyplug/polyplug/issues
+Keywords: polyplug,plugin,abi,ffi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10

polyplug_abi-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+polyplug_abi/__init__.py,sha256=dTRrlkjV-bNNJOyQZlZyQWwYsXlgcZatAUen06ajjic,3900
+polyplug_abi/abi.py,sha256=QvQU9B2RkisfI5tdqqatzwdy-mIkThNdwdO90T8DDw0,317
+polyplug_abi/string_view_helper.py,sha256=3y2mrMSK_NEwo9C9owBZfZq7kulHu0yOW7KMOB_x0Ww,3360
+polyplug_abi-0.1.0.dist-info/METADATA,sha256=ur6AbfSniHhP0YSNLl9kVqHTOugIvAFuQWszHhScPNg,860
+polyplug_abi-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+polyplug_abi-0.1.0.dist-info/top_level.txt,sha256=2KW-836oU-A4B48jcweB0U_kpBVU9kHqp2S6C1wL7uY,13
+polyplug_abi-0.1.0.dist-info/RECORD,,

polyplug_abi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

polyplug_abi-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+polyplug_abi