gzw-data 0.1.1__tar.gz

gzw_data-0.1.1/LICENSE

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

gzw_data-0.1.1/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: gzw-data
+Version: 0.1.1
+Summary: Python client for the free Gray Zone Warfare data API (gzw-data.dev)
+License-Expression: MIT
+Project-URL: Homepage, https://gzw-data.dev/
+Project-URL: Source, https://github.com/ZoniBoy00/gzw-data-py
+Keywords: gray-zone-warfare,gzw,api,game-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gzw-data (Python)
+
+Dependency-free Python client for the free [Gray Zone Warfare data API](https://gzw-data.dev). Fan-made and not affiliated with the game's developer.
+
+```bash
+pip install git+https://github.com/ZoniBoy00/gzw-data-py
+```
+
+```python
+from gzw_data import GzwDataClient
+
+client = GzwDataClient()                       # no API key needed
+print(client.datasets())                       # {'ammo': 79, 'weapons': 44, ...}
+print(client.get("weapons", "ak-12")["name"])  # AK-12
+for ammo in client.iterate("ammo", search="5.56"):
+    print(ammo["name"])
+print(list(client.search("AK")))               # dataset names that matched
+```
+
+Errors raise `GzwApiError` (`.status`, `.code`, `.url`). Rate-limit (honouring `Retry-After`) and 5xx responses are retried with backoff.
+
+Game data comes from the community wiki and has its own terms: see the [data license](https://github.com/ZoniBoy00/gzw-data/blob/main/DATA_LICENSE.md). Code is MIT.
+
+## Development
+
+```bash
+python -m unittest discover -s tests
+```

gzw_data-0.1.1/README.md

@@ -0,0 +1,28 @@
+# gzw-data (Python)
+
+Dependency-free Python client for the free [Gray Zone Warfare data API](https://gzw-data.dev). Fan-made and not affiliated with the game's developer.
+
+```bash
+pip install git+https://github.com/ZoniBoy00/gzw-data-py
+```
+
+```python
+from gzw_data import GzwDataClient
+
+client = GzwDataClient()                       # no API key needed
+print(client.datasets())                       # {'ammo': 79, 'weapons': 44, ...}
+print(client.get("weapons", "ak-12")["name"])  # AK-12
+for ammo in client.iterate("ammo", search="5.56"):
+    print(ammo["name"])
+print(list(client.search("AK")))               # dataset names that matched
+```
+
+Errors raise `GzwApiError` (`.status`, `.code`, `.url`). Rate-limit (honouring `Retry-After`) and 5xx responses are retried with backoff.
+
+Game data comes from the community wiki and has its own terms: see the [data license](https://github.com/ZoniBoy00/gzw-data/blob/main/DATA_LICENSE.md). Code is MIT.
+
+## Development
+
+```bash
+python -m unittest discover -s tests
+```

gzw_data-0.1.1/gzw_data/__init__.py

@@ -0,0 +1,6 @@
+"""Python client for the free Gray Zone Warfare data API (https://gzw-data.dev)."""
+
+from .client import GzwApiError, GzwDataClient
+
+__all__ = ["GzwApiError", "GzwDataClient"]
+__version__ = "0.1.1"

gzw_data-0.1.1/gzw_data/client.py

@@ -0,0 +1,126 @@
+"""Small, dependency-free client built on urllib."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Iterator, Optional
+
+DEFAULT_BASE_URL = "https://gzw-data.dev/api/v1"
+RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+class GzwApiError(Exception):
+    """Raised when the API returns an error or cannot be reached."""
+
+    def __init__(
+        self, message: str, *, status: int = 0, code: str = "UNKNOWN", url: str = "", retry_after: Optional[float] = None
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.url = url
+        self.retry_after = retry_after  # seconds, from the Retry-After header when present
+
+
+class GzwDataClient:
+    """Read-only client. No API key is needed.
+
+    >>> client = GzwDataClient()
+    >>> client.get("weapons", "ak-12")["name"]
+    'AK-12'
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = 10.0,
+        retries: int = 2,
+        user_agent: str = "gzw-data-python/0.1.1",
+        max_retry_wait: float = 65.0,
+        opener: Optional[Callable[..., Any]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.retries = retries
+        self.user_agent = user_agent
+        self.max_retry_wait = max_retry_wait
+        self._open = opener or urllib.request.urlopen
+
+    # -- low level ---------------------------------------------------------
+
+    def request(self, path: str, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        """GET a path and return the full JSON envelope."""
+        query = urllib.parse.urlencode({k: v for k, v in (params or {}).items() if v is not None})
+        url = f"{self.base_url}/{path.lstrip('/')}" + (f"?{query}" if query else "")
+        req = urllib.request.Request(url, headers={"Accept": "application/json", "User-Agent": self.user_agent})
+        last: Optional[GzwApiError] = None
+        for attempt in range(self.retries + 1):
+            try:
+                with self._open(req, timeout=self.timeout) as response:
+                    return json.loads(response.read().decode("utf-8"))
+            except urllib.error.HTTPError as exc:
+                last = self._from_http_error(exc, url)
+                if exc.code not in RETRYABLE_STATUS:
+                    raise last from None
+            except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+                last = GzwApiError(f"Request failed: {exc}", code="NETWORK_ERROR", url=url)
+            if attempt < self.retries:
+                delay = last.retry_after if last.retry_after is not None else min(0.4 * 2**attempt, 4.0)
+                time.sleep(min(delay, self.max_retry_wait))
+        assert last is not None
+        raise last
+
+    @staticmethod
+    def _from_http_error(exc: urllib.error.HTTPError, url: str) -> GzwApiError:
+        code, message = "HTTP_ERROR", f"HTTP {exc.code}"
+        retry_after: Optional[float] = None
+        try:
+            retry_after = float(exc.headers.get("Retry-After")) if exc.headers and exc.headers.get("Retry-After") else None
+        except (TypeError, ValueError):
+            pass
+        try:
+            error = json.loads(exc.read().decode("utf-8")).get("error", {})
+            code = error.get("code", code)
+            message = error.get("message", message)
+        except (ValueError, AttributeError):
+            pass
+        return GzwApiError(message, status=exc.code, code=code, url=url, retry_after=retry_after)
+
+    # -- API ---------------------------------------------------------------
+
+    def datasets(self) -> dict[str, int]:
+        """Dataset name -> record count."""
+        stats = self.request("stats")["data"]
+        return {name: int(info.get("total", 0)) for name, info in stats.items()}
+
+    def list(self, dataset: str, *, page: int = 1, per_page: int = 50, search: Optional[str] = None, **filters: Any) -> dict[str, Any]:
+        """One page of a dataset. Returns the envelope (``data``, ``total``, ``totalPages`` ...)."""
+        return self.request(dataset, {"page": page, "per_page": per_page, "search": search, **filters})
+
+    def iterate(self, dataset: str, *, per_page: int = 100, search: Optional[str] = None, **filters: Any) -> Iterator[dict[str, Any]]:
+        """Yield every record of a dataset, following pagination."""
+        page = 1
+        while True:
+            payload = self.list(dataset, page=page, per_page=per_page, search=search, **filters)
+            yield from payload["data"]
+            if page >= int(payload.get("totalPages", 1)) or not payload["data"]:
+                return
+            page += 1
+
+    def get(self, dataset: str, record_id: str) -> Optional[dict[str, Any]]:
+        """One record by id, or ``None`` if it does not exist."""
+        try:
+            return self.request(f"{dataset}/{urllib.parse.quote(record_id, safe='')}")["data"]
+        except GzwApiError as exc:
+            if exc.code == "RECORD_NOT_FOUND":
+                return None
+            raise
+
+    def search(self, query: str) -> dict[str, list[dict[str, Any]]]:
+        """Search all datasets. Returns dataset name -> matching records."""
+        return self.request("search", {"q": query})["data"]["results"]

gzw_data-0.1.1/gzw_data.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: gzw-data
+Version: 0.1.1
+Summary: Python client for the free Gray Zone Warfare data API (gzw-data.dev)
+License-Expression: MIT
+Project-URL: Homepage, https://gzw-data.dev/
+Project-URL: Source, https://github.com/ZoniBoy00/gzw-data-py
+Keywords: gray-zone-warfare,gzw,api,game-data
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# gzw-data (Python)
+
+Dependency-free Python client for the free [Gray Zone Warfare data API](https://gzw-data.dev). Fan-made and not affiliated with the game's developer.
+
+```bash
+pip install git+https://github.com/ZoniBoy00/gzw-data-py
+```
+
+```python
+from gzw_data import GzwDataClient
+
+client = GzwDataClient()                       # no API key needed
+print(client.datasets())                       # {'ammo': 79, 'weapons': 44, ...}
+print(client.get("weapons", "ak-12")["name"])  # AK-12
+for ammo in client.iterate("ammo", search="5.56"):
+    print(ammo["name"])
+print(list(client.search("AK")))               # dataset names that matched
+```
+
+Errors raise `GzwApiError` (`.status`, `.code`, `.url`). Rate-limit (honouring `Retry-After`) and 5xx responses are retried with backoff.
+
+Game data comes from the community wiki and has its own terms: see the [data license](https://github.com/ZoniBoy00/gzw-data/blob/main/DATA_LICENSE.md). Code is MIT.
+
+## Development
+
+```bash
+python -m unittest discover -s tests
+```

gzw_data-0.1.1/gzw_data.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+gzw_data/__init__.py
+gzw_data/client.py
+gzw_data.egg-info/PKG-INFO
+gzw_data.egg-info/SOURCES.txt
+gzw_data.egg-info/dependency_links.txt
+gzw_data.egg-info/top_level.txt
+tests/test_client.py

gzw_data-0.1.1/gzw_data.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gzw_data-0.1.1/gzw_data.egg-info/top_level.txt

@@ -0,0 +1 @@
+gzw_data

gzw_data-0.1.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gzw-data"
+version = "0.1.1"
+description = "Python client for the free Gray Zone Warfare data API (gzw-data.dev)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+keywords = ["gray-zone-warfare", "gzw", "api", "game-data"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://gzw-data.dev/"
+Source = "https://github.com/ZoniBoy00/gzw-data-py"
+
+[tool.setuptools]
+packages = ["gzw_data"]

gzw_data-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gzw_data-0.1.1/tests/test_client.py

@@ -0,0 +1,117 @@
+import io
+import json
+import unittest
+import urllib.error
+
+from gzw_data import GzwApiError, GzwDataClient
+
+
+class FakeResponse(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def envelope(data, **extra):
+    return FakeResponse(json.dumps({"data": data, **extra}).encode())
+
+
+def http_error(req, status, code, message="err", headers=None):
+    body = json.dumps({"error": {"code": code, "message": message}}).encode()
+    return urllib.error.HTTPError(req.full_url, status, message, headers or {}, io.BytesIO(body))
+
+
+class ClientTests(unittest.TestCase):
+    def test_list_builds_query_and_skips_none(self):
+        seen = []
+
+        def opener(req, timeout):
+            seen.append(req.full_url)
+            return envelope([{"id": "a"}], totalPages=1)
+
+        GzwDataClient(opener=opener).list("weapons", page=2, per_page=5, caliber="5.56")
+        self.assertEqual(len(seen), 1)
+        self.assertIn("/weapons?", seen[0])
+        self.assertIn("page=2", seen[0])
+        self.assertIn("caliber=5.56", seen[0])
+        self.assertNotIn("search", seen[0])
+
+    def test_iterate_follows_pages(self):
+        pages = {"1": [{"id": 1}, {"id": 2}], "2": [{"id": 3}]}
+
+        def opener(req, timeout):
+            page = req.full_url.split("page=")[1].split("&")[0]
+            return envelope(pages[page], totalPages=2)
+
+        ids = [r["id"] for r in GzwDataClient(opener=opener).iterate("ammo")]
+        self.assertEqual(ids, [1, 2, 3])
+
+    def test_get_returns_none_when_missing(self):
+        def opener(req, timeout):
+            raise http_error(req, 404, "RECORD_NOT_FOUND")
+
+        self.assertIsNone(GzwDataClient(opener=opener).get("weapons", "x"))
+
+    def test_retries_then_raises_structured_error(self):
+        calls = []
+
+        def opener(req, timeout):
+            calls.append(1)
+            raise http_error(req, 429, "RATE_LIMITED")
+
+        client = GzwDataClient(opener=opener, retries=1)
+        with self.assertRaises(GzwApiError) as ctx:
+            client.request("stats")
+        self.assertEqual(len(calls), 2)
+        self.assertEqual(ctx.exception.code, "RATE_LIMITED")
+        self.assertEqual(ctx.exception.status, 429)
+
+    def test_honours_retry_after_header(self):
+        from unittest import mock
+
+        calls = []
+
+        def opener(req, timeout):
+            calls.append(1)
+            if len(calls) == 1:
+                raise http_error(req, 429, "RATE_LIMITED", headers={"Retry-After": "7"})
+            return envelope({"ok": True})
+
+        with mock.patch("gzw_data.client.time.sleep") as sleep:
+            result = GzwDataClient(opener=opener).request("health")
+        sleep.assert_called_once_with(7.0)
+        self.assertEqual(result["data"], {"ok": True})
+
+    def test_retry_after_is_capped(self):
+        from unittest import mock
+
+        def opener(req, timeout):
+            raise http_error(req, 429, "RATE_LIMITED", headers={"Retry-After": "600"})
+
+        with mock.patch("gzw_data.client.time.sleep") as sleep, self.assertRaises(GzwApiError) as ctx:
+            GzwDataClient(opener=opener, retries=1, max_retry_wait=30).request("health")
+        sleep.assert_called_once_with(30)
+        self.assertEqual(ctx.exception.retry_after, 600.0)
+
+    def test_does_not_retry_client_errors(self):
+        calls = []
+
+        def opener(req, timeout):
+            calls.append(1)
+            raise http_error(req, 400, "BAD_REQUEST")
+
+        with self.assertRaises(GzwApiError):
+            GzwDataClient(opener=opener).request("weapons")
+        self.assertEqual(len(calls), 1)
+
+    def test_datasets_maps_counts(self):
+        def opener(req, timeout):
+            return envelope({"ammo": {"total": 79}, "weapons": {"total": 44}})
+
+        self.assertEqual(GzwDataClient(opener=opener).datasets(), {"ammo": 79, "weapons": 44})
+
+
+if __name__ == "__main__":
+    unittest.main()