Prepare package for PyPI release

Author: Zvendson

.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade build twine
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check distributions
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

README.md

@@ -1,11 +1,16 @@
+[![PyPI version](https://img.shields.io/pypi/v/paldefender-rest-client)](https://pypi.org/project/paldefender-rest-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/paldefender-rest-client)](https://pypi.org/project/paldefender-rest-client/)
+[![License](https://img.shields.io/pypi/l/paldefender-rest-client)](https://github.com/PalLink/PD-REST-Python/blob/main/LICENSE)
+[![Discord](https://img.shields.io/discord/1399150174357422150?style=social&logo=discord&label=Discord)](https://discord.gg/ZfHEeGbxbk)
+
 # PalDefender-REST-Client (Python)
 
 Installable Python client for the PalDefender REST API. The package covers every route currently registered in the PalDefender reference implementation under `Reference/`.
 
 ## Install
 
 ```bash
-pip install .
+pip install paldefender-rest-client
 ```
 
 ## Quick Start
@@ -28,16 +33,20 @@ Or:
 import PalDefender
 ```
 
-## Example Project
+## CLI
 
-A runnable example CLI is included in [examples/paldefender_cli](examples/paldefender_cli). It uses a local `.env` file for credentials and server settings, and covers every client endpoint.
+The package also installs a `paldefender-cli` command.
 
 ```bash
-pip install -e .[examples]
-python examples/paldefender_cli/main.py version
+paldefender-cli --env .env version
 ```
 
-Copy `examples/paldefender_cli/.env.example` to `examples/paldefender_cli/.env`, then fill in your settings before running the example.
+Set these variables in `.env` or in your shell environment:
+
+- `PALDEFENDER_BASE_URL`
+- `PALDEFENDER_BEARER_TOKEN`
+- `PALDEFENDER_DISPLAY_ADDRESS` (optional)
+- `PALDEFENDER_TIMEOUT` (optional)
 
 If `base_url` omits a port, the client defaults to `17993`.
 
@@ -101,8 +110,8 @@ HTTP errors raise `PalDefenderApiError`. The exception exposes:
 
 ## Endpoint Reference
 
-Full endpoint documentation is in [docs/ENDPOINTS.md](docs/ENDPOINTS.md).
+Full endpoint documentation is in [docs/ENDPOINTS.md](https://github.com/PalLink/PD-REST-Python/blob/main/docs/ENDPOINTS.md).
 
 ## Usage Guide
 
-For a more detailed Python-focused guide with examples for typed GET responses, friendly POST helpers, constants, recipes, and error handling, see [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md).
+For a more detailed Python-focused guide with examples for typed GET responses, friendly POST helpers, constants, recipes, and error handling, see [docs/USAGE_GUIDE.md](https://github.com/PalLink/PD-REST-Python/blob/main/docs/USAGE_GUIDE.md).

docs/USAGE_GUIDE.md

@@ -14,7 +14,7 @@ pip install .
 For the example CLI:
 
 ```bash
-pip install -e .[examples]
+pip install -e .
 ```
 
 ## Creating a Client
@@ -398,7 +398,7 @@ except PalDefenderApiError as exc:
 
 ## Full Example CLI
 
-There is also a runnable CLI example in [examples/paldefender_cli](../examples/paldefender_cli).
+The package also installs a `paldefender-cli` command for terminal use.
 
 It is useful when you want to:
 

examples/paldefender_cli/.env.example

@@ -25,20 +25,21 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules"
 ]
 dependencies = [
+  "python-dotenv>=1.0.1,<2",
   "requests>=2.31.0,<3"
 ]
 
-[project.optional-dependencies]
-examples = [
-  "python-dotenv>=1.0.1,<2"
-]
+[project.scripts]
+paldefender-cli = "paldefender_cli.cli:main"
 
 [project.urls]
-Homepage = "https://github.com/"
-Documentation = "https://github.com/"
+Homepage = "https://pallink.net"
+Repository = "https://github.com/PalLink/PD-REST-Python"
+Documentation = "https://github.com/PalLink/PD-REST-Python/blob/main/docs/USAGE_GUIDE.md"
+Issues = "https://github.com/PalLink/PD-REST-Python/issues"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/PalDefender"]
+packages = ["src/PalDefender", "src/paldefender_cli"]
 
 [tool.hatch.build.targets.sdist]
 include = [

examples/paldefender_cli/README.md

@@ -0,0 +1,5 @@
+"""Command-line interface for the PalDefender REST client."""
+
+from .cli import main
+
+__all__ = ["main"]

pyproject.toml

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

src/paldefender_cli/__init__.py

@@ -7,7 +7,16 @@
 from pathlib import Path
 from typing import Any
 
-from dotenv import load_dotenv
+try:
+    from dotenv import load_dotenv as _load_dotenv
+except ModuleNotFoundError:
+    def _load_dotenv(dotenv_path: Path) -> None:
+        for raw_line in dotenv_path.read_text(encoding="utf-8").splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, value = line.split("=", 1)
+            os.environ.setdefault(key.strip(), value.strip())
 
 from PalDefender import (
     GiveItem,
@@ -22,7 +31,11 @@
 
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        description="Full example CLI for the PalDefender REST client.",
+        description="Command-line interface for the PalDefender REST client.",
+    )
+    parser.add_argument(
+        "--env",
+        help="Path to a .env file. Defaults to .env in the current working directory when present.",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
 
@@ -109,18 +122,30 @@ def build_parser() -> argparse.ArgumentParser:
     return parser
 
 
-def load_settings(env_path: Path) -> dict[str, Any]:
-    load_dotenv(env_path)
+def resolve_env_path(raw_env_path: str | None) -> Path | None:
+    if raw_env_path:
+        return Path(raw_env_path).expanduser().resolve()
+
+    default_env_path = Path.cwd() / ".env"
+    if default_env_path.is_file():
+        return default_env_path
+    return None
+
+
+def load_settings(env_path: Path | None) -> dict[str, Any]:
+    if env_path is not None:
+        _load_dotenv(env_path)
 
     base_url = os.getenv("PALDEFENDER_BASE_URL", "").strip()
     bearer_token = os.getenv("PALDEFENDER_BEARER_TOKEN", "").strip()
     display_address = os.getenv("PALDEFENDER_DISPLAY_ADDRESS", "").strip() or None
     timeout_raw = os.getenv("PALDEFENDER_TIMEOUT", "30").strip()
 
+    source = str(env_path) if env_path is not None else "environment variables"
     if not base_url:
-        raise ValueError(f"PALDEFENDER_BASE_URL is required in {env_path}")
+        raise ValueError(f"PALDEFENDER_BASE_URL is required in {source}")
     if not bearer_token:
-        raise ValueError(f"PALDEFENDER_BEARER_TOKEN is required in {env_path}")
+        raise ValueError(f"PALDEFENDER_BEARER_TOKEN is required in {source}")
 
     try:
         timeout = float(timeout_raw)
@@ -224,9 +249,7 @@ def print_json(data: Any) -> None:
 def main() -> int:
     parser = build_parser()
     args = parser.parse_args()
-
-    example_dir = Path(__file__).resolve().parent
-    env_path = example_dir / ".env"
+    env_path = resolve_env_path(args.env)
 
     try:
         settings = load_settings(env_path)
@@ -284,7 +307,3 @@ def main() -> int:
 
     print_json(result)
     return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

src/paldefender_cli/__main__.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
+import os
 import sys
-import types
 import unittest
 from pathlib import Path
+from tempfile import TemporaryDirectory
 
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
-sys.modules.setdefault("dotenv", types.SimpleNamespace(load_dotenv=lambda *_args, **_kwargs: None))
 
-from examples.paldefender_cli.main import load_json_argument, parse_items
+from paldefender_cli.cli import load_json_argument, load_settings, parse_items, resolve_env_path
 
 
 class PalDefenderCliTests(unittest.TestCase):
@@ -29,6 +29,45 @@ def test_parse_items_maps_known_item_shape(self) -> None:
         self.assertEqual(len(parsed), 1)
         self.assertEqual(parsed[0].to_dict(), {"ItemID": "Axe", "Count": 7})
 
+    def test_resolve_env_path_prefers_explicit_path(self) -> None:
+        resolved = resolve_env_path("./custom.env")
+
+        self.assertTrue(resolved is not None)
+        self.assertEqual(resolved.name, "custom.env")
+
+    def test_load_settings_reads_values_from_env_file(self) -> None:
+        with TemporaryDirectory() as tmp_dir:
+            env_path = Path(tmp_dir) / ".env"
+            env_path.write_text(
+                "PALDEFENDER_BASE_URL=http://localhost\n"
+                "PALDEFENDER_BEARER_TOKEN=secret\n"
+                "PALDEFENDER_TIMEOUT=45\n",
+                encoding="utf-8",
+            )
+
+            old_base_url = os.environ.pop("PALDEFENDER_BASE_URL", None)
+            old_bearer_token = os.environ.pop("PALDEFENDER_BEARER_TOKEN", None)
+            old_timeout = os.environ.pop("PALDEFENDER_TIMEOUT", None)
+            try:
+                settings = load_settings(env_path)
+            finally:
+                if old_base_url is not None:
+                    os.environ["PALDEFENDER_BASE_URL"] = old_base_url
+                else:
+                    os.environ.pop("PALDEFENDER_BASE_URL", None)
+                if old_bearer_token is not None:
+                    os.environ["PALDEFENDER_BEARER_TOKEN"] = old_bearer_token
+                else:
+                    os.environ.pop("PALDEFENDER_BEARER_TOKEN", None)
+                if old_timeout is not None:
+                    os.environ["PALDEFENDER_TIMEOUT"] = old_timeout
+                else:
+                    os.environ.pop("PALDEFENDER_TIMEOUT", None)
+
+        self.assertEqual(settings["base_url"], "http://localhost")
+        self.assertEqual(settings["bearer_token"], "secret")
+        self.assertEqual(settings["timeout"], 45.0)
+
 
 if __name__ == "__main__":
     unittest.main()