gzw-data 0.1.1__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+gzw_data/__init__.py,sha256=W4Vf9ytQtWJK21yAKgZ5xBtT2nRjuczhE7HEaI2Yp0c,198
+gzw_data/client.py,sha256=xfn9VLfEgGWOjs8CLFhDKTktZzR7wzvSsSG3aCwTASk,5385
+gzw_data-0.1.1.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+gzw_data-0.1.1.dist-info/METADATA,sha256=bSyp6VWOPv4AVUR11YUNUTB3eb07RWMwjldSSzVNP0k,1433
+gzw_data-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gzw_data-0.1.1.dist-info/top_level.txt,sha256=k5kHgwU0d_hZs8yBrWNGLKIlmitdIkXzdLdnsoKqgFE,9
+gzw_data-0.1.1.dist-info/RECORD,,

gzw_data-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gzw_data-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

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