multiplayer 0.11.0__py3-none-any.whl

multiplayer/utils.py

@@ -0,0 +1,215 @@
+"""
+This module provides utility functions for the multiplayer package.
+"""
+import csv
+import random
+from importlib import resources
+from pathlib import Path
+
+# --- Built-in Categories ---
+_BUILTIN_GAME_CATEGORIES = {
+    "cities": "data/cities.csv",
+    "countries": "data/countries.csv",
+    "rivers": "data/rivers.csv",
+    "seas_oceans": "data/seas_oceans.csv",
+    "planets_moons": "data/planets_moons.csv",
+}
+
+_BUILTIN_PLAYER_CATEGORIES = {
+    "roman_gods": "data/roman_gods.csv",
+    "greek_gods": "data/greek_gods.csv",
+    "egyptian_gods": "data/egyptian_gods.csv",
+    "european_kings": "data/european_kings.csv",
+    "european_queens": "data/european_queens.csv",
+}
+
+# --- Custom Categories (user-defined) ---
+_CUSTOM_GAME_CATEGORIES = {}
+_CUSTOM_PLAYER_CATEGORIES = {}
+
+def register_name_category(category_name, data, category_type):
+    """
+    Registers a new custom category for name suggestions.
+
+    Args:
+        category_name (str): The name for the new category.
+        data (list or str or Path): A list of strings, or a path to a CSV/text file.
+                                    The file should have one name per line.
+        category_type (str): "game" or "player".
+    """
+    if category_type == "game":
+        _CUSTOM_GAME_CATEGORIES[category_name] = data
+    elif category_type == "player":
+        _CUSTOM_PLAYER_CATEGORIES[category_name] = data
+    else:
+        raise ValueError("category_type must be 'game' or 'player'")
+
+def unregister_name_category(category_name):
+    """
+    Unregisters a custom category. Built-in categories cannot be removed.
+
+    Args:
+        category_name (str): The name of the custom category to remove.
+
+    Returns:
+        bool: True if the category was found and removed, False otherwise.
+    """
+    if category_name in _CUSTOM_GAME_CATEGORIES:
+        del _CUSTOM_GAME_CATEGORIES[category_name]
+        return True
+    if category_name in _CUSTOM_PLAYER_CATEGORIES:
+        del _CUSTOM_PLAYER_CATEGORIES[category_name]
+        return True
+    return False
+
+def get_available_categories(category_type="all"):
+    """
+    Returns a list of available categories, including custom ones.
+
+    Args:
+        category_type (str): "all", "game", or "player".
+
+    Returns:
+        A list of strings representing the available categories.
+    """
+    if category_type == "game":
+        return list(_BUILTIN_GAME_CATEGORIES.keys()) + list(_CUSTOM_GAME_CATEGORIES.keys())
+    if category_type == "player":
+        return list(_BUILTIN_PLAYER_CATEGORIES.keys()) + list(_CUSTOM_PLAYER_CATEGORIES.keys())
+    return list({**_BUILTIN_GAME_CATEGORIES, **_BUILTIN_PLAYER_CATEGORIES, **_CUSTOM_GAME_CATEGORIES, **_CUSTOM_PLAYER_CATEGORIES}.keys())
+
+def _get_names_from_source(source):
+    """Internal helper to load names from a list, a file path, or a package resource."""
+    if isinstance(source, list):
+        return source
+    
+    # Ensure source uses correct separators for the OS
+    source_path = Path(source)
+    
+    # 1. Try relative to this file first (most reliable in both dev and production layouts)
+    try:
+        current_file_dir = Path(__file__).parent.resolve()
+        path = (current_file_dir / source_path).resolve()
+        if path.is_file():
+            with open(path, 'r', encoding='utf-8') as f:
+                if str(source).endswith('.csv'):
+                    reader = csv.reader(f)
+                    try:
+                        next(reader)  # Assume header
+                        return [row[0] for row in reader if row]
+                    except StopIteration:
+                        return []
+                else:
+                    return [line.strip() for line in f if line.strip()]
+    except Exception:
+        pass
+
+    # 2. Try as an absolute or CWD-relative file path
+    try:
+        if source_path.is_file():
+            with open(source_path, 'r', encoding='utf-8') as f:
+                if str(source).endswith('.csv'):
+                    reader = csv.reader(f)
+                    try:
+                        next(reader)
+                        return [row[0] for row in reader if row]
+                    except StopIteration:
+                        return []
+                else:
+                    return [line.strip() for line in f if line.strip()]
+    except Exception:
+        pass
+
+    # 3. Fallback to package resource (standard PEP 302/modern way)
+    try:
+        # Try finding it in the multiplayer.data subpackage first
+        try:
+            # We explicitly import the subpackage to ensure it's loaded
+            import multiplayer.data
+            package_path = resources.files(multiplayer.data)
+            # If we are looking for 'data/cities.csv', and we are in 'multiplayer.data',
+            # we just need 'cities.csv'
+            if 'data' in source_path.parts:
+                file_name = source_path.name
+                resource_path = package_path.joinpath(file_name)
+            else:
+                resource_path = package_path.joinpath(*source_path.parts)
+        except (ImportError, ModuleNotFoundError, ValueError):
+            # Fallback to main package
+            import multiplayer
+            package_path = resources.files(multiplayer)
+            resource_path = package_path.joinpath(*source_path.parts)
+            
+        if resource_path.is_file():
+            with resource_path.open('r', encoding='utf-8') as f:
+                if str(source).endswith('.csv'):
+                    reader = csv.reader(f)
+                    try:
+                        next(reader)  # Assume header
+                        return [row[0] for row in reader if row]
+                    except StopIteration:
+                        return []
+                else:
+                    return [line.strip() for line in f if line.strip()]
+    except Exception:
+        pass
+
+    return None
+
+def _suggest_from_category(category, valid_builtin_cats, valid_custom_cats):
+    """Internal helper to suggest a name from a specific category."""
+    if category in valid_custom_cats:
+        source = valid_custom_cats[category]
+    elif category in valid_builtin_cats:
+        source = valid_builtin_cats[category]
+    else:
+        return None
+        
+    names = _get_names_from_source(source)
+    if not names:
+        return None
+    return random.choice(names)
+
+def suggest_game_name(category=None):
+    """
+    Suggests a random game name.
+
+    If a category is provided, a name is chosen from that category.
+    If no category is provided, a random game-related category is chosen first.
+
+    Args:
+        category (str, optional): A category from get_available_categories("game").
+
+    Returns:
+        A string containing a random name, or None on failure.
+    """
+    if category:
+        return _suggest_from_category(category, _BUILTIN_GAME_CATEGORIES, _CUSTOM_GAME_CATEGORIES)
+    
+    all_game_cats = {**_BUILTIN_GAME_CATEGORIES, **_CUSTOM_GAME_CATEGORIES}
+    if not all_game_cats:
+        return None
+    random_category = random.choice(list(all_game_cats.keys()))
+    return _suggest_from_category(random_category, _BUILTIN_GAME_CATEGORIES, _CUSTOM_GAME_CATEGORIES)
+
+def suggest_player_name(category=None):
+    """
+    Suggests a random player name.
+
+    If a category is provided, a name is chosen from that category.
+    If no category is provided, a random player-related category is chosen first.
+
+    Args:
+        category (str, optional): A category from get_available_categories("player").
+
+    Returns:
+        A string containing a random name, or None on failure.
+    """
+    if category:
+        return _suggest_from_category(category, _BUILTIN_PLAYER_CATEGORIES, _CUSTOM_PLAYER_CATEGORIES)
+    
+    all_player_cats = {**_BUILTIN_PLAYER_CATEGORIES, **_CUSTOM_PLAYER_CATEGORIES}
+    if not all_player_cats:
+        return None
+    random_category = random.choice(list(all_player_cats.keys()))
+    return _suggest_from_category(random_category, _BUILTIN_PLAYER_CATEGORIES, _CUSTOM_PLAYER_CATEGORIES)

multiplayer-0.11.0.dist-info/METADATA

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: multiplayer
+Version: 0.11.0
+Summary: Library that allows you to manage multiple players, locally, on a network, or on the Internet.
+License-Expression: MIT
+License-File: LICENSE.md
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Requires-Dist: colorlog
+Requires-Dist: cryptography
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: requests ; extra == 'dev'
+Requires-Dist: ruff ; extra == 'dev'
+Requires-Python: >=3.12
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+**English** | [Español](translation/README.es.md) | [Français](translation/README.fr.md)
+
+# Multiplayer Game Manager
+
+> **A Note on this Project's Origin**
+>
+> This project is primarily the result of a series of experiments using Gemini Code Assist for code generation and error handling. Rather than using it on academic examples, it seemed more interesting to apply it to a project that could meet a real practical need.
+>
+> This, therefore, is the reason for `multiplayer`'s existence: you can dissect the code to see how Gemini (with my guidance) went about building it, or you can ignore all that and just use this library for your own needs!
+
+This Python module provides a simple and flexible framework for managing multiplayer games, both locally and over a network.
+
+For a detailed technical description of all classes and functions, see the [API Reference](REFERENCE.md).
+
+## Features
+
+*   **Local & Networked:** Use in a single process or in a client-server architecture.
+*   **Combined Game State:** A flexible system for synchronizing both the core game status (e.g., `in_progress`) and any custom game data.
+*   **Observer Support:** Ability to add observers who can view the game state without participating as players.
+*   **Administrator Role:** New `ServerAdmin` class to manage the server, kick players/observers, and monitor server status.
+*   **Game Grouping:** Organize several game sessions within the same server using the `GameGroup` class.
+*   **Multi-Layered Security:** Supports server passwords, admin passwords, and per-game passwords, with optional TLS v1.3 encryption. Passwords can be updated dynamically by administrators.
+*   **Automatic Server Discovery:** Clients can automatically find running servers on the local network.
+*   **Extensible Name Suggestions:** Includes a utility function to suggest creative names for games and players.
+*   **Multiple Games:** The server can manage multiple game sessions simultaneously, and the game list is now filtered to hide finished games.
+*   **Robust Error Handling:** A clear set of custom exceptions for both game logic and network issues.
+
+## Installation
+
+You can install it in two ways:
+
+### 1. From PyPI
+```sh
+pip install multiplayer
+```
+
+### 2. From a Wheel file (GitHub)
+Download the `.whl` file from the [Releases](https://github.com/devfred78/multiplayer/releases) page and run:
+```sh
+pip install multiplayer-0.11.0-py3-none-any.whl
+```
+*Replace `multiplayer-0.11.0-py3-none-any.whl` with the actual name of the downloaded file.*
+
+## Usage
+
+### Game State Management
+
+A key feature is the ability to manage your own game state alongside the core game status.
+
+```python
+# On one client, set a custom state
+game.set_state({
+    "board": [["X", "O", ""], ["", "X", ""], ["O", "", ""]],
+    "turn": "player2"
+})
+
+# On another client, retrieve the combined state
+full_state = game.state
+print(f"Game status: {full_state['status']}")
+# > Game status: in_progress
+
+print(f"Current turn: {full_state['custom']['turn']}")
+# > Current turn: player2
+```
+
+
+### Game Grouping
+
+You can group games together for better organization.
+
+```python
+from multiplayer import Game, GameGroup
+
+# Create a group
+group = GameGroup("Tournament A", priority="high")
+
+# Add games to the group
+game1 = Game("Match 1")
+game2 = Game("Match 2")
+group.add_game(game1)
+group.add_game(game2)
+
+print(f"Game 1 ID: {game1.ID}")
+# > Game 1 ID: 550e8400-e29b-41d4-a716-446655440000
+
+print(f"Group '{group.name}' has {len(group.games)} games.")
+# > Group 'Tournament A' has 2 games.
+```
+
+
+### Full Test Environment
+
+A script is available to launch a complete test environment with:
+- An IPC log server (`IPClogging`) in a separate window.
+- A game server.
+- Multiple separate client instances (default is 2) simulating a game, each in its own terminal window.
+
+To run it:
+```bash
+uv run python scripts/full_test_env.py
+```
+
+To specify the number of players:
+```bash
+uv run python scripts/full_test_env.py --players 3
+```
+This will open several Windows Terminal windows: one for the log server and one for each client instance, allowing you to see the real-time interactions and logs.
+
+### Local Usage
+
+You can use the `Game` class directly, including with a password for local validation.
+
+```python
+from multiplayer import Game, Player, suggest_game_name
+
+game = Game(name="My Awesome Game", password="local_game_pass")
+game.add_player(Player("Alice"), password="local_game_pass")
+game.start()
+```
+
+### Networked Usage (Client-Server)
+
+#### Server Setup
+```python
+from multiplayer import GameServer
+
+# Start a secure server with a custom domain and self-signed certificate
+server = GameServer(
+    host='0.0.0.0',
+    port=12345,
+    name="My Production Server",
+    password="my_server_password",
+    admin_password="my_admin_password",
+    use_tls=True,
+    tls_domain="example.com",
+    tls_self_signed=True
+)
+server.start()
+
+# Or use existing certificate files
+server = GameServer(
+    use_tls=True,
+    tls_cert="path/to/cert.pem",
+    tls_key="path/to/key.pem",
+    tls_self_signed=False
+)
+```
+
+#### Running with Docker
+
+You can run the game server using Docker. To use your own TLS certificates, map a local directory containing `cert.pem` and `privkey.pem` to `/app/certs` in the container.
+
+```bash
+docker run -d \
+  -p 65432:65432 \
+  -v /path/to/your/certs:/app/certs \
+  ghcr.io/yourusername/multiplayer-server:latest \
+  --name "My Docker Server" \
+  --use-tls --no-self-signed
+```
+
+The server will automatically look for `cert.pem`, `RSA-cert.pem`, or `ECC-cert.pem` (and their corresponding keys) in the `/app/certs` directory.
+
+#### Administrator Usage
+
+```python
+from multiplayer import ServerAdmin
+
+# Connect as administrator
+admin = ServerAdmin(
+    host='localhost',
+    port=12345,
+    admin_password="my_admin_password",
+    use_tls=True
+)
+
+# Manage the server
+info = admin.get_server_info()
+print(f"Active games: {info['games_count']}")
+
+# Check certificate expiration
+expiration = admin.get_cert_expiration()
+print(f"Certificate expires on: {expiration}")
+
+# Kick a player if necessary
+# admin.kick_player(game_id, player_id)
+
+# Stop the server remotely
+# admin.stop_server()
+```
+
+#### Client Usage
+```python
+from multiplayer import GameClient, Player, suggest_game_name
+
+# 1. Discover and connect to the server
+servers = GameClient.discover_servers()
+if not servers:
+    print("No servers found.")
+else:
+    host, port = servers[0]
+    client = GameClient(
+        host=host,
+        port=port,
+        password="my_server_password",
+        use_tls=True
+    )
+
+    # 2. Create a private game
+    private_game = client.create_game(
+        name=suggest_game_name(),
+        password="my_game_password"
+    )
+    print(f"Created game with ID: {private_game.ID}")
+
+    # 3. Create and use a Game Group
+    group = client.create_group("Tournament A")
+    game_in_group = group.create_game(name="Final Match")
+    print(f"Game in group '{group.name}' has ID: {game_in_group.ID}")
+
+    # 4. A player joins and sets the initial state
+    private_game.add_player(Player("Charlie"), password="my_game_password")
+    private_game.set_state({"score": 0})
+    private_game.start()
+```
+
+## Error Handling
+
+The module provides a set of custom exceptions, including `AuthenticationError` for both server and game passwords.
+
+```python
+from multiplayer import GameClient
+from multiplayer.exceptions import ConnectionError, AuthenticationError
+
+try:
+    # ... connect to client ...
+
+    # Try to join a game with the wrong password
+    game.add_player(Player("Eve"), password="wrong_game_password")
+
+except AuthenticationError as e:
+    print(f"Authentication failed as expected: {e}")
+except ConnectionError as e:
+    print(f"A connection or discovery error occurred: {e}")
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for more details on how to get started.
+
+## Running Tests
+
+To run the unit tests, you will need to have `pytest` installed.
+
+```sh
+pip install pytest
+```
+
+Then, you can run the tests from the root of the project:
+
+```sh
+pytest

multiplayer-0.11.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+multiplayer/IPClogging/__init__.py,sha256=_0l2znu2eZsl7dYT6JCd23TQGwqMOfkTPLjtDOb-TwA,1590
+multiplayer/IPClogging/echoing.py,sha256=pj8xGvvvxhRDE4dJXBip66vx5vyNWFYPmfee-fPc1cw,1153
+multiplayer/IPClogging/server.py,sha256=E9STqw9QmkmQ0t4DnKKXK-verzwdY9IpAWXfcycczZ8,13753
+multiplayer/IPClogging/test.py,sha256=SSgp6KQoZn6PnbLcCOiqlwAS_D70koSyMmfQWlcCxYQ,2335
+multiplayer/__init__.py,sha256=DDXy3jtiqT378FI4fae9BU90L6BL_Q5tgLPeehdp3sI,1212
+multiplayer/client.py,sha256=lzelylHYH0XbOhe0OwhonCnSdIqg5B-sVPhQ3fjY-qU,21428
+multiplayer/data/__init__.py,sha256=IKVEo67OxQU1W-7JXrsuKCNA3Lc6wbcPbMYSlKsboPk,46
+multiplayer/data/cities.csv,sha256=SQlwCxbofWxQN41NQUsybRsC5gAHvaDGkm7A7l9JlLQ,881
+multiplayer/data/countries.csv,sha256=sB2MYdbNbKW2a6OaySeXNG4017dK6Pn5TQrKmt1s0V4,1351
+multiplayer/data/egyptian_gods.csv,sha256=otF4bFk3P410W3nzXr7W-Byl6W5Bhmm2tVUpZRMK-Oo,696
+multiplayer/data/european_kings.csv,sha256=i3fpfyK2KnPj8tzMO5DCB3r2XxCeKnFyXVmb6PqwQGs,1341
+multiplayer/data/european_queens.csv,sha256=YxOfgU68HS3NktMu2ovDbmGwOmnGAjwUpctp5FHDuMM,1938
+multiplayer/data/greek_gods.csv,sha256=D0yZG2TV8GpKVxMkcx-e8kP-vMvvbha9xRapx_ENbUo,917
+multiplayer/data/planets_moons.csv,sha256=xBnp_DLsyoJX8BM48sKlQ_AR0CS0PJFVH14_B0GNaGs,909
+multiplayer/data/rivers.csv,sha256=FK2l4Yt7RePcjQm48EfI_Ksxr4XhMKkyJVvSMYfz7LE,782
+multiplayer/data/roman_gods.csv,sha256=KqzP5PcA68-Bj6hO7NefF6anb1ABzR5zvJ3MAXjJy88,819
+multiplayer/data/seas_oceans.csv,sha256=VUzNRxEmjWePa7owC8GNnobOlbpEUUxEDG6KsJKZ3pA,1347
+multiplayer/exceptions.py,sha256=mOYRbVRJU5W3wUORPPzsnbCI7xJ5DGDig1lUVhMkYmw,1052
+multiplayer/game.py,sha256=Fup2BbTGrBvlUqZq8dW773HSUfYJ1G3Ak-6CXIphIOM,9020
+multiplayer/language/__init__.py,sha256=uBWyC9rEkGtR5-_uGRqQWZ9ycH-NeO1L7JXzHJioKcg,869
+multiplayer/language/language.py,sha256=5KcaDGAaGukMTYdw0JfuNuimpRmtWR0pBxkLG3A2mVo,21299
+multiplayer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+multiplayer/run_log_server.py,sha256=FdQ_cTzxxEyeRYARGdxZHKEjD6cC9LmhMqNuacvb5Yw,915
+multiplayer/run_server.py,sha256=l5y0tbnthpqUcQPCSKKVIcbEvBas_LdIm3GcwWJMf1g,3921
+multiplayer/server.py,sha256=6b6T2-0TYGnxuoHEWmpB9GudAAxV7kfIYbhLcEh7JME,31217
+multiplayer/utils.py,sha256=-kJ9qCx7BQ3GaTQlaoTbR6eqJP1_txYVuPRMP8v0r6A,7973
+multiplayer-0.11.0.dist-info/licenses/LICENSE.md,sha256=kzBwgJsF0xF7Sn6fzdG1w10J1pUiaPZV_7qogwPxpd4,1161
+multiplayer-0.11.0.dist-info/WHEEL,sha256=q5IF0q2xCp3ktUFRCVWsQLjl2ChNlWXBJtnI1LCGdJ8,80
+multiplayer-0.11.0.dist-info/entry_points.txt,sha256=17_5t71OVCgGXdxI8bEfqjCFPUkn6PWcCF9CshY_cKg,125
+multiplayer-0.11.0.dist-info/METADATA,sha256=92VkL11dX-CD85jr4FMHfs-sCCMjH0WRSCFHx4sKPo4,8861
+multiplayer-0.11.0.dist-info/RECORD,,

multiplayer-0.11.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.8
+Root-Is-Purelib: true
+Tag: py3-none-any

multiplayer-0.11.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+multiplayer-log-server = multiplayer.run_log_server:main
+multiplayer-server = multiplayer.run_server:main
+

multiplayer-0.11.0.dist-info/licenses/LICENSE.md

@@ -0,0 +1,23 @@
+**English** | [Español](translation/LICENSE.es.md) | [Français](translation/LICENSE.fr.md)
+
+# MIT License
+
+Copyright (c) 2026 devfred78
+
+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.