repodnet 0.1.0__tar.gz

repodnet-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff lint
+        run: uv run ruff check .
+
+      - name: Ruff format
+        run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: ty check
+        run: uv run ty check
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v

repodnet-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+uv.lock
+
+# Secrets
+.env

repodnet-0.1.0/.python-version

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

repodnet-0.1.0/COPYING

@@ -0,0 +1,165 @@
+		   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions. 
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version. 
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

repodnet-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: repodnet
+Version: 0.1.0
+Summary: Modern async networking library for multiplayer games
+Project-URL: Homepage, https://github.com/Walkercito/repod
+Project-URL: Repository, https://github.com/Walkercito/repod
+Project-URL: Documentation, https://github.com/Walkercito/repod/blob/main/docs/DOCS.md
+Project-URL: Issues, https://github.com/Walkercito/repod/issues
+Author-email: Walkercito <walekrcitoliver@gmail.com>
+License-Expression: LGPL-3.0-or-later
+License-File: COPYING
+Keywords: async,gamedev,msgpack,multiplayer,networking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: msgpack>=1.0.0
+Description-Content-Type: text/markdown
+
+# repod -- multiplayer networking library for Python games
+
+[![Python 3.12+](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FWalkercito%2Frepod%2Fmain%2Fpyproject.toml&logo=python&logoColor=white&label=Python)](https://www.python.org/)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![msgpack](https://img.shields.io/badge/serialization-msgpack-orange)](https://msgpack.org/)
+[![asyncio](https://img.shields.io/badge/I%2FO-asyncio-purple)](https://docs.python.org/3/library/asyncio.html)
+
+repod is a networking library designed to make it easy to write multiplayer games in Python. It uses `asyncio` and `msgpack` to asynchronously serialize network events and arbitrary data structures, and delivers them to your high-level classes through simple callback methods.
+
+It is a modernized fork of [PodSixNet](https://github.com/chr15m/PodSixNet). Same ideas -- channels, action-based message dispatch, synchronous pump loops -- but rebuilt from scratch for Python 3.12+ with async I/O, binary msgpack serialization, and full type annotations. PodSixNet was built on `asyncore`, which was removed in Python 3.12; repod is the drop-in replacement.
+
+Each class within your game client which wants to receive network events subclasses `ConnectionListener` and implements `Network_*` methods to catch specific events from the server. You don't have to wait for buffers to fill, or check sockets for waiting data or anything like that -- just call `client.pump()` once per game loop and the library handles everything else, passing off events to your listener. Sending data back to the server is just as easy with `client.send(mydata)`. On the server side, events are propagated to `Network_*` callbacks on your `Channel` subclass, and data is sent back to clients with `channel.send(mydata)`.
+
+## Install
+
+```bash
+pip install repod
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add repod
+```
+
+## Examples
+
+Chat example:
+
+- `python examples/chat_server.py`
+- and a couple of instances of `python examples/chat_client.py`
+
+Whiteboard example (requires pygame-ce):
+
+- `python examples/whiteboard_server.py`
+- and a couple of instances of `python examples/whiteboard_client.py`
+
+LagTime example (measures round-trip time from server to client):
+
+- `python examples/lag_time_server.py`
+- and a couple of instances of `python examples/lag_time_client.py`
+
+## Quick start -- Server
+
+You need to subclass two classes to make your own server. Each time a client connects, a new `Channel` instance is created, so you subclass `Channel` to make your server-side representation of a client:
+
+```python
+from repod import Channel
+
+class ClientChannel(Channel):
+
+    def network_received(self, data: dict) -> None:
+        print(data)
+
+    def Network_myaction(self, data: dict) -> None:
+        print("myaction:", data)
+```
+
+Whenever the client sends data, the `network_received()` fallback is called if no specific handler exists. The method `Network_myaction()` is only called if your data has an `"action"` key with a value of `"myaction"`. In other words, if the data looks like:
+
+```python
+{"action": "myaction", "blah": 123, ...}
+```
+
+Next, subclass `Server`:
+
+```python
+from repod import Server
+
+class MyServer(Server):
+    channel_class = ClientChannel
+
+    def on_connect(self, channel, addr):
+        print("new connection:", channel)
+```
+
+Set `channel_class` to the Channel subclass you created above. The `on_connect()` method is called whenever a new client connects.
+
+To run the server, call `launch()`:
+
+```python
+MyServer(host="0.0.0.0", port=5071).launch()
+```
+
+That's it. One line. `launch()` handles the event loop internally and catches `Ctrl+C` for clean shutdown.
+
+When you want to send data to a specific client, use the `send` method on the Channel:
+
+```python
+channel.send({"action": "hello", "message": "hello client!"})
+```
+
+## Quick start -- Client
+
+To connect to your server, subclass `ConnectionListener`:
+
+```python
+import time
+from repod import ConnectionListener
+
+class MyClient(ConnectionListener):
+
+    def Network_connected(self, data: dict) -> None:
+        print("connected to the server")
+
+    def Network_error(self, data: dict) -> None:
+        print("error:", data["error"])
+
+    def Network_disconnected(self, data: dict) -> None:
+        print("disconnected from the server")
+
+    def Network_myaction(self, data: dict) -> None:
+        print("myaction:", data)
+```
+
+Network events are received by `Network_*` callback methods. Replace `*` with the value of the `"action"` key you want to catch. The `connected`, `disconnected`, and `error` events are sent automatically by repod.
+
+Connect and pump:
+
+```python
+client = MyClient()
+client.connect("localhost", 5071)
+
+while True:
+    client.pump()
+    time.sleep(0.01)
+```
+
+Call `pump()` once per game loop and repod handles everything -- reading from the socket, deserializing, and dispatching to your `Network_*` methods. Sending data to the server:
+
+```python
+client.send({"action": "myaction", "blah": 123, "things": [3, 4, 3, 4, 7]})
+```
+
+This works with any game framework that has a main loop: pygame, raylib, arcade, pyglet, etc. Just drop `pump()` into the loop.
+
+## Documentation
+
+Full tutorial and API reference: **[docs/DOCS.md](docs/DOCS.md)**
+
+## Why not PodSixNet?
+
+PodSixNet was great for its time, but:
+
+- It's built on `asyncore`, which was **removed in Python 3.12**
+- It uses `rencode` / custom delimiter-based framing (`\0---\0`), which is fragile with binary data
+- It has no type annotations, no modern tooling support
+- It is no longer maintained ([chr15m/PodSixNet#46](https://github.com/chr15m/PodSixNet/issues/46))
+
+repod keeps the same simple API philosophy but replaces the internals:
+
+- **asyncio** instead of asyncore
+- **msgpack** with length-prefix framing instead of rencode with delimiter framing
+- **Full type annotations** with PEP 695 generics (optional)
+- **Python 3.12+** only -- no compatibility shims
+
+## Development
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run pytest tests/ -v
+```
+
+## License
+
+Copyright Walker Gonzales, 2025.
+
+repod is licensed under the terms of the **LGPL v3.0** or later. See the [COPYING](COPYING) file for details.
+
+This is the same license as [PodSixNet](https://github.com/chr15m/PodSixNet), from which repod is forked. In short: you can use repod in any project (commercial or otherwise), but if you modify the repod library code itself, you must make the modified source available.

repodnet-0.1.0/README.md

@@ -0,0 +1,174 @@
+# repod -- multiplayer networking library for Python games
+
+[![Python 3.12+](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FWalkercito%2Frepod%2Fmain%2Fpyproject.toml&logo=python&logoColor=white&label=Python)](https://www.python.org/)
+[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![msgpack](https://img.shields.io/badge/serialization-msgpack-orange)](https://msgpack.org/)
+[![asyncio](https://img.shields.io/badge/I%2FO-asyncio-purple)](https://docs.python.org/3/library/asyncio.html)
+
+repod is a networking library designed to make it easy to write multiplayer games in Python. It uses `asyncio` and `msgpack` to asynchronously serialize network events and arbitrary data structures, and delivers them to your high-level classes through simple callback methods.
+
+It is a modernized fork of [PodSixNet](https://github.com/chr15m/PodSixNet). Same ideas -- channels, action-based message dispatch, synchronous pump loops -- but rebuilt from scratch for Python 3.12+ with async I/O, binary msgpack serialization, and full type annotations. PodSixNet was built on `asyncore`, which was removed in Python 3.12; repod is the drop-in replacement.
+
+Each class within your game client which wants to receive network events subclasses `ConnectionListener` and implements `Network_*` methods to catch specific events from the server. You don't have to wait for buffers to fill, or check sockets for waiting data or anything like that -- just call `client.pump()` once per game loop and the library handles everything else, passing off events to your listener. Sending data back to the server is just as easy with `client.send(mydata)`. On the server side, events are propagated to `Network_*` callbacks on your `Channel` subclass, and data is sent back to clients with `channel.send(mydata)`.
+
+## Install
+
+```bash
+pip install repod
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add repod
+```
+
+## Examples
+
+Chat example:
+
+- `python examples/chat_server.py`
+- and a couple of instances of `python examples/chat_client.py`
+
+Whiteboard example (requires pygame-ce):
+
+- `python examples/whiteboard_server.py`
+- and a couple of instances of `python examples/whiteboard_client.py`
+
+LagTime example (measures round-trip time from server to client):
+
+- `python examples/lag_time_server.py`
+- and a couple of instances of `python examples/lag_time_client.py`
+
+## Quick start -- Server
+
+You need to subclass two classes to make your own server. Each time a client connects, a new `Channel` instance is created, so you subclass `Channel` to make your server-side representation of a client:
+
+```python
+from repod import Channel
+
+class ClientChannel(Channel):
+
+    def network_received(self, data: dict) -> None:
+        print(data)
+
+    def Network_myaction(self, data: dict) -> None:
+        print("myaction:", data)
+```
+
+Whenever the client sends data, the `network_received()` fallback is called if no specific handler exists. The method `Network_myaction()` is only called if your data has an `"action"` key with a value of `"myaction"`. In other words, if the data looks like:
+
+```python
+{"action": "myaction", "blah": 123, ...}
+```
+
+Next, subclass `Server`:
+
+```python
+from repod import Server
+
+class MyServer(Server):
+    channel_class = ClientChannel
+
+    def on_connect(self, channel, addr):
+        print("new connection:", channel)
+```
+
+Set `channel_class` to the Channel subclass you created above. The `on_connect()` method is called whenever a new client connects.
+
+To run the server, call `launch()`:
+
+```python
+MyServer(host="0.0.0.0", port=5071).launch()
+```
+
+That's it. One line. `launch()` handles the event loop internally and catches `Ctrl+C` for clean shutdown.
+
+When you want to send data to a specific client, use the `send` method on the Channel:
+
+```python
+channel.send({"action": "hello", "message": "hello client!"})
+```
+
+## Quick start -- Client
+
+To connect to your server, subclass `ConnectionListener`:
+
+```python
+import time
+from repod import ConnectionListener
+
+class MyClient(ConnectionListener):
+
+    def Network_connected(self, data: dict) -> None:
+        print("connected to the server")
+
+    def Network_error(self, data: dict) -> None:
+        print("error:", data["error"])
+
+    def Network_disconnected(self, data: dict) -> None:
+        print("disconnected from the server")
+
+    def Network_myaction(self, data: dict) -> None:
+        print("myaction:", data)
+```
+
+Network events are received by `Network_*` callback methods. Replace `*` with the value of the `"action"` key you want to catch. The `connected`, `disconnected`, and `error` events are sent automatically by repod.
+
+Connect and pump:
+
+```python
+client = MyClient()
+client.connect("localhost", 5071)
+
+while True:
+    client.pump()
+    time.sleep(0.01)
+```
+
+Call `pump()` once per game loop and repod handles everything -- reading from the socket, deserializing, and dispatching to your `Network_*` methods. Sending data to the server:
+
+```python
+client.send({"action": "myaction", "blah": 123, "things": [3, 4, 3, 4, 7]})
+```
+
+This works with any game framework that has a main loop: pygame, raylib, arcade, pyglet, etc. Just drop `pump()` into the loop.
+
+## Documentation
+
+Full tutorial and API reference: **[docs/DOCS.md](docs/DOCS.md)**
+
+## Why not PodSixNet?
+
+PodSixNet was great for its time, but:
+
+- It's built on `asyncore`, which was **removed in Python 3.12**
+- It uses `rencode` / custom delimiter-based framing (`\0---\0`), which is fragile with binary data
+- It has no type annotations, no modern tooling support
+- It is no longer maintained ([chr15m/PodSixNet#46](https://github.com/chr15m/PodSixNet/issues/46))
+
+repod keeps the same simple API philosophy but replaces the internals:
+
+- **asyncio** instead of asyncore
+- **msgpack** with length-prefix framing instead of rencode with delimiter framing
+- **Full type annotations** with PEP 695 generics (optional)
+- **Python 3.12+** only -- no compatibility shims
+
+## Development
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run ty check
+uv run pytest tests/ -v
+```
+
+## License
+
+Copyright Walker Gonzales, 2025.
+
+repod is licensed under the terms of the **LGPL v3.0** or later. See the [COPYING](COPYING) file for details.
+
+This is the same license as [PodSixNet](https://github.com/chr15m/PodSixNet), from which repod is forked. In short: you can use repod in any project (commercial or otherwise), but if you modify the repod library code itself, you must make the modified source available.