prc-client 1.1.0__py3-none-any.whl

prc/__init__.py

@@ -0,0 +1,13 @@
+"""`prc-client`: A flexible, feature-rich Python API client for the ER:LC private server API."""
+
+from . import v1, v2, utils, exceptions
+from .users import FullUser, UsernameUser, IdUser
+from .command import cmd
+
+__all__ = [
+    "v1", "v2", "utils", "exceptions",
+    "FullUser", "UsernameUser", "IdUser", "cmd"
+]
+
+import logging
+logging.getLogger(__name__).addHandler(logging.NullHandler())

prc/base_client.py

@@ -0,0 +1,263 @@
+from typing import Literal, Self, cast, TYPE_CHECKING
+import logging
+import threading
+import time
+import asyncio
+import httpx
+
+from .policy import CommandPolicy
+from .v2.models import Endpoint as V2Endpoint
+from .v1.models import Endpoint as V1Endpoint
+from .exceptions import ApiError, RateLimited, DeserializationError
+
+if TYPE_CHECKING:
+    from .v2.client import AsyncClient as V2AsyncClient, Client as V2Client
+    from .v1.client import AsyncClient as V1AsyncClient, Client as V1Client
+
+logger = logging.getLogger(__name__)
+
+type ClientType = "V2AsyncClient | V2Client | V1AsyncClient | V1Client"
+type HTTPXClient = httpx.Client | httpx.AsyncClient
+type EndpointType = V1Endpoint | V2Endpoint
+
+def create_async_client(server_key: str, **kwargs) -> httpx.AsyncClient:
+    logger.debug("Creating new async HTTPX client.")
+    return httpx.AsyncClient(
+        base_url="https://api.erlc.gg/",
+        headers={"server-key": server_key},
+        **kwargs
+    )
+    
+def create_sync_client(server_key: str, **kwargs) -> httpx.Client:
+    logger.debug("Creating new sync HTTPX client.")
+    return httpx.Client(
+        base_url="https://api.erlc.gg/",
+        headers={"server-key": server_key},
+        **kwargs
+    )
+
+class _AsyncContext:
+    server_key: str
+    connection: HTTPXClient | None
+
+    async def __aenter__(self) -> Self:
+        self.connection = create_async_client(self.server_key)
+        return self
+    
+    async def __aexit__(self, exc_type, exc, tb):
+        if self.connection and not self.connection.is_closed:
+            # use cast here because the context manager ensures AsyncClient
+            await cast(httpx.AsyncClient, self.connection).aclose()
+        self.connection = None
+        self.closed = True
+
+class _SyncContext:
+    server_key: str
+    connection: HTTPXClient | None
+
+    def __enter__(self) -> Self:
+        self.connection = create_sync_client(self.server_key)
+        return self
+    
+    def __exit__(self, exc_type, exc, tb):
+        if self.connection and not self.connection.is_closed:
+            # use cast here because the context manager ensures Client
+            cast(httpx.Client, self.connection).close()
+        self.connection = None
+        self.closed = True
+
+class _BaseApiClient(_SyncContext, _AsyncContext):
+    def __init__(self,
+        server_key: str,
+        *,
+        policy: CommandPolicy | None = None,
+        wait_for_rate_limit: bool = True,
+        connection: HTTPXClient | None = None
+    ) -> None:
+        """
+        Parameters
+        ----------
+        server_key: `str`
+            The private server API key.
+        policy: `CommandPolicy` | `None` (optional)
+            The optional command policy to use to validate commands. Raises `CommandPolicyViolation` on violations.
+        rate_limit_config: `RateLimitConfig` (optional)
+            The rate limit configuration for this client. Defaults to safe values.
+        connection: `HTTPXClient` | `None` (optional)
+            An existing HTTPX client to use. If not provided, a new one will be created.
+        """
+        # prevent circular import
+        from .v2.client import AsyncClient as V2AsyncClient
+        from .v1.client import AsyncClient as V1AsyncClient
+        
+        self.server_key: str = server_key
+        self.policy = policy
+        self.wait_for_rate_limit = wait_for_rate_limit
+        self.connection: HTTPXClient | None = connection
+        self.closed: bool = False
+        self.is_async: bool = issubclass(type(self), (V2AsyncClient, V1AsyncClient))
+        
+        # rate limit tracking attributes, updated on each request based on response headers
+        self.post_expiration: int = int(time.time())
+        self.get_remaining: int = 0
+        self.get_expiration: int = int(time.time())
+        
+        if self.is_async:
+            self.lock = asyncio.Lock()
+        else:
+            self.lock = threading.Lock()
+    
+    def _raise_for_status(self, resp: httpx.Response):
+        body = resp.json()
+        if resp.status_code == 429:
+            logger.error("Currently being rate-limited by PRC.", extra={"body": body})
+            try:
+                raise RateLimited.from_dict(body)
+            except DeserializationError:
+                raise RateLimited(
+                    code=429,
+                    message="API call failed (rate limited by PRC - unknown refresh_after).",
+                    retry_after=0.0
+                )
+                
+        if resp.status_code != 200:
+            try:
+                logger.error("API call failed with non-200 status code.", extra={"body": body})
+                raise ApiError.from_dict(body)
+            except DeserializationError:
+                logger.error(
+                    "API call failed with non-200 status code %s.",
+                    resp.status_code,
+                    extra={"code": resp.status_code}
+                )
+                raise ApiError(code=resp.status_code, message="API call failed (status not 200).")
+            
+    def _update_ratelimit(self, resp: httpx.Response):
+        headers = resp.headers
+        
+        limit_remaining = headers.get("x-ratelimit-remaining")
+        limit_expiration = headers.get("x-ratelimit-reset")
+        
+        if resp.request.method == "GET":
+            self.get_remaining = int(limit_remaining) or self.get_remaining
+            self.get_expiration = int(limit_expiration) or self.get_expiration
+        else:
+            self.post_expiration = int(limit_expiration) or self.post_expiration
+        
+        logger.debug("Updated rate limit info.", extra={
+            "get_remaining": self.get_remaining,
+            "get_expiration": self.get_expiration,
+            "post_expiration": self.post_expiration
+        })
+            
+    def _get_method(self, endpoint: EndpointType) -> Literal["GET", "POST"]:
+        if isinstance(endpoint, V2Endpoint):
+            return "GET" if endpoint == V2Endpoint.v2_server else "POST"
+        else:
+            return "POST" if endpoint == V1Endpoint.command else "GET"
+        
+    async def _send_async_request(self, endpoint: EndpointType, **kwargs) -> httpx.Response:
+        if self.connection is None and self.closed:
+            logger.error("Attempted to send async request with closed connection.")
+            raise RuntimeError("Unable to make request as this connection is closed.")
+        if self.connection is None:
+            logger.debug("No existing connection found; creating new async client for request.")
+            self.connection = create_async_client(self.server_key)
+        if not isinstance(self.connection, httpx.AsyncClient):
+            logger.error("Async request attempted with non-async client.")
+            raise RuntimeError("Cannot send async request; connection is not an async client.")
+        
+        method = self._get_method(endpoint)
+        if self.wait_for_rate_limit:
+            async with cast(asyncio.Lock, self.lock):
+                if method == "GET":
+                    wait_for = self._get_wait_time()
+                else:
+                    wait_for = self._post_wait_time()
+                    
+                if wait_for > 0:
+                    logger.debug("Waiting for %s seconds due to rate limit before sending async request.", wait_for)
+                    await asyncio.sleep(wait_for)
+                    logger.debug("Rate limit waiting finished.")
+                
+                logger.debug("Sending async request to endpoint %s.", endpoint.value)
+                resp = await self.connection.request(method, endpoint.value, **kwargs)
+                self._update_ratelimit(resp)
+                self._raise_for_status(resp)
+                
+                return resp
+        
+        logger.debug("Sending async request to endpoint %s.", endpoint.value)
+        resp = await self.connection.request(method, endpoint.value, **kwargs)
+        self._update_ratelimit(resp)
+        self._raise_for_status(resp)
+            
+        return resp
+    
+    def _send_sync_request(self, endpoint: EndpointType, **kwargs) -> httpx.Response:
+        if self.connection is None and self.closed:
+            logger.error("Attempted to send sync request with closed connection.")
+            raise RuntimeError("Unable to make request as this connection is closed.")
+        if self.connection is None:
+            logger.debug("No existing connection found; creating new sync client for request.")
+            self.connection = create_sync_client(self.server_key)
+        if not isinstance(self.connection, httpx.Client):
+            logger.error("Sync request attempted with non-sync client.")
+            raise RuntimeError("Cannot send sync request; connection is not a sync client.")
+        
+        method = self._get_method(endpoint)
+        if self.wait_for_rate_limit:
+            with cast(threading.Lock, self.lock):
+                if method == "GET":
+                    wait_for = self._get_wait_time()
+                else:
+                    wait_for = self._post_wait_time()
+                    
+                if wait_for > 0:
+                    logger.debug("Waiting for %s seconds due to rate limit before sending sync request.", wait_for)
+                    time.sleep(wait_for)
+                    logger.debug("Rate limit waiting finished.")
+                
+                logger.debug("Sending sync request to endpoint %s.", endpoint.value)
+                resp = self.connection.request(method, endpoint.value, **kwargs)
+                self._update_ratelimit(resp)
+                self._raise_for_status(resp)
+
+                return resp
+        
+        logger.debug("Sending sync request to endpoint %s.", endpoint.value)
+        resp = self.connection.request(method, endpoint.value, **kwargs)
+        self._update_ratelimit(resp)
+        self._raise_for_status(resp)
+        
+        return resp
+    
+    def _get_wait_time(self) -> float:
+        if self.get_remaining > 0:
+            return 0.0
+        return max(self.get_expiration - time.time() + 1, 0)
+    
+    def _post_wait_time(self) -> float:
+        return max(self.post_expiration - time.time() + 1, 0)
+    
+    async def aclose(self):
+        if not isinstance(self.connection, httpx.AsyncClient):
+            logger.error("Attempted to close async connection with non-async client.")
+            raise RuntimeError("Connection is not an async client; close with .close().")
+        if self.connection and not self.connection.is_closed:
+            await self.connection.aclose()
+        
+        self.connection = None
+        self.closed = True
+        logger.info("Async connection closed.")
+        
+    def close(self):
+        if not isinstance(self.connection, httpx.Client):
+            logger.error("Attempted to close sync connection with non-sync client.")
+            raise RuntimeError("Connection is not an sync client; close with .aclose().")
+        if self.connection and not self.connection.is_closed:
+            self.connection.close()
+        
+        self.connection = None
+        self.closed = True
+        logger.info("Sync connection closed.")

prc/command.py

@@ -0,0 +1,163 @@
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+from httpx import Response
+
+from .users import FullUser, UsernameUser, IdUser
+from .v2.models import Player as V2Player
+from .v1.models import Player as V1Player
+
+if TYPE_CHECKING:
+    from .v2.client import AsyncClient as V2AsyncClient, Client as V2Client
+    
+logger = logging.getLogger(__name__)
+
+def normalize_command(command: str) -> str:
+    """Normalize a command by ensuring it starts with a colon."""
+    return command if command.startswith(":") else f":{command}"
+
+@dataclass
+class Command:
+    """Represents an in-game command.
+    
+    You should import and use the `cmd` instance to dynamically create `Command` objects
+    instead of instantiating this class directly:
+    
+    ```python
+    from prc.v2 import cmd
+    
+    cmd.pm("Alice", "Hello World!") # Command(text=":pm Alice Hello World!")
+    ```
+    
+    Attributes
+    ----------
+    text: `str`
+        The command's normalized text.
+    """
+    text: str
+    
+    dangerous_cmds: ClassVar[set[str]] = {
+        ":kick", ":ban", ":wanted", ":unwanted",
+        ":jail", ":unjail", ":kill", ":heal",
+        ":refresh", ":respawn"
+    }
+    
+    def __post_init__(self) -> None:
+        self.text = normalize_command(self.text)
+    
+    async def asend(self, client: "V2AsyncClient"):
+        """Sends this command to the API using the provided asynchronous client."""
+        logger.info("Sending async command: '%s'", self.text)
+        return await client.send_command(self)
+    
+    def send(self, client: "V2Client") -> Response:
+        """Sends this command to the API using the provided synchronous client."""
+        logger.info("Sending sync command: '%s'", self.text)
+        return client.send_command(self)
+    
+    @property
+    def payload(self) -> dict[str, str]:
+        """Returns the payload to send this command to the API."""
+        return {"command": self.text}
+
+    @property
+    def command(self) -> str:
+        """Returns the command with leading colon (`:h`, `:kick`, etc.)"""
+        return self.text.split()[0]
+    
+    @property
+    def dangerous(self) -> bool:
+        """Returns True if the command is dangerous (e.g. `:kick all`, `:ban all`), else False."""
+        return any(
+            self.text.startswith((f"{cmd} all", f"{cmd} others"))
+            for cmd in type(self).dangerous_cmds
+        )
+
+# define user types
+type AnyUserType = V2Player | V1Player | FullUser | UsernameUser | IdUser | str | int
+type UsernameUserType = V2Player | V1Player | FullUser | UsernameUser | str
+type IdUserType = V2Player | V1Player | FullUser | IdUser | int
+
+type CommandLike = Command | str
+
+class _CmdFactory:
+    if TYPE_CHECKING:
+        # define in-game command methods 
+        def h(self, message: str) -> Command: ...
+        def hint(self, message: str) -> Command: ...
+        def m(self, message: str) -> Command: ...
+        def message(self, message: str) -> Command: ...
+        def pm(self, player: UsernameUserType | Sequence[UsernameUserType], message: str) -> Command: ...
+        def privatemessage(self, player: UsernameUserType | Sequence[UsernameUserType], message: str) -> Command: ...
+        def kick(self, player: AnyUserType | Sequence[AnyUserType], reason: str = "") -> Command: ...
+        def ban(self, player: AnyUserType | Sequence[AnyUserType], reason: str = "") -> Command: ...
+        def unban(self, player: AnyUserType | Sequence[AnyUserType]) -> Command: ...
+        def wanted(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def unwanted(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def jail(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def unjail(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def kill(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def heal(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def refresh(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def respawn(self, player: UsernameUserType | Sequence[UsernameUserType]) -> Command: ...
+        def tp(self, player1: UsernameUserType, player2: UsernameUserType) -> Command: ...
+        def teleport(self, player1: UsernameUserType, player2: UsernameUserType) -> Command: ...
+        def admin(self, player: AnyUserType) -> Command: ...
+        def unadmin(self, player: AnyUserType) -> Command: ...
+        def mod(self, player: AnyUserType) -> Command: ...
+        def unmod(self, player: AnyUserType) -> Command: ...
+        def helper(self, player: AnyUserType) -> Command: ...
+        def unhelper(self, player: AnyUserType) -> Command: ...
+        def log(self, message: str) -> Command: ...
+        def weather(self, weather: str) -> Command: ...
+        def time(self, time: float) -> Command: ...
+        def shutdown(self) -> Command: ...
+    
+    # handle argument parsing and custom command creation
+    def __getattr__(self, name: str):
+        def call(*args, **kwargs) -> Command:
+            # parse player/user objects into username/ID representations
+            parsed: list[str] = []
+            collected_args = list(args) + list(kwargs.values())
+            
+            for arg in collected_args:
+                # treat non-string sequences as a grouped player list
+                if isinstance(arg, Sequence) and not isinstance(arg, (str, bytes)):
+                    items: list[str] = []
+                    for item in arg:
+                        if isinstance(item, (V2Player, V1Player)):
+                            items.append(item.user.name)
+                        elif isinstance(item, (UsernameUser, FullUser)):
+                            items.append(item.name)
+                        elif isinstance(item, IdUser):
+                            items.append(str(item.id))
+                        else:
+                            items.append(str(item))
+                    parsed.append(','.join(items))
+                else:
+                    item = arg
+                    if isinstance(item, (V2Player, V1Player)):
+                        parsed.append(item.user.name)
+                    elif isinstance(item, (UsernameUser, FullUser)):
+                        parsed.append(item.name)
+                    elif isinstance(item, IdUser):
+                        parsed.append(str(item.id))
+                    else:
+                        parsed.append(str(item))
+            
+            # join the parsed arguments
+            joined_args = ' '.join(parsed)
+            full = f"{name} {joined_args}".strip()
+            logger.debug("Created command: '%s'", full)
+            
+            return Command(text=full)
+        return call
+
+cmd: _CmdFactory = _CmdFactory()
+"""Factory for creating in-game commands.
+
+Used to build commands, such as `cmd.hint("Hello, World!")` or `cmd.kick(["player1", "player2"], "reason")`.
+
+In-game commands have type hints/method stubs, but any command can be created the same way
+and user arguments will be parsed automatically."""

prc/events/__init__.py

@@ -0,0 +1,4 @@
+from .router import Router
+from .models import Context
+
+__all__ = ["Router", "Context"]

prc/events/decorators.py

@@ -0,0 +1,56 @@
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .router import Router
+
+class _On:
+    def __init__(self, router: "Router") -> None:
+        self.router = router
+        
+    def command(self, command: str, *commands: str):
+        """Register a function to be called when a specific command is run in-game."""
+        def wrapper(func):
+            self.router._add_command(func, command)
+            for cmd in commands:
+                self.router._add_command(func, cmd)
+            return func
+        return wrapper
+    
+    def any_custom_command(self):
+        """Register a function to be called when any custom command is run in-game."""
+        def wrapper(func):
+            self.router._add_command(func, None)
+            return func
+        return wrapper
+    
+    def custom_event(self, event_name: str, *event_names: str):
+        """Register a function to be called when a custom event with the specified name is received."""
+        def wrapper(func):
+            self.router._add_function(func, event_name)
+            for name in event_names:
+                self.router._add_function(func, name)
+            return func
+        return wrapper
+    
+    def emergency_start(self):
+        """Register a function to be called when an emergency call is made in-game."""
+        def wrapper(func):
+            self.router._add_function(func, "EmergencyCallStarted")
+            return func
+        return wrapper
+    
+    def probe(self):
+        """Register a function to be called when a webhook ping is received from the PRC API.
+        
+        These are occasionally sent by the API to test the validity of the webhook URL and its signature verification.
+        """
+        def wrapper(func):
+            self.router._add_function(func, "WebhookProbe")
+            return func
+        return wrapper
+    
+    def any_event(self):
+        """Register a function to be called when any non-command event is received."""
+        def wrapper(func):
+            self.router._add_function(func, None)
+            return func
+        return wrapper

prc/events/integrations/__init__.py

@@ -0,0 +1,5 @@
+from .fastapi import _FastApiIntegration
+from .quart import _QuartIntegration
+from .starlette import _StarletteIntegration
+
+__all__ = ["_FastApiIntegration", "_QuartIntegration", "_StarletteIntegration"]

prc/events/integrations/fastapi.py

@@ -0,0 +1,24 @@
+from typing import Literal
+from ..router import Router
+
+try:
+    from fastapi import Request, BackgroundTasks
+except ImportError:
+    raise RuntimeError((
+        "FastAPI integration for PRC events requires the `fastapi` library. "
+        "Install the dependency with `pip install prc-client[fastapi]`."
+    ))
+
+class _FastApiIntegration:
+    def __init__(self, router: Router) -> None:
+        self.router = router
+    
+    async def handle_fastapi_request(self, request: Request, background_tasks: BackgroundTasks) -> Literal[200, 400]:
+        raw_body = await request.body()
+        headers = dict(request.headers)
+
+        status, task = await self.router.prepare_request(raw_body, headers)
+        if status == 200 and task:
+            background_tasks.add_task(task)
+
+        return status

prc/events/integrations/quart.py

@@ -0,0 +1,25 @@
+from typing import Literal
+from ..router import Router
+
+try:
+    from quart import Quart, request
+except ImportError:
+    raise RuntimeError((
+        "Quart integration for PRC events requires the `quart` library. "
+        "Install the dependency with `pip install prc-client[quart]`."
+    ))
+
+class _QuartIntegration:
+    def __init__(self, router: Router) -> None:
+        self.router = router
+    
+    async def handle_quart_request(self, app: Quart) -> Literal[200, 400]:
+        raw_body = await request.get_data(as_text=False)
+        raw_body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+        headers = dict(request.headers)
+        
+        status, task = await self.router.prepare_request(raw_body, headers)
+        if status == 200 and task:
+            app.add_background_task(task)
+        
+        return status

prc/events/integrations/starlette.py

@@ -0,0 +1,29 @@
+from typing import Literal
+from ..router import Router
+
+try:
+    from starlette.requests import Request
+    from starlette.background import BackgroundTask
+except ImportError:
+    raise RuntimeError((
+        "Starlette integration for PRC events requires the `starlette` library. "
+        "Install the dependency with `pip install prc-client[starlette]`."
+    ))
+
+class _StarletteIntegration:
+    def __init__(self, router: Router) -> None:
+        self.router = router
+    
+    async def handle_starlette_request(
+        self, request: Request
+    ) -> tuple[Literal[200, 400], BackgroundTask | None]:
+        raw_body = await request.body()
+        headers = dict(request.headers)
+
+        status, task = await self.router.prepare_request(raw_body, headers)
+        if status == 200 and task:
+            background_task = BackgroundTask(task)
+        else:
+            background_task = None
+
+        return status, background_task