metagraphed 0.1.0__tar.gz

metagraphed-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+.pytest_cache/
+uv.lock

metagraphed-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: metagraphed
+Version: 0.1.0
+Summary: Thin Python client for metagraphed — the operational + integration registry for Bittensor subnets (api.metagraph.sh).
+Project-URL: Homepage, https://metagraph.sh
+Project-URL: Repository, https://github.com/JSONbored/metagraphed
+Author: JSONbored
+License: MIT
+Keywords: api-client,bittensor,metagraph,registry,subnet
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# metagraphed (Python)
+
+Thin, dependency-free Python client for **metagraphed** — the operational +
+integration registry for Bittensor subnets at `https://api.metagraph.sh`.
+
+It mirrors the [npm client](https://www.npmjs.com/package/@jsonbored/metagraphed):
+one generic GET helper over the uniform, read-only API surface, returning the
+parsed `{ ok, schema_version, data, meta }` envelope. Stdlib only — no transitive
+dependencies.
+
+## Install
+
+```bash
+pip install metagraphed
+```
+
+## Usage
+
+```python
+from metagraphed import MetagraphedClient, metagraphed_fetch
+
+client = MetagraphedClient()  # base_url defaults to https://api.metagraph.sh
+
+# List subnets (query params; None values are dropped)
+subnets = client.fetch(
+    "/api/v1/subnets",
+    query={"limit": 10, "sort": "completeness_score", "order": "desc"},
+)
+print(subnets["data"][0]["name"])
+
+# One subnet by netuid (path params)
+detail = client.fetch("/api/v1/subnets/{netuid}", path_params={"netuid": 7})
+
+# Which subnets are buildable? (integration readiness lives in the agent catalog)
+catalog = client.fetch("/api/v1/agent-catalog")
+
+# Point at the frontend origin instead, ad hoc:
+metagraphed_fetch("/api/v1/health", base_url="https://metagraph.sh")
+```
+
+Every response is the standard envelope:
+
+```python
+{"ok": True, "schema_version": 1, "data": ..., "meta": {...}}
+```
+
+On a network failure or non-2xx response, a `MetagraphedError` is raised (with
+`.status` for HTTP errors).
+
+## Versioning & stability
+
+Tracks the public `/api/v1` contract; changes are additive within v1. See the
+backend's [API stability policy](https://github.com/JSONbored/metagraphed/blob/main/docs/api-stability.md).
+
+## License
+
+MIT

metagraphed-0.1.0/PUBLISHING.md

@@ -0,0 +1,39 @@
+# Publishing `metagraphed` to PyPI
+
+Releases go out via **OIDC Trusted Publishing** — no API token is ever created
+or stored. The `.github/workflows/publish-python.yml` workflow builds the wheel +
+sdist in an unprivileged job and publishes from a separate privileged job, so no
+third-party code runs while the OIDC token is live.
+
+## One-time bootstrap (owner, no placeholder upload needed)
+
+1. **Confirm the project name is free** at <https://pypi.org/project/metagraphed/>
+   (a 404 means available). If it's taken, change `[project].name` in
+   `python/pyproject.toml`, the `pip install` command in the README, and the
+   PyPI Project Name field below to e.g. `metagraphed-client`.
+
+2. **Add a PyPI pending publisher** at
+   <https://pypi.org/manage/account/publishing/> → "Add a new pending publisher"
+   with EXACTLY:
+   - PyPI Project Name: `metagraphed`
+   - Owner: `JSONbored`
+   - Repository name: `metagraphed`
+   - Workflow name: `publish-python.yml`
+   - Environment name: `pypi-production`
+
+3. **Create the GitHub Environment** in repo Settings → Environments → New
+   environment named EXACTLY `pypi-production` (optionally add required reviewers
+   for a manual approval gate before each publish).
+
+That's it — no token, no bootstrap upload. The pending publisher converts to a
+normal Trusted Publisher on the first successful publish.
+
+## Cutting a release
+
+1. Bump `[project].version` in `python/pyproject.toml` (strict semver, no `v`
+   prefix) on `main`.
+2. Actions → **Publish Python SDK** → Run workflow.
+
+The release gate (`scripts/validate-python-release.sh`) refuses to run off
+`main`, requires strict semver, and aborts if the git tag `python-v<version>` or
+the PyPI version already exists.

metagraphed-0.1.0/README.md

@@ -0,0 +1,57 @@
+# metagraphed (Python)
+
+Thin, dependency-free Python client for **metagraphed** — the operational +
+integration registry for Bittensor subnets at `https://api.metagraph.sh`.
+
+It mirrors the [npm client](https://www.npmjs.com/package/@jsonbored/metagraphed):
+one generic GET helper over the uniform, read-only API surface, returning the
+parsed `{ ok, schema_version, data, meta }` envelope. Stdlib only — no transitive
+dependencies.
+
+## Install
+
+```bash
+pip install metagraphed
+```
+
+## Usage
+
+```python
+from metagraphed import MetagraphedClient, metagraphed_fetch
+
+client = MetagraphedClient()  # base_url defaults to https://api.metagraph.sh
+
+# List subnets (query params; None values are dropped)
+subnets = client.fetch(
+    "/api/v1/subnets",
+    query={"limit": 10, "sort": "completeness_score", "order": "desc"},
+)
+print(subnets["data"][0]["name"])
+
+# One subnet by netuid (path params)
+detail = client.fetch("/api/v1/subnets/{netuid}", path_params={"netuid": 7})
+
+# Which subnets are buildable? (integration readiness lives in the agent catalog)
+catalog = client.fetch("/api/v1/agent-catalog")
+
+# Point at the frontend origin instead, ad hoc:
+metagraphed_fetch("/api/v1/health", base_url="https://metagraph.sh")
+```
+
+Every response is the standard envelope:
+
+```python
+{"ok": True, "schema_version": 1, "data": ..., "meta": {...}}
+```
+
+On a network failure or non-2xx response, a `MetagraphedError` is raised (with
+`.status` for HTTP errors).
+
+## Versioning & stability
+
+Tracks the public `/api/v1` contract; changes are additive within v1. See the
+backend's [API stability policy](https://github.com/JSONbored/metagraphed/blob/main/docs/api-stability.md).
+
+## License
+
+MIT

metagraphed-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "metagraphed"
+version = "0.1.0"
+description = "Thin Python client for metagraphed — the operational + integration registry for Bittensor subnets (api.metagraph.sh)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "JSONbored" }]
+keywords = ["bittensor", "metagraph", "subnet", "registry", "api-client"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://metagraph.sh"
+Repository = "https://github.com/JSONbored/metagraphed"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/metagraphed"]

metagraphed-0.1.0/src/metagraphed/__init__.py

@@ -0,0 +1,17 @@
+"""metagraphed — thin Python client for the Bittensor subnet registry API."""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    MetagraphedClient,
+    MetagraphedError,
+    metagraphed_fetch,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "MetagraphedClient",
+    "MetagraphedError",
+    "metagraphed_fetch",
+    "__version__",
+]

metagraphed-0.1.0/src/metagraphed/client.py

@@ -0,0 +1,105 @@
+"""Thin Python client for the metagraphed API (https://api.metagraph.sh).
+
+Dependency-free (stdlib ``urllib`` only). Mirrors the generated TypeScript
+client: one generic GET helper over the uniform, read-only API surface,
+returning the parsed ``{ ok, schema_version, data, meta }`` envelope as a dict.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Mapping, Optional
+
+DEFAULT_BASE_URL = "https://api.metagraph.sh"
+_PATH_PARAM = re.compile(r"\{([^{}]+)\}")
+
+
+class MetagraphedError(Exception):
+    """Raised on a network failure or a non-2xx HTTP response."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+def _interpolate(path: str, path_params: Optional[Mapping[str, Any]]) -> str:
+    params = path_params or {}
+
+    def repl(match: "re.Match[str]") -> str:
+        name = match.group(1)
+        if name not in params or params[name] is None:
+            raise MetagraphedError(f"Missing path parameter: {name}")
+        return urllib.parse.quote(str(params[name]), safe="")
+
+    return _PATH_PARAM.sub(repl, path)
+
+
+def metagraphed_fetch(
+    path: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    path_params: Optional[Mapping[str, Any]] = None,
+    query: Optional[Mapping[str, Any]] = None,
+    headers: Optional[Mapping[str, str]] = None,
+    timeout: float = 30.0,
+) -> Any:
+    """GET ``path`` against metagraphed and return the parsed JSON envelope.
+
+    ``path`` may contain ``{name}`` segments filled from ``path_params``.
+    ``query`` values that are ``None`` are dropped. Raises
+    :class:`MetagraphedError` on a network failure or a non-2xx response.
+    """
+    url = base_url.rstrip("/") + _interpolate(path, path_params)
+    if query:
+        pairs = [(key, value) for key, value in query.items() if value is not None]
+        if pairs:
+            url += "?" + urllib.parse.urlencode(pairs, doseq=True)
+
+    request = urllib.request.Request(url, method="GET")
+    request.add_header("Accept", "application/json")
+    for key, value in (headers or {}).items():
+        request.add_header(key, value)
+
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            body = response.read().decode("utf-8")
+    except urllib.error.HTTPError as error:
+        raise MetagraphedError(
+            f"GET {url} failed: HTTP {error.code}", status=error.code
+        ) from error
+    except urllib.error.URLError as error:
+        raise MetagraphedError(f"GET {url} failed: {error.reason}") from error
+
+    return json.loads(body)
+
+
+class MetagraphedClient:
+    """Convenience wrapper binding a ``base_url`` + default ``timeout``."""
+
+    def __init__(
+        self, base_url: str = DEFAULT_BASE_URL, *, timeout: float = 30.0
+    ) -> None:
+        self.base_url = base_url
+        self.timeout = timeout
+
+    def fetch(
+        self,
+        path: str,
+        *,
+        path_params: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """GET ``path`` using this client's ``base_url`` + ``timeout``."""
+        return metagraphed_fetch(
+            path,
+            base_url=self.base_url,
+            path_params=path_params,
+            query=query,
+            headers=headers,
+            timeout=self.timeout,
+        )

metagraphed-0.1.0/tests/test_client.py

@@ -0,0 +1,89 @@
+"""Hermetic tests for the metagraphed client (urllib mocked, no network)."""
+
+import json
+import unittest
+import urllib.error
+from unittest import mock
+
+from metagraphed import MetagraphedClient, MetagraphedError, metagraphed_fetch
+
+
+class _FakeResponse:
+    def __init__(self, payload):
+        self._body = json.dumps(payload).encode("utf-8")
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+class ClientTest(unittest.TestCase):
+    def test_interpolates_path_params_and_sets_accept(self):
+        captured = {}
+
+        def fake_urlopen(request, timeout=None):
+            captured["url"] = request.full_url
+            captured["accept"] = request.get_header("Accept")
+            return _FakeResponse({"ok": True, "data": {"netuid": 7}})
+
+        with mock.patch("urllib.request.urlopen", fake_urlopen):
+            out = metagraphed_fetch(
+                "/api/v1/subnets/{netuid}", path_params={"netuid": 7}
+            )
+
+        self.assertEqual(captured["url"], "https://api.metagraph.sh/api/v1/subnets/7")
+        self.assertEqual(captured["accept"], "application/json")
+        self.assertEqual(out["data"]["netuid"], 7)
+
+    def test_missing_path_param_raises(self):
+        with self.assertRaises(MetagraphedError):
+            metagraphed_fetch("/api/v1/subnets/{netuid}")
+
+    def test_drops_none_query_values_and_encodes(self):
+        captured = {}
+
+        def fake_urlopen(request, timeout=None):
+            captured["url"] = request.full_url
+            return _FakeResponse({"ok": True})
+
+        with mock.patch("urllib.request.urlopen", fake_urlopen):
+            metagraphed_fetch(
+                "/api/v1/search",
+                query={"q": "image gen", "cursor": None, "limit": 5},
+            )
+
+        self.assertIn("q=image+gen", captured["url"])
+        self.assertIn("limit=5", captured["url"])
+        self.assertNotIn("cursor", captured["url"])
+
+    def test_base_url_override(self):
+        captured = {}
+
+        def fake_urlopen(request, timeout=None):
+            captured["url"] = request.full_url
+            return _FakeResponse({"ok": True})
+
+        with mock.patch("urllib.request.urlopen", fake_urlopen):
+            MetagraphedClient(base_url="https://metagraph.sh").fetch("/api/v1/health")
+
+        self.assertTrue(
+            captured["url"].startswith("https://metagraph.sh/api/v1/health")
+        )
+
+    def test_http_error_becomes_metagraphed_error(self):
+        def fake_urlopen(request, timeout=None):
+            raise urllib.error.HTTPError(request.full_url, 404, "Not Found", {}, None)
+
+        with mock.patch("urllib.request.urlopen", fake_urlopen):
+            with self.assertRaises(MetagraphedError) as ctx:
+                metagraphed_fetch("/api/v1/subnets/{netuid}", path_params={"netuid": 9999})
+        self.assertEqual(ctx.exception.status, 404)
+
+
+if __name__ == "__main__":
+    unittest.main()