prc-client 1.1.0__tar.gz

prc_client-1.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+
+      - run: uv build
+
+      - run: uv publish

prc_client-1.1.0/.github/workflows/tests.yml

@@ -0,0 +1,33 @@
+name: Run Tests
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      
+      - name: Setup UV
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras --all-groups
+
+      - name: Run tests
+        run: uv run pytest

prc_client-1.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+test.py
+prc_client.egg-info/
+dist/

prc_client-1.1.0/.python-version

@@ -0,0 +1 @@
+3.12

prc_client-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 garden-yardripper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

prc_client-1.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: prc-client
+Version: 1.1.0
+Summary: A flexible, feature-rich API client for the ER:LC private server API.
+Author-email: garden-yardripper <gardenyardripper@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.13.4
+Provides-Extra: events
+Requires-Dist: cryptography>=49.0.0; extra == 'events'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.137.1; extra == 'fastapi'
+Requires-Dist: starlette>=1.3.1; extra == 'fastapi'
+Provides-Extra: quart
+Requires-Dist: quart>=0.20.0; extra == 'quart'
+Provides-Extra: starlette
+Requires-Dist: starlette>=1.3.1; extra == 'starlette'
+Description-Content-Type: text/markdown
+
+# prc-client
+`prc-client` is a flexible, feature-rich API client for the ER:LC private server API. This client provides a simple and intuitive interface for interacting with ER:LC private servers with detailed data models, typing, comprehensive error handling, and a high-performance architecture.
+
+This library aims to provide all the functionality you need without overwhelming developers with unnecessary features or complexity. `prc-client` stays lightweight, allowing for full control over your development process - whether you're building a simple automation script to fully-featured complex application integrating with the PRC API.
+
+# Key Features
+- 100% coverage of all V1 and V2 API endpoints
+- Full support for the event webhook API
+- Support for both synchronous and asynchronous applications
+- Automatic rate limit handling
+- Intuitive developer interface allows for rapid prototyping and high development experience
+- High performance - built on top of [HTTPX](https://github.com/encode/httpx) for HTTP requests and [Pydantic](https://github.com/samuelcolvin/pydantic) for data validation
+- Detailed docstring documentation and examples
+- Comprehensive error handling and logging
+
+# Installation
+Install `prc-client` using pip:
+
+```bash
+pip install prc-client
+```
+
+Optionally install additional dependencies:
+
+```bash
+pip install prc-client[events,fastapi]
+```
+
+# Quick Start
+Import the `prc` module and create a client instance.
+
+```python
+import prc
+
+client = prc.v2.Client()
+```
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+
+client = prc.v2.AsyncClient()
+```
+</details>  
+
+Get a server with configurable parameters, or get a `BundledServer` with all available API data.
+
+```python
+import prc
+
+client = prc.v2.Client()
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+
+async def main():
+    client = prc.v2.AsyncClient()
+
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+```
+</details> 
+
+Send a command to the server using the `send_command` method and `cmd` factory to build commands.
+
+```python
+import prc
+from prc import cmd
+
+client = prc.v2.Client()
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+
+# Send a PM to all players
+client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+from prc import cmd
+
+async def main():
+    client = prc.v2.AsyncClient()
+
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+
+    # Send a PM to all players
+    await client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+</details> 
+
+Let's set up a router with a simple command handler to receive requests from PRC.
+
+```python
+import prc
+from prc import cmd
+from prc.events import Router, Context
+
+client = prc.v2.Client()
+# Create a router
+router = Router(client)
+
+# Define a command handler to run when the command ;myid / ;id / ;whoami is sent
+@router.on.command("myid", "id", "whoami")
+def handle_myid_command(ctx: Context):
+    ctx.reply(f"Your ID is: {ctx.user.id}")
+
+# This command handler runs when any command is received
+@router.on.any_command()
+def handle_any_command(ctx: Context):
+    print(f"User {ctx.user.id} sent command '{ctx.command.command}' with arguments {ctx.command.arguments}")
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+
+# Send a PM to all players
+client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+from prc import cmd
+from prc.events import Router, Context
+
+client = prc.v2.AsyncClient()
+# Create a router
+router = Router(client)
+
+# Define a command handler to run when the command ;myid / ;id / ;whoami is sent
+@router.on.command("myid", "id", "whoami")
+async def handle_myid_command(ctx: Context):
+    await ctx.areply(f"Your ID is: {ctx.user.id}")
+
+# This command handler runs when any command is received
+@router.on.any_command()
+def handle_any_command(ctx: Context):
+    print(f"User {ctx.user.id} sent command '{ctx.command.command}' with arguments {ctx.command.arguments}")
+
+async def main():
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+
+    # Send a PM to all players
+    await client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+</details>
+
+<details>
+<summary>FastAPI application code</summary>
+
+See the [FastAPI documentation](https://fastapi.tiangolo.com/) for more information on how to use FastAPI.
+
+```python
+from fastapi import FastAPI, Request, Response, BackgroundTasks
+
+app = FastAPI()
+
+@app.post("/your/endpoint")
+async def prc_webhook(request: Request, background_tasks: BackgroundTasks):
+    status = await router.handle_fastapi_request(request, background_tasks)
+    return Response(status_code=status)
+```
+</details>
+
+Check out the [examples](./examples) for more information on specific use cases.

prc_client-1.1.0/README.md

@@ -0,0 +1,194 @@
+# prc-client
+`prc-client` is a flexible, feature-rich API client for the ER:LC private server API. This client provides a simple and intuitive interface for interacting with ER:LC private servers with detailed data models, typing, comprehensive error handling, and a high-performance architecture.
+
+This library aims to provide all the functionality you need without overwhelming developers with unnecessary features or complexity. `prc-client` stays lightweight, allowing for full control over your development process - whether you're building a simple automation script to fully-featured complex application integrating with the PRC API.
+
+# Key Features
+- 100% coverage of all V1 and V2 API endpoints
+- Full support for the event webhook API
+- Support for both synchronous and asynchronous applications
+- Automatic rate limit handling
+- Intuitive developer interface allows for rapid prototyping and high development experience
+- High performance - built on top of [HTTPX](https://github.com/encode/httpx) for HTTP requests and [Pydantic](https://github.com/samuelcolvin/pydantic) for data validation
+- Detailed docstring documentation and examples
+- Comprehensive error handling and logging
+
+# Installation
+Install `prc-client` using pip:
+
+```bash
+pip install prc-client
+```
+
+Optionally install additional dependencies:
+
+```bash
+pip install prc-client[events,fastapi]
+```
+
+# Quick Start
+Import the `prc` module and create a client instance.
+
+```python
+import prc
+
+client = prc.v2.Client()
+```
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+
+client = prc.v2.AsyncClient()
+```
+</details>  
+
+Get a server with configurable parameters, or get a `BundledServer` with all available API data.
+
+```python
+import prc
+
+client = prc.v2.Client()
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+
+async def main():
+    client = prc.v2.AsyncClient()
+
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+```
+</details> 
+
+Send a command to the server using the `send_command` method and `cmd` factory to build commands.
+
+```python
+import prc
+from prc import cmd
+
+client = prc.v2.Client()
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+
+# Send a PM to all players
+client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+from prc import cmd
+
+async def main():
+    client = prc.v2.AsyncClient()
+
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+
+    # Send a PM to all players
+    await client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+</details> 
+
+Let's set up a router with a simple command handler to receive requests from PRC.
+
+```python
+import prc
+from prc import cmd
+from prc.events import Router, Context
+
+client = prc.v2.Client()
+# Create a router
+router = Router(client)
+
+# Define a command handler to run when the command ;myid / ;id / ;whoami is sent
+@router.on.command("myid", "id", "whoami")
+def handle_myid_command(ctx: Context):
+    ctx.reply(f"Your ID is: {ctx.user.id}")
+
+# This command handler runs when any command is received
+@router.on.any_command()
+def handle_any_command(ctx: Context):
+    print(f"User {ctx.user.id} sent command '{ctx.command.command}' with arguments {ctx.command.arguments}")
+
+# Contains only the specified data
+server = client.get_server(players=True, vehicles=True)
+# Contains all available data
+bundled_server = client.get_bundled_server()
+
+# Send a PM to all players
+client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+<details>
+<summary>Or asynchronously...</summary>
+
+```python
+import prc
+from prc import cmd
+from prc.events import Router, Context
+
+client = prc.v2.AsyncClient()
+# Create a router
+router = Router(client)
+
+# Define a command handler to run when the command ;myid / ;id / ;whoami is sent
+@router.on.command("myid", "id", "whoami")
+async def handle_myid_command(ctx: Context):
+    await ctx.areply(f"Your ID is: {ctx.user.id}")
+
+# This command handler runs when any command is received
+@router.on.any_command()
+def handle_any_command(ctx: Context):
+    print(f"User {ctx.user.id} sent command '{ctx.command.command}' with arguments {ctx.command.arguments}")
+
+async def main():
+    # Contains only the specified data
+    server = await client.get_server(players=True, vehicles=True)
+    # Contains all available data
+    bundled_server = await client.get_bundled_server()
+
+    # Send a PM to all players
+    await client.send_command(cmd.pm(server.players, "Welcome to the server!"))
+```
+
+</details>
+
+<details>
+<summary>FastAPI application code</summary>
+
+See the [FastAPI documentation](https://fastapi.tiangolo.com/) for more information on how to use FastAPI.
+
+```python
+from fastapi import FastAPI, Request, Response, BackgroundTasks
+
+app = FastAPI()
+
+@app.post("/your/endpoint")
+async def prc_webhook(request: Request, background_tasks: BackgroundTasks):
+    status = await router.handle_fastapi_request(request, background_tasks)
+    return Response(status_code=status)
+```
+</details>
+
+Check out the [examples](./examples) for more information on specific use cases.

prc_client-1.1.0/examples/command_policy.py

@@ -0,0 +1,20 @@
+import prc
+from prc import cmd
+from prc.policy import CommandPolicy
+
+# Only allow hint and message commands
+# Blacklist set takes priority over whitelist
+policy = CommandPolicy(whitelist={"h", "hint", "m", "message"}, blacklist={"kick"})
+
+with prc.v2.Client(server_key="...", policy=policy) as client:
+    hint_preview = policy.preview_command(cmd.h("Hello World!"))
+    wanted_preview = policy.preview_command(cmd.wanted("Alice"))
+    
+    if hint_preview.allowed:
+        client.send_command(hint_preview.command)
+    
+    if wanted_preview.allowed:
+        # This will not run
+        client.send_command(wanted_preview.command)
+    else:
+        print("Command disallowed! Reason:", wanted_preview.reason)

prc_client-1.1.0/examples/events/fastapi_integration.py

@@ -0,0 +1,23 @@
+from fastapi import FastAPI, BackgroundTasks, Request, Response
+
+import prc
+from prc.events import Router, Context
+
+client = prc.v2.AsyncClient(server_key="...")
+router = Router(client)
+
+@router.on.command("say")
+async def handle_say_command(ctx: Context[prc.v2.AsyncClient]):
+    player = await ctx.client.get_player_from_user(ctx.user.id)
+    await ctx.areply(f"Hello, {player.user.name}! You said: {ctx.command.argument}")
+
+# Basic FastAPI application to receive requests from PRC
+app = FastAPI()
+
+@app.post("/prc/webhook")
+async def prc_webhook(request: Request, background_tasks: BackgroundTasks):
+    # Handle the incoming request using the handle_fastapi_request method,
+    # which will handle all dispatching and background task scheduling for us
+    # and immediately return the appropriate HTTP status code.
+    status = await router.handle_fastapi_request(request, background_tasks)
+    return Response(status_code=status)

prc_client-1.1.0/examples/events/router_usage.py

@@ -0,0 +1,53 @@
+from fastapi import FastAPI, Request, Response, BackgroundTasks
+
+import prc
+from prc import cmd
+from prc.events import Router, Context
+
+client = prc.v2.AsyncClient(server_key="...")
+
+# No need to send sync handlers to a thread in this example
+# because our sync handlers don't do any blocking operations,
+# which will give better performance.
+router = Router(client, sync_handlers_to_thread=False)
+
+# You can assign multiple commands to the same handler
+# by passing them as additional arguments to the decorator
+@router.on.command("myid", "id", "whoami")
+async def handle_myid_command(ctx: Context):
+    # This handler will send the command user a PM when they run the command ';myid' in-game
+    await ctx.areply(f"Your user ID is {ctx.user.id}.")
+    
+@router.on.emergency_start()
+async def handle_emergency_start(ctx: Context[prc.v2.AsyncClient]):
+    # This handler will check if the caller of an emergency call is on the Police or Sheriff team,
+    # and if so, will PM them and then wanted off the team
+    player = await ctx.client.get_player_from_user(ctx.emergency_call.caller)
+    
+    if player.team in ("Police", "Sheriff"):
+        await ctx.client.send_command(cmd.pm(player,
+            "You cannot make emergency calls while on this team! You will be wanted off the team shortly."
+        ))
+        await ctx.client.send_command(cmd.wanted(player))
+
+@router.on.any_event()
+def handle_any_event(ctx: Context):
+    # This handler will be called for any non-command event
+    print(f"Received event of type {ctx.event_type}.")
+
+@router.on.any_custom_command()
+def log_command_usage(ctx: Context):
+    # This handler will log the usage of any custom command to the console
+    # Replace with a proper logging statement in a production application
+    print(f"User {ctx.user.id} executed command '{ctx.command.command}' with argument '{ctx.command.argument}'.")
+    
+# Basic FastAPI application to receive requests from PRC
+app = FastAPI()
+
+@app.post("/prc/webhook")
+async def prc_webhook(request: Request, background_tasks: BackgroundTasks):
+    # Handle the incoming request using the handle_fastapi_request method,
+    # which will handle all dispatching and background task scheduling for us
+    # and immediately return the appropriate HTTP status code.
+    status = await router.handle_fastapi_request(request, background_tasks)
+    return Response(status_code=status)

prc_client-1.1.0/examples/v2/get_server.py

@@ -0,0 +1,10 @@
+import prc
+
+def main():
+    with prc.v2.Client(server_key="...") as client:
+        server = client.get_bundled_server()
+        for player in server.players:
+            print(f"{player.user.name} is on the {player.team} team!")
+    
+if __name__ == "__main__":
+    main()

prc_client-1.1.0/examples/v2/get_server_async.py

@@ -0,0 +1,11 @@
+import prc
+import asyncio
+
+async def main():
+    async with prc.v2.AsyncClient(server_key="...") as client:
+        server = await client.get_bundled_server()
+        for player in server.players:
+            print(f"{player.user.name} is on the {player.team} team!")
+    
+if __name__ == "__main__":
+    asyncio.run(main())

prc_client-1.1.0/examples/v2/send_command.py

@@ -0,0 +1,17 @@
+import prc
+from prc import cmd
+
+with prc.v2.Client(server_key="...") as client:
+    server = client.get_server(players=True)
+    
+    # Get players whose names start with 'all' or 'others'
+    players_to_kick = [
+        player for player in server.players
+        if player.user.name.lower().startswith(("all", "others"))
+    ]
+    
+    # Kick the players from the server
+    client.send_command(cmd.kick(players_to_kick, "Username starts with 'all' or 'others'."))
+    
+    # Alternatively:
+    # cmd.kick(players_to_kick, "Username starts with 'all' or 'others'.").send(client)