qovia 0.1.0__tar.gz

qovia-0.1.0/LICENSE

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

qovia-0.1.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: qovia
+Version: 0.1.0
+Summary: Python client for Qovia: public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, TikTok, YouTube and 20+ platforms as unified JSON
+Author-email: Qovia <scott@qovia.ai>
+License: MIT
+Project-URL: Homepage, https://qovia.ai
+Project-URL: Documentation, https://qovia.ai/docs/
+Project-URL: Source, https://github.com/qovia/qovia-mcp
+Keywords: qovia,douyin,xiaohongshu,rednote,weibo,bilibili,tiktok,social media,api,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# qovia
+
+Python client for [Qovia](https://qovia.ai): public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, Kuaishou, Zhihu, WeChat Official Accounts, Taobao/JD reviews, the Xingtu and Pugongying creator marketplaces, TikTok, YouTube, Instagram, X and Reddit, as unified JSON. No dependencies.
+
+```bash
+pip install qovia
+```
+
+```python
+from qovia import Qovia, QoviaError
+
+client = Qovia()  # reads QOVIA_API_KEY; create a key at https://qovia.ai/console/?tab=keys
+
+notes = client.get("/v1/raw/xiaohongshu/search", keyword="coffee", sort="latest")
+for note in notes.data["items"]:
+    print(note["extra"]["url"], note["text"][:60])
+print("charged", notes.charged_usd)
+
+hot = client.get("/v1/raw/weibo/hot_search")
+results = client.search("electric vehicles", platforms=["weibo", "douyin"])
+
+try:
+    client.get("/v1/raw/douyin/video", item_id="not-a-real-id")
+except QoviaError as error:
+    print(error.code, error.request_id)
+```
+
+- `get(path, **params)` and `post(path, body)` call any endpoint; the [API reference](https://qovia.ai/docs/api-reference/) lists them all.
+- A `Response` has `data`, `meta`, `charged_usd`, `balance_usd` and `empty`. Empty results and errors are never charged.
+- `pages(path, ...)` walks page-numbered endpoints until `has_more` is false.
+- 429 and 503 answers are retried (honouring `Retry-After`); other errors raise `QoviaError` with `code`, `message` and `request_id`.
+
+New accounts get 50 trial calls. Questions: [Telegram @wodaemn](https://t.me/wodaemn) or scott@qovia.ai.

qovia-0.1.0/README.md

@@ -0,0 +1,33 @@
+# qovia
+
+Python client for [Qovia](https://qovia.ai): public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, Kuaishou, Zhihu, WeChat Official Accounts, Taobao/JD reviews, the Xingtu and Pugongying creator marketplaces, TikTok, YouTube, Instagram, X and Reddit, as unified JSON. No dependencies.
+
+```bash
+pip install qovia
+```
+
+```python
+from qovia import Qovia, QoviaError
+
+client = Qovia()  # reads QOVIA_API_KEY; create a key at https://qovia.ai/console/?tab=keys
+
+notes = client.get("/v1/raw/xiaohongshu/search", keyword="coffee", sort="latest")
+for note in notes.data["items"]:
+    print(note["extra"]["url"], note["text"][:60])
+print("charged", notes.charged_usd)
+
+hot = client.get("/v1/raw/weibo/hot_search")
+results = client.search("electric vehicles", platforms=["weibo", "douyin"])
+
+try:
+    client.get("/v1/raw/douyin/video", item_id="not-a-real-id")
+except QoviaError as error:
+    print(error.code, error.request_id)
+```
+
+- `get(path, **params)` and `post(path, body)` call any endpoint; the [API reference](https://qovia.ai/docs/api-reference/) lists them all.
+- A `Response` has `data`, `meta`, `charged_usd`, `balance_usd` and `empty`. Empty results and errors are never charged.
+- `pages(path, ...)` walks page-numbered endpoints until `has_more` is false.
+- 429 and 503 answers are retried (honouring `Retry-After`); other errors raise `QoviaError` with `code`, `message` and `request_id`.
+
+New accounts get 50 trial calls. Questions: [Telegram @wodaemn](https://t.me/wodaemn) or scott@qovia.ai.

qovia-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qovia"
+version = "0.1.0"
+description = "Python client for Qovia: public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, TikTok, YouTube and 20+ platforms as unified JSON"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Qovia", email = "scott@qovia.ai" }]
+keywords = ["qovia", "douyin", "xiaohongshu", "rednote", "weibo", "bilibili", "tiktok", "social media", "api", "mcp"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Topic :: Internet :: WWW/HTTP",
+]
+
+[project.urls]
+Homepage = "https://qovia.ai"
+Documentation = "https://qovia.ai/docs/"
+Source = "https://github.com/qovia/qovia-mcp"
+
+[tool.setuptools]
+packages = ["qovia"]

qovia-0.1.0/qovia/__init__.py

@@ -0,0 +1,15 @@
+"""Python client for the Qovia public web data API (https://qovia.ai).
+
+    from qovia import Qovia
+
+    client = Qovia()  # reads QOVIA_API_KEY
+    notes = client.get("/v1/raw/xiaohongshu/search", keyword="coffee")
+    for note in notes.data["items"]:
+        print(note["extra"]["url"], note["text"][:60])
+    print(notes.charged_usd)
+"""
+
+from qovia.client import Qovia, QoviaError, Response
+
+__all__ = ["Qovia", "QoviaError", "Response"]
+__version__ = "0.1.0"

qovia-0.1.0/qovia/client.py

@@ -0,0 +1,152 @@
+"""A small, dependency-free client: one method per HTTP verb, the response envelope unpacked, errors raised.
+
+Every success is {"request_id", "data", "meta"}; every error is {"error": {"code", "message", "request_id",
+"support"}}. Calls are billed only when they return data, and meta says what each one cost.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+DEFAULT_BASE_URL = "https://api.qovia.ai"
+USER_AGENT = "qovia-python/0.1.0"
+
+
+class QoviaError(Exception):
+    """An error answer from the API. Branch on `code` (see https://qovia.ai/docs/), never on the message."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: str | None = None,
+                 retry_after: float | None = None) -> None:
+        super().__init__(f"{status} {code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.retry_after = retry_after
+
+
+@dataclass
+class Response:
+    """One successful call: the data plus what it cost."""
+
+    request_id: str
+    data: Any
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def empty(self) -> bool:
+        """True when nothing was found (and nothing was charged)."""
+        return bool(self.meta.get("empty"))
+
+    @property
+    def charged_usd(self) -> str:
+        return str(self.meta.get("charged_usd", "0"))
+
+    @property
+    def balance_usd(self) -> str | None:
+        value = self.meta.get("balance_usd")
+        return None if value is None else str(value)
+
+
+class Qovia:
+    """Client for https://api.qovia.ai.
+
+    api_key: defaults to the QOVIA_API_KEY environment variable. Create one at
+             https://qovia.ai/console/?tab=keys (new accounts get 50 trial calls).
+    max_retries: retries on 429 and 503 answers, honouring Retry-After (calls that fail are never charged).
+    """
+
+    def __init__(self, api_key: str | None = None, *, base_url: str = DEFAULT_BASE_URL, timeout: float = 60,
+                 max_retries: int = 2) -> None:
+        self.api_key = api_key or os.environ.get("QOVIA_API_KEY")
+        if not self.api_key:
+            raise ValueError("pass api_key or set QOVIA_API_KEY (create a key at https://qovia.ai/console/?tab=keys)")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    # ------------------------------------------------------------------ calls
+
+    def get(self, path: str, **params: Any) -> Response:
+        """Call a GET endpoint, e.g. client.get("/v1/raw/douyin/video", item_id="...")."""
+        query = {key: _query_value(value) for key, value in params.items() if value is not None}
+        url = self._url(path) + ("?" + urllib.parse.urlencode(query) if query else "")
+        return self._send("GET", url, None)
+
+    def post(self, path: str, body: dict[str, Any] | None = None, **fields: Any) -> Response:
+        """Call a POST endpoint with a JSON body, e.g. client.post("/v1/search", query="coffee")."""
+        payload = {**(body or {}), **fields}
+        return self._send("POST", self._url(path), json.dumps(payload).encode())
+
+    def account(self) -> Response:
+        """Balance, plan and rate limit for this key. Not charged."""
+        return self.get("/v1/account")
+
+    def search(self, query: str, **filters: Any) -> Response:
+        """Cross-platform search over Chinese public sources (POST /v1/search)."""
+        return self.post("/v1/search", query=query, **filters)
+
+    def pages(self, path: str, *, page_param: str = "page", start: int = 1, max_pages: int = 10,
+              **params: Any):
+        """Yield page after page of a page-numbered GET endpoint until has_more is false or max_pages."""
+        for page in range(start, start + max_pages):
+            response = self.get(path, **{**params, page_param: page})
+            yield response
+            if response.empty or not (isinstance(response.data, dict) and response.data.get("has_more")):
+                return
+
+    # ------------------------------------------------------------------ plumbing
+
+    def _url(self, path: str) -> str:
+        return self.base_url + ("" if path.startswith("/") else "/") + path
+
+    def _send(self, method: str, url: str, body: bytes | None) -> Response:
+        headers = {"Authorization": f"Bearer {self.api_key}", "User-Agent": USER_AGENT, "Accept": "application/json"}
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=body, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(request, timeout=self.timeout) as answer:
+                    envelope = json.load(answer)
+                return Response(envelope.get("request_id", ""), envelope.get("data"), envelope.get("meta") or {})
+            except urllib.error.HTTPError as answer:
+                error = _error_from(answer)
+                if error.status in (429, 503) and attempt < self.max_retries:
+                    attempt += 1
+                    time.sleep(error.retry_after if error.retry_after is not None else 2 ** attempt)
+                    continue
+                raise error from None
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (list, tuple)):
+        return ",".join(str(item) for item in value)
+    return str(value)
+
+
+def _error_from(answer: urllib.error.HTTPError) -> QoviaError:
+    retry_after = answer.headers.get("Retry-After") if answer.headers else None
+    try:
+        retry = float(retry_after) if retry_after else None
+    except ValueError:
+        retry = None
+    try:
+        payload = json.loads(answer.read() or b"{}")
+    except ValueError:
+        payload = {}
+    error = payload.get("error") if isinstance(payload, dict) else None
+    if isinstance(error, dict):
+        return QoviaError(answer.code, str(error.get("code", "error")), str(error.get("message", "")),
+                          error.get("request_id"), retry)
+    return QoviaError(answer.code, "http_error", str(payload.get("detail") or answer.reason), None, retry)

qovia-0.1.0/qovia.egg-info/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: qovia
+Version: 0.1.0
+Summary: Python client for Qovia: public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, TikTok, YouTube and 20+ platforms as unified JSON
+Author-email: Qovia <scott@qovia.ai>
+License: MIT
+Project-URL: Homepage, https://qovia.ai
+Project-URL: Documentation, https://qovia.ai/docs/
+Project-URL: Source, https://github.com/qovia/qovia-mcp
+Keywords: qovia,douyin,xiaohongshu,rednote,weibo,bilibili,tiktok,social media,api,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# qovia
+
+Python client for [Qovia](https://qovia.ai): public data from Douyin, Xiaohongshu (RedNote), Weibo, Bilibili, Kuaishou, Zhihu, WeChat Official Accounts, Taobao/JD reviews, the Xingtu and Pugongying creator marketplaces, TikTok, YouTube, Instagram, X and Reddit, as unified JSON. No dependencies.
+
+```bash
+pip install qovia
+```
+
+```python
+from qovia import Qovia, QoviaError
+
+client = Qovia()  # reads QOVIA_API_KEY; create a key at https://qovia.ai/console/?tab=keys
+
+notes = client.get("/v1/raw/xiaohongshu/search", keyword="coffee", sort="latest")
+for note in notes.data["items"]:
+    print(note["extra"]["url"], note["text"][:60])
+print("charged", notes.charged_usd)
+
+hot = client.get("/v1/raw/weibo/hot_search")
+results = client.search("electric vehicles", platforms=["weibo", "douyin"])
+
+try:
+    client.get("/v1/raw/douyin/video", item_id="not-a-real-id")
+except QoviaError as error:
+    print(error.code, error.request_id)
+```
+
+- `get(path, **params)` and `post(path, body)` call any endpoint; the [API reference](https://qovia.ai/docs/api-reference/) lists them all.
+- A `Response` has `data`, `meta`, `charged_usd`, `balance_usd` and `empty`. Empty results and errors are never charged.
+- `pages(path, ...)` walks page-numbered endpoints until `has_more` is false.
+- 429 and 503 answers are retried (honouring `Retry-After`); other errors raise `QoviaError` with `code`, `message` and `request_id`.
+
+New accounts get 50 trial calls. Questions: [Telegram @wodaemn](https://t.me/wodaemn) or scott@qovia.ai.

qovia-0.1.0/qovia.egg-info/SOURCES.txt

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

qovia-0.1.0/qovia.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

qovia-0.1.0/qovia.egg-info/top_level.txt

@@ -0,0 +1 @@
+qovia

qovia-0.1.0/setup.cfg

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

qovia-0.1.0/tests/test_client.py

@@ -0,0 +1,81 @@
+import json
+import threading
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+from qovia import Qovia, QoviaError
+
+CALLS = []
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def _reply(self, status, body, headers=None):
+        raw = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        for key, value in (headers or {}).items():
+            self.send_header(key, value)
+        self.end_headers()
+        self.wfile.write(raw)
+
+    def do_GET(self):
+        CALLS.append(("GET", self.path, self.headers.get("Authorization")))
+        if self.path.startswith("/v1/busy") and sum(1 for c in CALLS if c[1].startswith("/v1/busy")) < 2:
+            return self._reply(429, {"error": {"code": "rate_limited", "message": "slow down", "request_id": "r0"}},
+                               {"Retry-After": "0"})
+        if self.path.startswith("/v1/missing"):
+            return self._reply(400, {"error": {"code": "invalid_params", "message": "bad", "request_id": "r1",
+                                               "support": "https://t.me/wodaemn"}})
+        page = int(self.path.split("page=")[1]) if "page=" in self.path else 1
+        return self._reply(200, {"request_id": "r2", "data": {"items": [page], "has_more": page < 3},
+                                 "meta": {"billed": True, "charged_usd": "0.005000", "empty": False}})
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        CALLS.append(("POST", self.path, json.loads(self.rfile.read(length))))
+        return self._reply(200, {"request_id": "r3", "data": {"items": []}, "meta": {"empty": True}})
+
+
+@pytest.fixture
+def client():
+    CALLS.clear()
+    server = HTTPServer(("127.0.0.1", 0), Handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    yield Qovia("sk-qovia-test", base_url=f"http://127.0.0.1:{server.server_port}")
+    server.shutdown()
+
+
+def test_get_unpacks_the_envelope(client):
+    response = client.get("/v1/raw/xiaohongshu/search", keyword="coffee", sort=None, tags=["a", "b"])
+    assert response.data["items"] == [1] and response.charged_usd == "0.005000" and not response.empty
+    assert CALLS[0] == ("GET", "/v1/raw/xiaohongshu/search?keyword=coffee&tags=a%2Cb", "Bearer sk-qovia-test")
+
+
+def test_post_sends_json(client):
+    response = client.search("coffee", platforms=["weibo"])
+    assert response.empty
+    assert CALLS[0] == ("POST", "/v1/search", {"query": "coffee", "platforms": ["weibo"]})
+
+
+def test_errors_raise_with_code_and_request_id(client):
+    with pytest.raises(QoviaError) as caught:
+        client.get("/v1/missing")
+    assert (caught.value.status, caught.value.code, caught.value.request_id) == (400, "invalid_params", "r1")
+
+
+def test_rate_limits_are_retried(client):
+    assert client.get("/v1/busy").request_id == "r2"
+
+
+def test_pages_stop_when_has_more_is_false(client):
+    assert [r.data["items"][0] for r in client.pages("/v1/raw/x", max_pages=10)] == [1, 2, 3]
+
+
+def test_a_key_is_required(monkeypatch):
+    monkeypatch.delenv("QOVIA_API_KEY", raising=False)
+    with pytest.raises(ValueError):
+        Qovia()