palworld-restapi 0.7.3__tar.gz

palworld_restapi-0.7.3/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python package
+    runs-on: ubuntu-latest
+    
+    # Required for Trusted Publishing
+    environment:
+      name: pypi
+      url: https://pypi.org/p/palworld-restapi
+      
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

palworld_restapi-0.7.3/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

palworld_restapi-0.7.3/.python-version

@@ -0,0 +1 @@
+3.14

palworld_restapi-0.7.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AyanoKouji
+
+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.

palworld_restapi-0.7.3/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: palworld-restapi
+Version: 0.7.3
+Summary: This is a simple Palworld REST API Wrapper + CLI written in python.
+Project-URL: Repository, https://github.com/KJAyano/Palworld-RESTAPI
+Project-URL: Issues, https://github.com/KJAyano/Palworld-RESTAPI/issues
+Author: KJAyano
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: python-dotenv
+Description-Content-Type: text/markdown
+
+# Palworld REST API
+
+[![PyPI version](https://badge.fury.io/py/palworld-restapi.svg)](https://pypi.org/project/palworld-restapi/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/palworld-restapi.svg)](https://pypi.org/project/palworld-restapi/)
+
+A modern, fast, and fully-typed Python client library and CLI wrapper for the official **Palworld Dedicated Server REST API**. Built on `httpx` to provide first-class support for both synchronous scripts and high-performance asynchronous applications.
+
+## Features
+
+- **Dual Clients**: Contains both `PalworldClient` (sync) and `AsyncPalworldClient` (async) using connection pooling for maximum performance.
+- **Strict Typing**: Fully typed with PEP 561 compliance. API responses are parsed into rigorous Python Dataclasses for safety and excellent IDE autocomplete.
+- **CLI Included**: Manage your Palworld server directly from your terminal using the built-in `palworld-cli`.
+- **Modern**: Formatted with `ruff`, built with `hatchling`, and rigorously tested.
+
+---
+
+## Installation
+
+You can install the package directly from PyPI:
+
+```bash
+pip install palworld-restapi
+```
+*(Or use `uv add palworld-restapi` if you are using `uv`)*
+
+---
+
+## Quickstart
+
+### Async Client (Recommended for Bots / Web Apps)
+```python
+import asyncio
+from palworld_restapi import AsyncPalworldClient
+
+async def main():
+    async with AsyncPalworldClient("http://127.0.0.1:8212", password="admin-password") as client:
+        info = await client.get_info()
+        print(f"Connected to {info.servername} (v{info.version})")
+        
+        # Announce a message to the server
+        await client.announce("Hello from Python!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Sync Client (Recommended for simple scripts)
+```python
+from palworld_restapi import PalworldClient
+
+with PalworldClient("http://127.0.0.1:8212", password="admin-password") as client:
+    players_resp = client.get_players()
+    print(f"There are currently {len(players_resp.players)} players online.")
+```
+
+---
+
+## Command Line Interface (CLI)
+
+The package ships with a built-in CLI to easily manage your server without writing code. It supports loading credentials from `.env` files automatically.
+
+```bash
+# Get server info
+palworld-cli info
+
+# See online players
+palworld-cli players
+
+# Kick a player by Steam ID
+palworld-cli kick steam_00000000000000000 --message "AFK too long"
+
+# Shut the server down in 60 seconds
+palworld-cli shutdown 60 --message "Restarting for an update!"
+```
+
+---
+
+## Documentation & Examples
+
+For full details, please refer to the documentation:
+- **[Usage Guide](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/USAGE_GUIDE.md)**: Deep dive into using the Python clients.
+- **[CLI Guide](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/CLI_GUIDE.md)**: Full command reference for the `palworld-cli` terminal tool.
+- **[Endpoints Reference](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/ENDPOINTS.md)**: Available endpoints and payload details.
+
+We also have a full suite of working scripts in the [`examples/`](https://github.com/KJAyano/Palworld-RESTAPI/tree/main/examples) directory demonstrating kick/ban management, player tracking, and server metrics.

palworld_restapi-0.7.3/README.md

@@ -0,0 +1,85 @@
+# Palworld REST API
+
+[![PyPI version](https://badge.fury.io/py/palworld-restapi.svg)](https://pypi.org/project/palworld-restapi/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/palworld-restapi.svg)](https://pypi.org/project/palworld-restapi/)
+
+A modern, fast, and fully-typed Python client library and CLI wrapper for the official **Palworld Dedicated Server REST API**. Built on `httpx` to provide first-class support for both synchronous scripts and high-performance asynchronous applications.
+
+## Features
+
+- **Dual Clients**: Contains both `PalworldClient` (sync) and `AsyncPalworldClient` (async) using connection pooling for maximum performance.
+- **Strict Typing**: Fully typed with PEP 561 compliance. API responses are parsed into rigorous Python Dataclasses for safety and excellent IDE autocomplete.
+- **CLI Included**: Manage your Palworld server directly from your terminal using the built-in `palworld-cli`.
+- **Modern**: Formatted with `ruff`, built with `hatchling`, and rigorously tested.
+
+---
+
+## Installation
+
+You can install the package directly from PyPI:
+
+```bash
+pip install palworld-restapi
+```
+*(Or use `uv add palworld-restapi` if you are using `uv`)*
+
+---
+
+## Quickstart
+
+### Async Client (Recommended for Bots / Web Apps)
+```python
+import asyncio
+from palworld_restapi import AsyncPalworldClient
+
+async def main():
+    async with AsyncPalworldClient("http://127.0.0.1:8212", password="admin-password") as client:
+        info = await client.get_info()
+        print(f"Connected to {info.servername} (v{info.version})")
+        
+        # Announce a message to the server
+        await client.announce("Hello from Python!")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Sync Client (Recommended for simple scripts)
+```python
+from palworld_restapi import PalworldClient
+
+with PalworldClient("http://127.0.0.1:8212", password="admin-password") as client:
+    players_resp = client.get_players()
+    print(f"There are currently {len(players_resp.players)} players online.")
+```
+
+---
+
+## Command Line Interface (CLI)
+
+The package ships with a built-in CLI to easily manage your server without writing code. It supports loading credentials from `.env` files automatically.
+
+```bash
+# Get server info
+palworld-cli info
+
+# See online players
+palworld-cli players
+
+# Kick a player by Steam ID
+palworld-cli kick steam_00000000000000000 --message "AFK too long"
+
+# Shut the server down in 60 seconds
+palworld-cli shutdown 60 --message "Restarting for an update!"
+```
+
+---
+
+## Documentation & Examples
+
+For full details, please refer to the documentation:
+- **[Usage Guide](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/USAGE_GUIDE.md)**: Deep dive into using the Python clients.
+- **[CLI Guide](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/CLI_GUIDE.md)**: Full command reference for the `palworld-cli` terminal tool.
+- **[Endpoints Reference](https://github.com/KJAyano/Palworld-RESTAPI/blob/main/docs/ENDPOINTS.md)**: Available endpoints and payload details.
+
+We also have a full suite of working scripts in the [`examples/`](https://github.com/KJAyano/Palworld-RESTAPI/tree/main/examples) directory demonstrating kick/ban management, player tracking, and server metrics.

palworld_restapi-0.7.3/docs/CLI_GUIDE.md

@@ -0,0 +1,104 @@
+# Palworld-RESTAPI Command Line Interface (CLI)
+
+The `palworld-cli` tool allows you to query and manage your Palworld dedicated server directly from your terminal.
+
+## Authentication & Configuration
+
+The CLI requires your server's REST API URL and the Admin Password. 
+
+You can provide these in **three** ways, in order of priority:
+
+1. **Command Line Arguments**:
+   ```bash
+   palworld-cli --base-url "http://127.0.0.1:8212" --password "your_password" info
+   ```
+
+2. **Environment Variables**:
+   ```bash
+   export PALWORLD_BASE_URL="http://127.0.0.1:8212"
+   export PALWORLD_PASSWORD="your_password"
+   palworld-cli info
+   ```
+
+3. **Dotenv (`.env`) File** (Recommended):
+   Create a `.env` file in the folder where you run the command. The CLI automatically loads it.
+   ```env
+   PALWORLD_BASE_URL=http://127.0.0.1:8212
+   PALWORLD_USERNAME=admin
+   PALWORLD_PASSWORD=your_password
+   PALWORLD_TIMEOUT=10.0
+   ```
+   *Note: If your `.env` file is located somewhere else, you can pass `--env /path/to/.env`.*
+
+---
+
+## Available Commands
+
+All data-fetching commands output their results in clean, formatted **JSON**, making it perfect for piping into other tools like `jq`.
+
+### `info`
+Gets general server information (version, name, GUID).
+```bash
+palworld-cli info
+```
+
+### `metrics`
+Gets current server metrics (FPS, uptime, current players).
+```bash
+palworld-cli metrics
+```
+
+### `players`
+Gets a list of all currently online players, including their level, ping, and Steam ID.
+```bash
+palworld-cli players
+```
+
+### `settings`
+Gets the extensive list of server configurations (difficulty, drop rates, PvP settings, etc.).
+```bash
+palworld-cli settings
+```
+
+### `announce`
+Broadcasts a system message to all online players.
+```bash
+palworld-cli announce "Server will restart in 5 minutes!"
+```
+
+### `kick`
+Kicks a player from the server using their `userid` (Steam ID). An optional message can be provided.
+```bash
+palworld-cli kick steam_00000000000000000
+palworld-cli kick steam_00000000000000000 --message "AFK too long"
+```
+
+### `ban`
+Bans a player from the server using their `userid`.
+```bash
+palworld-cli ban steam_00000000000000000 --message "Cheating"
+```
+
+### `unban`
+Unbans a previously banned player.
+```bash
+palworld-cli unban steam_00000000000000000
+```
+
+### `save`
+Forces an immediate save of the world state.
+```bash
+palworld-cli save
+```
+
+### `shutdown`
+Initiates a graceful server shutdown. Requires a `waittime` (in seconds).
+```bash
+palworld-cli shutdown 60 --message "Restarting for update"
+```
+
+### `stop`
+Forces the server to stop immediately without a grace period.
+```bash
+palworld-cli stop
+```

palworld_restapi-0.7.3/docs/ENDPOINTS.md

@@ -0,0 +1,23 @@
+# Palworld REST API Endpoints
+
+Base URL for all endpoints: `http://<host>:8212/v1/api`
+Authentication: **HTTP Basic** (`admin` / `AdminPassword`)
+
+| Method | Endpoint | Description | Request Body | Response Body |
+|--------|----------|-------------|--------------|---------------|
+| `GET` | `/info` | Get server info | - | `ServerInfo` |
+| `GET` | `/players` | Get list of online players | - | `PlayersResponse` |
+| `GET` | `/settings` | Get server settings | - | `ServerSettings` |
+| `GET` | `/metrics` | Get server metrics | - | `ServerMetrics` |
+| `POST` | `/announce` | Send a server announcement | `{"message": "str"}` | - |
+| `POST` | `/kick` | Kick a player | `{"userid": "str", "message": "str"}` | - |
+| `POST` | `/ban` | Ban a player | `{"userid": "str", "message": "str"}` | - |
+| `POST` | `/unban` | Unban a player | `{"userid": "str"}` | - |
+| `POST` | `/save` | Save the server world state | - | - |
+| `POST` | `/shutdown` | Shutdown the server | `{"waittime": int, "message": "str"}` | - |
+| `POST` | `/stop` | Force stop the server | - | - |
+
+> [!NOTE]
+> All successful `POST` endpoints return a `200 OK` status without a specific JSON body.
+> All endpoints will return `401 Unauthorized` if invalid credentials are provided.
+> Endpoints will return `400 Bad Request` if payload is invalid.

palworld_restapi-0.7.3/docs/USAGE_GUIDE.md

@@ -0,0 +1,69 @@
+# Palworld REST API Usage Guide
+
+This guide covers how to use the Palworld REST API Python client in both Synchronous and Asynchronous applications, and how to use the CLI.
+
+## Installation
+
+Ensure your project environment is setup and install the library (e.g. `uv add palworld-restapi` or `pip install palworld-restapi`).
+
+## Code Examples
+We have a full suite of working scripts in the `examples/` directory of the repository:
+- `announcement.py`
+- `banplayer.py` / `kickplayer.py` / `unbanplayer.py`
+- `playerlist.py`
+- `serverinfo.py` / `sync_serverinfo.py`
+- `shutdown.py`
+
+## Sync Client Usage
+
+Use `PalworldClient` for standard scripts and synchronous applications.
+
+```python
+from palworld_restapi import PalworldClient, PalworldApiError
+
+def main():
+    try:
+        with PalworldClient("http://127.0.0.1:8212", password="admin-pass") as client:
+            info = client.get_info()
+            print(f"Server Name: {info.servername}")
+            print(f"Version: {info.version}")
+            
+            players_resp = client.get_players()
+            print(f"Online Players: {len(players_resp.players)}")
+            
+            client.announce("Hello from Palworld-RESTAPI!")
+    except PalworldApiError as e:
+        print(f"API Error: {e}")
+
+if __name__ == "__main__":
+    main()
+```
+
+## Async Client Usage
+
+Use `AsyncPalworldClient` for highly concurrent applications, like Discord bots (e.g., discord.py).
+
+```python
+import asyncio
+from palworld_restapi import AsyncPalworldClient, PalworldApiError
+
+async def main():
+    try:
+        async with AsyncPalworldClient("http://127.0.0.1:8212", password="admin-pass") as client:
+            metrics = await client.get_metrics()
+            print(f"Server FPS: {metrics.serverfps}")
+            
+            settings = await client.get_settings()
+            print(f"Difficulty: {settings.Difficulty}")
+    except PalworldApiError as e:
+        print(f"API Error: {e}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## CLI Usage
+
+The package provides a built-in CLI `palworld-cli`. 
+
+For full details on authentication, options, and commands, please see the dedicated **[CLI Guide](CLI_GUIDE.md)**!

palworld_restapi-0.7.3/examples/announcement.py

@@ -0,0 +1,20 @@
+import asyncio
+from palworld_restapi import AsyncPalworldClient, PalworldApiError
+
+
+async def main():
+    server_url = "http://127.0.0.1:8212"
+    password = "admin_password"
+
+    try:
+        async with AsyncPalworldClient(server_url, password=password) as client:
+            await client.announce(
+                "Server restarting in 5 minutes! Please find a safe place."
+            )
+            print("Announcement sent successfully.")
+    except PalworldApiError as e:
+        print(f"API Error: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

palworld_restapi-0.7.3/examples/banplayer.py

@@ -0,0 +1,20 @@
+import asyncio
+from palworld_restapi import AsyncPalworldClient, PalworldApiError
+
+
+async def main():
+    server_url = "http://127.0.0.1:8212"
+    password = "admin_password"
+
+    try:
+        async with AsyncPalworldClient(server_url, password=password) as client:
+            await client.ban_player(
+                "steam_00000000000000000", message="Violation of server rules."
+            )
+            print("Player banned successfully.")
+    except PalworldApiError as e:
+        print(f"API Error: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())