endstone-papi 0.2.0__cp315-cp315-win_amd64.whl

endstone_papi/__init__.py

@@ -0,0 +1,59 @@
+"""Endstone PlaceholderAPI.
+
+A native C++20 PlaceholderAPI framework for Endstone and Minecraft Bedrock
+Dedicated Server.  Provides a bracket placeholder parser, an owner-aware
+expansion registry, and a service that resolves ``{identifier:params}``
+placeholders through expansions supplied by C++ or Python plugins.
+"""
+
+
+# start delvewheel patch
+def _delvewheel_patch_1_13_1():
+    import os
+    if os.path.isdir(libs_dir := os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir, 'endstone_papi.libs'))):
+        os.add_dll_directory(libs_dir)
+
+
+_delvewheel_patch_1_13_1()
+del _delvewheel_patch_1_13_1
+# end delvewheel patch
+
+# Load PAPI's native extension before Endstone's Python bindings so provider
+# exceptions are translated by the module that owns them.
+try:
+    from ._native_loader import load_native as _load_native
+    from ._native_loader import should_use_shadow as _should_use_shadow
+
+    if _should_use_shadow(__file__):
+        _load_native(__name__, __file__)
+
+    from ._papi import (
+        SERVICE_NAME,
+        ExpansionInfo,
+        ExpansionRegisteredEvent,
+        ExpansionUnregisteredEvent,
+        PlaceholderAPI,
+        PlaceholderExpansion,
+        UnregisterReason,
+        __version__,
+    )
+except ImportError as _e:
+    raise ImportError(
+        f"Failed to load the native PAPI extension: {_e}. "
+        "PAPI requires Endstone >=0.11.8,<0.12 (API 0.11). "
+        "After updating PAPI or Endstone, restart the server before trying again."
+    ) from _e
+
+from .plugin import PlaceholderAPIPlugin
+
+__all__ = [
+    "SERVICE_NAME",
+    "ExpansionInfo",
+    "ExpansionRegisteredEvent",
+    "ExpansionUnregisteredEvent",
+    "PlaceholderAPI",
+    "PlaceholderAPIPlugin",
+    "PlaceholderExpansion",
+    "UnregisterReason",
+    "__version__",
+]

endstone_papi/_native_loader.py

@@ -0,0 +1,185 @@
+"""Windows content-addressed loading for the native PAPI extension."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.machinery
+import importlib.util
+import os
+import re
+import sys
+import types
+from pathlib import Path
+
+PERSISTENT_MODULE_NAME = "_endstone_papi_native._papi"
+PERSISTENT_DIGEST_ATTRIBUTE = "_papi_payload_sha256"
+_PERSISTENT_PARENT_NAME = "_endstone_papi_native"
+_PACKAGE_SUFFIX = ("plugins", ".local", "Lib", "site-packages", "endstone_papi")
+_RESTART_REQUIRED = "native binary changed while server runs; restart server to apply update"
+_SHADOW_TARGET_RE = re.compile(r"endstone_papi-[0-9a-f]{64}\.pyd\Z", re.IGNORECASE)
+
+
+def _package_dir(package_path: str | os.PathLike[str]) -> Path:
+    path = Path(package_path)
+    if path.name == "__init__.py" or (path.suffix and not path.is_dir()):
+        path = path.parent
+    return path.resolve()
+
+
+def shadow_root(package_path: str | os.PathLike[str]) -> Path | None:
+    """Return the Endstone local-plugin root for an eligible package path."""
+    package_dir = _package_dir(package_path)
+    expected = tuple(part.casefold() for part in _PACKAGE_SUFFIX)
+    actual = tuple(part.casefold() for part in package_dir.parts[-len(expected) :])
+    if actual != expected:
+        return None
+    return package_dir.parents[2]
+
+
+def should_use_shadow(package_path: str | os.PathLike[str]) -> bool:
+    return os.name == "nt" and shadow_root(package_path) is not None
+
+
+def _find_native_payload(package_dir: Path) -> Path:
+    matches: list[Path] = []
+    seen: set[str] = set()
+    for suffix in importlib.machinery.EXTENSION_SUFFIXES:
+        candidate = package_dir / f"_papi{suffix}"
+        key = str(candidate).casefold()
+        if key in seen or not candidate.is_file():
+            continue
+        seen.add(key)
+        matches.append(candidate)
+
+    if not matches:
+        suffixes = ", ".join(importlib.machinery.EXTENSION_SUFFIXES)
+        raise ImportError(f"could not find packaged native PAPI payload (_papi + one of: {suffixes})")
+    if len(matches) != 1:
+        names = ", ".join(str(path) for path in matches)
+        raise ImportError(f"ambiguous packaged native PAPI payloads: {names}")
+    return matches[0]
+
+
+def _payload_digest(payload: bytes) -> str:
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _target_path(root: Path, digest: str) -> Path:
+    return root / f"endstone_papi-{digest}.pyd"
+
+
+def _ensure_shadow_copy(target: Path, payload: bytes, digest: str) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        stream = target.open("xb")
+    except FileExistsError:
+        try:
+            existing = target.read_bytes()
+        except OSError as error:
+            raise ImportError(f"could not verify existing native shadow target {target}") from error
+        if _payload_digest(existing) != digest:
+            raise ImportError(f"existing native shadow target does not match payload digest: {target}")
+        return
+
+    try:
+        with stream:
+            stream.write(payload)
+            stream.flush()
+    except Exception as error:
+        try:
+            target.unlink()
+        except OSError:
+            pass
+        raise ImportError(f"failed to create native shadow target {target}") from error
+
+
+def _make_persistent_parent() -> tuple[types.ModuleType, bool]:
+    existing = sys.modules.get(_PERSISTENT_PARENT_NAME)
+    if existing is not None:
+        if not isinstance(existing, types.ModuleType):
+            raise ImportError(f"persistent native namespace is not a module: {_PERSISTENT_PARENT_NAME}")
+        return existing, False
+
+    parent = types.ModuleType(_PERSISTENT_PARENT_NAME)
+    parent.__path__ = []
+    parent.__package__ = _PERSISTENT_PARENT_NAME
+    sys.modules[_PERSISTENT_PARENT_NAME] = parent
+    return parent, True
+
+
+def _execute_extension(target: Path) -> types.ModuleType:
+    loader = importlib.machinery.ExtensionFileLoader(PERSISTENT_MODULE_NAME, str(target))
+    spec = importlib.util.spec_from_file_location(PERSISTENT_MODULE_NAME, str(target), loader=loader)
+    if spec is None:
+        raise ImportError(f"could not create import spec for native PAPI payload: {target}")
+
+    parent, parent_created = _make_persistent_parent()
+    module: types.ModuleType | None = None
+    try:
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[PERSISTENT_MODULE_NAME] = module
+        loader.exec_module(module)
+        return module
+    except BaseException:
+        if module is not None and sys.modules.get(PERSISTENT_MODULE_NAME) is module:
+            del sys.modules[PERSISTENT_MODULE_NAME]
+        if parent_created and sys.modules.get(_PERSISTENT_PARENT_NAME) is parent:
+            del sys.modules[_PERSISTENT_PARENT_NAME]
+        raise
+
+
+def _cleanup_stale_targets(root: Path, current: Path) -> None:
+    current_key = str(current.absolute()).casefold()
+    try:
+        candidates = root.glob("endstone_papi-*.pyd")
+        for candidate in candidates:
+            if _SHADOW_TARGET_RE.fullmatch(candidate.name) is None:
+                continue
+            if str(candidate.absolute()).casefold() == current_key:
+                continue
+            try:
+                candidate.unlink()
+            except OSError:
+                pass
+    except OSError:
+        pass
+
+
+def _mismatch_error() -> ImportError:
+    return ImportError(_RESTART_REQUIRED)
+
+
+def load_native(package_name: str, package_path: str | os.PathLike[str]) -> types.ModuleType:
+    """Load and alias the native extension for an eligible Windows package."""
+    package_dir = _package_dir(package_path)
+    root = shadow_root(package_dir)
+    if os.name != "nt" or root is None:
+        raise ImportError("native shadow loading is only available for Endstone local plugins on Windows")
+
+    source = _find_native_payload(package_dir)
+    payload = source.read_bytes()
+    digest = _payload_digest(payload)
+
+    persistent = sys.modules.get(PERSISTENT_MODULE_NAME)
+    if persistent is not None:
+        if getattr(persistent, PERSISTENT_DIGEST_ATTRIBUTE, None) != digest:
+            raise _mismatch_error()
+        module = persistent
+    else:
+        target = _target_path(root, digest)
+        _ensure_shadow_copy(target, payload, digest)
+        module = _execute_extension(target)
+        _make_persistent_parent()
+        sys.modules[PERSISTENT_MODULE_NAME] = module
+        setattr(module, PERSISTENT_DIGEST_ATTRIBUTE, digest)
+        _cleanup_stale_targets(root, target)
+
+    alias_name = f"{package_name}._papi"
+    sys.modules[alias_name] = module
+    package = sys.modules.get(package_name)
+    if package is not None:
+        package._papi = module
+    parent = sys.modules.get(_PERSISTENT_PARENT_NAME)
+    if parent is not None:
+        parent._papi = module
+    return module

endstone_papi/_papi.pyi

@@ -0,0 +1,215 @@
+"""Type stubs for the native PlaceholderAPI core."""
+
+import enum
+
+from endstone import OfflinePlayer, Player
+from endstone.event import Event
+from endstone.plugin import Plugin, Service, ServiceManager
+
+__all__ = [
+    "SERVICE_NAME",
+    "ExpansionInfo",
+    "ExpansionRegisteredEvent",
+    "ExpansionUnregisteredEvent",
+    "PlaceholderAPI",
+    "PlaceholderExpansion",
+    "UnregisterReason",
+    "__version__",
+]
+
+__version__: str
+
+SERVICE_NAME: str
+
+class UnregisterReason(enum.Enum):
+    """Why an expansion was removed from the registry."""
+
+    EXPLICIT = 0
+    OWNER_DISABLED = 1
+    REQUIRED_PLUGIN_DISABLED = 2
+    PAPI_SHUTDOWN = 3
+
+class ExpansionInfo:
+    """An immutable copy of a registered expansion's metadata.
+
+    Stays valid and unchanged after the expansion it describes is unregistered and
+    destroyed. It holds no reference to the expansion, its owner, or the registry.
+    """
+
+    @property
+    def identifier(self) -> str:
+        """The canonical, lowercase identifier."""
+
+    @property
+    def name(self) -> str:
+        """The expansion's display name."""
+
+    @property
+    def author(self) -> str:
+        """The expansion's author."""
+
+    @property
+    def version(self) -> str:
+        """The expansion's version."""
+
+    @property
+    def owner(self) -> str:
+        """The name of the plugin that registered the expansion."""
+
+    @property
+    def required_plugin(self) -> str | None:
+        """The plugin the expansion requires, or None."""
+
+    @property
+    def relational(self) -> bool:
+        """Whether the expansion handles relational placeholders."""
+
+class PlaceholderExpansion:
+    """Base class for placeholder providers.
+
+    Subclass this and register it through the PlaceholderAPI service. C++ and Python
+    expansions share one registry, so a consumer never learns which language a
+    provider was written in.
+
+    Metadata is read once at registration and copied, so an implementation must report
+    stable values. Arguments are borrowed for the duration of a call only; do not keep
+    the player past the callback.
+    """
+
+    def __init__(self) -> None: ...
+    @property
+    def identifier(self) -> str:
+        """The identifier this expansion answers to.
+
+        Must match ``[A-Za-z0-9][A-Za-z0-9-]*``, and is canonicalized to lowercase.
+        The colon separates the identifier from parameters. Dots and underscores may
+        be used in parameters, but are not allowed in an identifier.
+        """
+
+    @property
+    def author(self) -> str:
+        """The expansion's author. Must not be empty."""
+
+    @property
+    def version(self) -> str:
+        """The expansion's version. Must not be empty."""
+
+    @property
+    def name(self) -> str:
+        """The expansion's display name. Defaults to the identifier."""
+
+    @property
+    def required_plugin(self) -> str | None:
+        """The plugin this expansion requires, or None.
+
+        Matched case-sensitively. It must be enabled at registration, and the expansion
+        is removed automatically if it is later disabled.
+        """
+
+    def can_register(self) -> bool:
+        """Final chance to refuse registration. Defaults to True."""
+
+    def supports_relational_placeholders(self) -> bool:
+        """Whether ``on_relational_request`` is implemented. Defaults to False."""
+
+    def supports_player_cleanup(self) -> bool:
+        """Whether ``on_player_quit`` is implemented. Defaults to False."""
+
+    def on_request(self, player: OfflinePlayer | None, params: str) -> str | None:
+        """Resolves an ordinary ``{identifier:params}`` placeholder.
+
+        ``params`` contains everything after the first colon exactly as written.
+        Return a ``str``, or None to leave the placeholder text untouched. Any other
+        type is a provider error and is not coerced.
+        """
+
+    def on_relational_request(self, one: Player, two: Player, params: str) -> str | None:
+        """Resolves a relational ``{rel:identifier:params}`` placeholder.
+
+        ``params`` contains everything after the second colon exactly as written.
+        """
+
+    def on_player_quit(self, player: Player) -> None:
+        """Called when a player leaves, if this expansion opted into cleanup."""
+
+    def on_unregister(self, reason: UnregisterReason) -> None:
+        """Called once after this expansion has been removed from the registry."""
+
+class PlaceholderAPI(Service):
+    """Resolves placeholders through registered expansions.
+
+    Obtained from Endstone's service manager; it cannot be constructed or subclassed in
+    Python. A retained instance becomes permanently inert once PAPI is disabled:
+    ``active`` turns False, parsing returns its input unchanged, queries come back
+    empty, and mutations fail.
+
+    Parsing and register/unregister mutations require the primary server thread, and
+    provider callbacks execute there. ``contains_placeholders``, ``active``, and registry
+    queries that return copied state are safe from any thread.
+    """
+
+    @staticmethod
+    def load(service_manager: ServiceManager) -> PlaceholderAPI | None:
+        """Load the active PlaceholderAPI service, or None when it is unavailable."""
+
+    @property
+    def active(self) -> bool:
+        """Whether this service is still usable."""
+
+    def set_placeholders(self, player: OfflinePlayer | None, text: str) -> str:
+        """Replaces every resolvable ``{identifier:params}`` in text."""
+
+    def set_relational_placeholders(self, one: Player, two: Player, text: str) -> str:
+        """Replaces every resolvable ``{rel:identifier:params}`` in text."""
+
+    def contains_placeholders(self, text: str) -> bool:
+        """Whether text lexically contains a placeholder-shaped substring."""
+
+    def is_registered(self, identifier: str) -> bool:
+        """Whether an identifier currently has an expansion registered.
+
+        ``rel`` is reserved by relational syntax and cannot be registered.
+        """
+
+    @property
+    def registered_identifiers(self) -> tuple[str, ...]:
+        """Every registered identifier, sorted canonically."""
+
+    @property
+    def expansions(self) -> tuple[ExpansionInfo, ...]:
+        """Metadata for every registered expansion, sorted by identifier."""
+
+    def register_expansion(self, owner: Plugin, expansion: PlaceholderExpansion) -> bool:
+        """Registers an expansion on behalf of a plugin."""
+
+    def unregister_expansion(self, owner: Plugin, identifier: str) -> bool:
+        """Unregisters one expansion owned by a plugin."""
+
+    def unregister_expansions(self, owner: Plugin) -> int:
+        """Unregisters every expansion owned by a plugin."""
+
+class ExpansionRegisteredEvent(Event):
+    """Fired after an expansion has been added to the registry."""
+
+    @property
+    def expansion_info(self) -> ExpansionInfo:
+        """Metadata describing the expansion that was registered."""
+
+class ExpansionUnregisteredEvent(Event):
+    """Fired after an expansion has been removed from the registry."""
+
+    @property
+    def expansion_info(self) -> ExpansionInfo:
+        """Metadata describing the expansion that was removed."""
+
+    @property
+    def reason(self) -> UnregisterReason:
+        """Why the expansion was removed."""
+
+class _PapiBootstrap:
+    """Internal native lifecycle state owned by the PAPI plugin."""
+
+    def start(self, plugin: Plugin) -> bool: ...
+    def stop(self) -> None: ...
+    @property
+    def service(self) -> PlaceholderAPI | None: ...

endstone_papi/_toolchain_provenance.txt

@@ -0,0 +1,4 @@
+compiler_id=Clang
+compiler_version=20.1.8
+compiler_frontend=MSVC
+cxx_standard=20

endstone_papi/include/endstone_papi/events.h

@@ -0,0 +1,71 @@
+#pragma once
+
+#include <utility>
+
+#include <endstone/event/event.h>
+#include <endstone/event/server/server_event.h>
+
+#include "endstone_papi/expansion_info.h"
+#include "endstone_papi/unregister_reason.h"
+
+namespace papi {
+
+/**
+ * @brief Fired after an expansion has been added to the registry.
+ *
+ * Synchronous, non-cancellable, and dispatched after the registry has committed,
+ * so a listener querying PlaceholderAPI already observes the new expansion.
+ *
+ * Only copied metadata is exposed; the expansion object is never reachable from
+ * the event.
+ */
+class ExpansionRegisteredEvent : public endstone::ServerEvent {
+public:
+    ENDSTONE_EVENT(ExpansionRegisteredEvent);
+
+    explicit ExpansionRegisteredEvent(ExpansionInfo info) : info_(std::move(info)) {}
+
+    /**
+     * @brief Metadata describing the expansion that was registered.
+     */
+    [[nodiscard]] const ExpansionInfo &getExpansionInfo() const { return info_; }
+
+private:
+    ExpansionInfo info_;
+};
+
+/**
+ * @brief Fired after an expansion has been removed from the registry.
+ *
+ * Synchronous, non-cancellable, and dispatched after the registry has removed the
+ * entry and the expansion's cleanup callback has returned, so a listener querying
+ * PlaceholderAPI no longer observes the expansion.
+ *
+ * This event is suppressed during PAPI's own shutdown, because the event system
+ * and its listeners are being torn down at that point.
+ */
+class ExpansionUnregisteredEvent : public endstone::ServerEvent {
+public:
+    ENDSTONE_EVENT(ExpansionUnregisteredEvent);
+
+    ExpansionUnregisteredEvent(ExpansionInfo info, const UnregisterReason reason)
+        : info_(std::move(info)), reason_(reason)
+    {
+    }
+
+    /**
+     * @brief Metadata describing the expansion that was removed.
+     */
+    [[nodiscard]] const ExpansionInfo &getExpansionInfo() const { return info_; }
+
+    /**
+     * @brief Why the expansion was removed.
+     */
+    [[nodiscard]] UnregisterReason getReason() const { return reason_; }
+
+private:
+    ExpansionInfo info_;
+    UnregisterReason reason_;
+};
+
+}  // namespace papi

endstone_papi/include/endstone_papi/expansion_info.h

@@ -0,0 +1,54 @@
+#pragma once
+
+#include <optional>
+#include <string>
+
+namespace papi {
+
+/**
+ * @brief An immutable copy of a registered expansion's metadata.
+ *
+ * Instances are pure values. They contain no plugin pointer, expansion pointer,
+ * callback, or registry reference, so they stay valid and unchanged after the
+ * expansion they describe is unregistered and destroyed.
+ */
+struct ExpansionInfo {
+    /**
+     * @brief The canonical identifier, always ASCII lowercase.
+     */
+    std::string identifier;
+
+    /**
+     * @brief The human-readable name reported by the expansion.
+     */
+    std::string name;
+
+    /**
+     * @brief The author reported by the expansion.
+     */
+    std::string author;
+
+    /**
+     * @brief The version reported by the expansion.
+     */
+    std::string version;
+
+    /**
+     * @brief The name of the Endstone plugin that registered the expansion.
+     */
+    std::string owner;
+
+    /**
+     * @brief The plugin the expansion requires, if it declared one.
+     */
+    std::optional<std::string> required_plugin;
+
+    /**
+     * @brief Whether the expansion handles relational placeholders.
+     */
+    bool relational = false;
+
+    [[nodiscard]] friend bool operator==(const ExpansionInfo &, const ExpansionInfo &) = default;
+};
+
+}  // namespace papi

endstone_papi/include/endstone_papi/papi.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include "endstone_papi/events.h"
+#include "endstone_papi/expansion_info.h"
+#include "endstone_papi/placeholder_api.h"
+#include "endstone_papi/placeholder_expansion.h"
+#include "endstone_papi/unregister_reason.h"
+#include "endstone_papi/version.h"