whereq.cloud 0.1.0__py3-none-any.whl

whereq_cloud/__init__.py

@@ -0,0 +1,4 @@
+"""whereq.cloud — official Python SDK for the WhereQ data cloud (api.whereq.cloud)."""
+from whereq_cloud.client import Client, WhereqError, DEFAULT_BASE_URL, __version__
+
+__all__ = ["Client", "WhereqError", "DEFAULT_BASE_URL", "__version__"]

whereq_cloud/client.py

@@ -0,0 +1,152 @@
+"""whereq.cloud — official Python SDK for the WhereQ data cloud.
+
+A thin, typed-ish wrapper over the versioned ``/v1`` HTTP API at ``api.whereq.cloud``.
+Public endpoints work with no key; metered endpoints take a ``X-API-Key``.
+
+    from whereq_cloud import Client
+
+    wq = Client()                               # public access
+    wq = Client(api_key="wq_live_…")            # metered tier
+
+    wq.cost_of_living("us:California,ca:Ontario")
+    wq.prices(domain="rent", region="us", bedrooms=2)
+    wq.get("/v1/trending", limit=10)            # escape hatch for any endpoint
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://api.whereq.cloud"
+
+
+class WhereqError(Exception):
+    """Raised on a non-2xx API response."""
+
+    def __init__(self, status: int, message: str, url: str) -> None:
+        self.status = status
+        self.url = url
+        self.message = message
+        super().__init__(f"whereq.cloud API error {status} for {url}: {message}")
+
+
+class Client:
+    """Synchronous client for the whereq.cloud Data API.
+
+    Args:
+        api_key: optional ``wq_live_…`` key for metered endpoints (sent as ``X-API-Key``).
+        base_url: override the API base (default ``https://api.whereq.cloud``).
+        timeout: per-request timeout in seconds.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0) -> None:
+        headers = {"Accept": "application/json",
+                   "User-Agent": f"whereq.cloud-python/{__version__}"}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        self._http = httpx.Client(base_url=base_url.rstrip("/"), headers=headers, timeout=timeout)
+
+    # -- lifecycle -----------------------------------------------------------
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *_exc: Any) -> None:
+        self.close()
+
+    # -- core ----------------------------------------------------------------
+    def get(self, path: str, **params: Any) -> Any:
+        """GET any endpoint. ``None`` params are dropped. Returns parsed JSON."""
+        clean = {k: v for k, v in params.items() if v is not None}
+        r = self._http.get(path, params=clean)
+        if r.status_code >= 400:
+            try:
+                msg = r.json().get("detail") or r.text
+            except Exception:  # noqa: BLE001
+                msg = r.text
+            raise WhereqError(r.status_code, msg, str(r.url))
+        return r.json()
+
+    def get_text(self, path: str, **params: Any) -> str:
+        """GET a non-JSON endpoint (e.g. CSV export) as text."""
+        clean = {k: v for k, v in params.items() if v is not None}
+        r = self._http.get(path, params=clean)
+        if r.status_code >= 400:
+            raise WhereqError(r.status_code, r.text, str(r.url))
+        return r.text
+
+    # -- prices / cost of living --------------------------------------------
+    def prices(self, domain: Optional[str] = None, region: Optional[str] = None,
+               bedrooms: Optional[int] = None, q: Optional[str] = None,
+               limit: int = 60, offset: int = 0) -> Any:
+        """Cost-of-living price series (fuel | food | energy | housing | rent)."""
+        return self.get("/v1/prices", domain=domain, region=region, bedrooms=bedrooms,
+                        q=q, limit=limit, offset=offset)
+
+    def price(self, series_id: int) -> Any:
+        """One price series with its full history."""
+        return self.get(f"/v1/prices/{series_id}")
+
+    def prices_csv(self, domain: Optional[str] = None, region: Optional[str] = None,
+                   bedrooms: Optional[int] = None, q: Optional[str] = None) -> str:
+        """Bulk CSV export of matching price series."""
+        return self.get_text("/v1/prices/export", domain=domain, region=region,
+                             bedrooms=bedrooms, q=q)
+
+    def cost_of_living(self, places: str) -> Any:
+        """Compare cost of living across US states / CA provinces / metros.
+
+        ``places``: comma-separated ``region:name`` or ``m:<rent-series-id>``,
+        e.g. ``"us:California,ca:Ontario,m:3958"``.
+        """
+        return self.get("/v1/cost-of-living", places=places)
+
+    # -- discovery / facets --------------------------------------------------
+    def catalog(self) -> Any:
+        return self.get("/v1/catalog")
+
+    def categories(self) -> Any:
+        return self.get("/v1/categories")
+
+    def regions(self) -> Any:
+        return self.get("/v1/regions")
+
+    def domains(self) -> Any:
+        return self.get("/v1/domains")
+
+    def trending(self, **params: Any) -> Any:
+        return self.get("/v1/trending", **params)
+
+    # -- finance -------------------------------------------------------------
+    def hotstocks(self, limit: int = 20) -> Any:
+        return self.get("/v1/hotstocks", limit=limit)
+
+    def quotes(self, **params: Any) -> Any:
+        return self.get("/v1/quotes", **params)
+
+    def news(self, **params: Any) -> Any:
+        return self.get("/v1/news", **params)
+
+    def screener(self, **params: Any) -> Any:
+        return self.get("/v1/screener", **params)
+
+    def search(self, q: str, **params: Any) -> Any:
+        return self.get("/v1/search", q=q, **params)
+
+    # -- autos ---------------------------------------------------------------
+    def autos_recalls(self, **params: Any) -> Any:
+        return self.get("/v1/autos/recalls", **params)
+
+    def autos_listings(self, **params: Any) -> Any:
+        return self.get("/v1/autos/listings", **params)
+
+    def autos_fuel_economy(self, **params: Any) -> Any:
+        return self.get("/v1/autos/fuel-economy", **params)
+
+    def autos_models(self, **params: Any) -> Any:
+        return self.get("/v1/autos/models", **params)

whereq_cloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: whereq.cloud
+Version: 0.1.0
+Summary: Official Python SDK for the WhereQ data cloud (api.whereq.cloud)
+Project-URL: Homepage, https://whereq.cloud
+Project-URL: Documentation, https://api.whereq.cloud/docs
+Project-URL: Repository, https://github.com/whereq/whereq-cloud-python
+Author-email: WhereQ <whereq@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,cost-of-living,data,finance,prices,trending,whereq
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# whereq.cloud — Python SDK
+
+Official Python client for the [WhereQ data cloud](https://whereq.cloud) — the versioned,
+metered `/v1` API at **`api.whereq.cloud`**: cost-of-living prices, a cross-region
+cost-of-living comparison, trending hot-lists, autos, equities & market data, and more.
+
+Public endpoints work with no key; metered endpoints take an API key.
+
+## Install
+
+```bash
+pip install whereq.cloud
+```
+
+## Usage
+
+```python
+from whereq_cloud import Client
+
+wq = Client()                          # public access
+# wq = Client(api_key="wq_live_…")     # metered tier
+
+# Cost of living — compare US states, CA provinces, or metros (by rent-series id)
+print(wq.cost_of_living("us:California,ca:Ontario,m:3958"))
+
+# Prices — fuel | food | energy | housing | rent
+print(wq.prices(domain="rent", region="us", bedrooms=2, limit=10))
+print(wq.price(3958))                  # one series + full history
+
+# Bulk CSV export
+csv_text = wq.prices_csv(domain="fuel", region="us")
+
+# Discovery
+wq.catalog(); wq.categories(); wq.regions(); wq.domains()
+
+# Finance
+wq.hotstocks(limit=5)
+wq.screener(sector="Technology")
+
+# Escape hatch — call any /v1 endpoint directly
+wq.get("/v1/trending", limit=10)
+```
+
+Use it as a context manager to close the HTTP connection pool:
+
+```python
+with Client(api_key="wq_live_…") as wq:
+    data = wq.prices(domain="energy")
+```
+
+Errors raise `whereq_cloud.WhereqError` (with `.status`, `.message`, `.url`).
+
+## License
+
+MIT © WhereQ

whereq_cloud-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+whereq_cloud/__init__.py,sha256=qNcVzL0fCbZVTTnvFTK_8nlzs_oGCXG1bz-NVEH6L3A,244
+whereq_cloud/client.py,sha256=o4NZdhEmSninZpejMauAwJyKEvMd9vJIgWp6yauJx4k,5898
+whereq_cloud-0.1.0.dist-info/METADATA,sha256=vWdS8TqhlgL1DHAXoIjE-WpsbG2Nl9Fw6F0maHLji1k,2277
+whereq_cloud-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+whereq_cloud-0.1.0.dist-info/licenses/LICENSE,sha256=7iJyJ26_RwXP5mKCfMH0Evj9V8gqILHDZNCEbVlNkzg,1063
+whereq_cloud-0.1.0.dist-info/RECORD,,

whereq_cloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

whereq_cloud-0.1.0.dist-info/licenses/LICENSE

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