darak 0.1.0__tar.gz

darak-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.egg-info/
+dist/

darak-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: darak
+Version: 0.1.0
+Summary: Official Python client for the Darak API: Saudi real-estate listings and market data.
+Project-URL: Documentation, https://platform.darak.app/docs
+Project-URL: Changelog, https://platform.darak.app/changelog
+License-Expression: MIT
+Keywords: api,darak,listings,real-estate,saudi-arabia
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# darak
+
+The official Python client for the [Darak API](https://platform.darak.app/docs): every live rental and sale listing in Saudi Arabia, deduplicated across 13+ sources. Standard library only, Python 3.9+.
+
+```bash
+pip install darak
+```
+
+```python
+from darak import Darak, DarakError
+
+darak = Darak()  # reads DARAK_API_KEY
+
+page = darak.listings.search(city="riyadh", listing_type="rent", beds=3, limit=25)
+print(page["data"][0]["price"]["yearly_sar"])
+
+# Every result, fetching pages as you go (stops at your plan's paging depth).
+for listing in darak.listings.search_all(city="jeddah", listing_type="sale"):
+    print(listing["id"], listing["location"]["neighborhood_name_en"])
+
+try:
+    darak.listings.get(1)
+except DarakError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+Get a key at [platform.darak.app](https://platform.darak.app).
+
+- Lists are sent comma-separated: `property_type=["apartment", "villa"]`.
+- `429` and `5xx` (and network errors) are retried, honoring `Retry-After`. A monthly-quota `429` isn't waited out; it raises.
+- Methods: `listings.search / search_all / count / get / batch / price_history`, `cities.list / neighborhoods / directions`, `enums()`, `broker_listings(...)`, and `request(method, path, query, body)` for anything else.
+
+Tests: `python3 -m unittest discover -s tests`.

darak-0.1.0/README.md

@@ -0,0 +1,33 @@
+# darak
+
+The official Python client for the [Darak API](https://platform.darak.app/docs): every live rental and sale listing in Saudi Arabia, deduplicated across 13+ sources. Standard library only, Python 3.9+.
+
+```bash
+pip install darak
+```
+
+```python
+from darak import Darak, DarakError
+
+darak = Darak()  # reads DARAK_API_KEY
+
+page = darak.listings.search(city="riyadh", listing_type="rent", beds=3, limit=25)
+print(page["data"][0]["price"]["yearly_sar"])
+
+# Every result, fetching pages as you go (stops at your plan's paging depth).
+for listing in darak.listings.search_all(city="jeddah", listing_type="sale"):
+    print(listing["id"], listing["location"]["neighborhood_name_en"])
+
+try:
+    darak.listings.get(1)
+except DarakError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+Get a key at [platform.darak.app](https://platform.darak.app).
+
+- Lists are sent comma-separated: `property_type=["apartment", "villa"]`.
+- `429` and `5xx` (and network errors) are retried, honoring `Retry-After`. A monthly-quota `429` isn't waited out; it raises.
+- Methods: `listings.search / search_all / count / get / batch / price_history`, `cities.list / neighborhoods / directions`, `enums()`, `broker_listings(...)`, and `request(method, path, query, body)` for anything else.
+
+Tests: `python3 -m unittest discover -s tests`.

darak-0.1.0/darak/__init__.py

@@ -0,0 +1,13 @@
+"""Official Python client for the Darak API (https://platform.darak.app/docs).
+
+    from darak import Darak
+
+    darak = Darak()  # reads DARAK_API_KEY
+    for listing in darak.listings.search_all(city="riyadh", listing_type="rent"):
+        print(listing["id"], listing["price"]["yearly_sar"])
+"""
+
+from .client import Darak, DarakError
+
+__all__ = ["Darak", "DarakError"]
+__version__ = "0.1.0"

darak-0.1.0/darak/client.py

@@ -0,0 +1,240 @@
+"""The Darak API client. Standard library only: nothing else to install."""
+
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+
+__all__ = ["Darak", "DarakError"]
+
+JSON = Dict[str, Any]
+QueryValue = Union[str, int, float, bool, Sequence[Union[str, int]], None]
+
+DEFAULT_BASE_URL = "https://api.darak.app/v1"
+# Longest Retry-After worth sleeping through; longer (a monthly quota) raises.
+MAX_RETRY_WAIT_S = 60
+
+
+class DarakError(Exception):
+    """A non-2xx response. Branch on ``code``; ``message`` is for humans."""
+
+    def __init__(
+        self,
+        status: int,
+        type: str,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        param: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.type = type
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.param = param
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"DarakError(status={self.status}, code={self.code!r}, request_id={self.request_id!r})"
+
+
+def encode_query(query: Mapping[str, QueryValue]) -> str:
+    """Lists go comma-separated, as the API expects; None is dropped."""
+    parts = []
+    for key, value in query.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            value = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            value = ",".join(str(v) for v in value)
+        parts.append((key, str(value)))
+    return "?" + urllib.parse.urlencode(parts) if parts else ""
+
+
+class _Response:
+    def __init__(self, status: int, headers: Mapping[str, str], body: bytes) -> None:
+        self.status = status
+        self.headers = {k.lower(): v for k, v in headers.items()}
+        self.body = body
+
+
+Transport = Callable[[urllib.request.Request, float], _Response]
+
+
+def _urllib_transport(request: urllib.request.Request, timeout: float) -> _Response:
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as res:  # noqa: S310 (https URL)
+            return _Response(res.status, dict(res.headers), res.read())
+    except urllib.error.HTTPError as err:
+        return _Response(err.code, dict(err.headers or {}), err.read() or b"")
+
+
+class Darak:
+    """Client for the Darak API.
+
+    Args:
+        api_key: Defaults to the ``DARAK_API_KEY`` environment variable.
+        base_url: Defaults to https://api.darak.app/v1.
+        max_retries: Retries for 429, 5xx and network errors (default 2).
+        timeout: Seconds per attempt (default 30).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 30.0,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        key = api_key or os.environ.get("DARAK_API_KEY")
+        if not key:
+            raise ValueError("Pass api_key or set DARAK_API_KEY. Get a key at https://platform.darak.app.")
+        self._api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._transport = transport or _urllib_transport
+        self._sleep = time.sleep
+        self.listings = _Listings(self)
+        self.cities = _Cities(self)
+
+    # ── Low level ─────────────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        query: Optional[Mapping[str, QueryValue]] = None,
+        body: Optional[Any] = None,
+    ) -> JSON:
+        """Calls any endpoint; prefer the typed helpers."""
+        url = f"{self.base_url}{path}{encode_query(query or {})}"
+        data = json.dumps(body).encode() if body is not None else None
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": "darak-python/0.1.0",
+        }
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                res = self._transport(request, self.timeout)
+            except (urllib.error.URLError, TimeoutError, ConnectionError):
+                if attempt < self.max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise
+            if 200 <= res.status < 300:
+                return json.loads(res.body or b"{}")
+
+            error = _to_error(res)
+            retryable = res.status == 429 or res.status >= 500
+            wait = error.retry_after if error.retry_after is not None else _backoff(attempt)
+            if retryable and attempt < self.max_retries and wait <= MAX_RETRY_WAIT_S:
+                self._sleep(wait)
+                attempt += 1
+                continue
+            raise error
+
+    # ── Reference data ────────────────────────────────────────────────────
+
+    def enums(self) -> JSON:
+        """Allowed values for enum parameters (sources, property types, …)."""
+        return self.request("GET", "/enums")
+
+    def broker_listings(self, **body: Any) -> JSON:
+        """Enterprise plans: listings by broker commercial registration."""
+        return self.request("POST", "/broker-listings", body=body)
+
+
+class _Listings:
+    def __init__(self, client: Darak) -> None:
+        self._c = client
+
+    def search(self, **params: QueryValue) -> JSON:
+        """One page. Follow ``pagination.next_cursor``, or use ``search_all``."""
+        return self._c.request("GET", "/listings", params)
+
+    def search_all(self, **params: QueryValue) -> Iterator[JSON]:
+        """Every matching listing, fetching pages as you iterate. Stops at the
+        end of the results or at your plan's paging depth."""
+        params.pop("cursor", None)
+        cursor: Optional[str] = None
+        while True:
+            page = self.search(**params, cursor=cursor)
+            yield from page.get("data", [])
+            pagination = page.get("pagination") or {}
+            cursor = pagination.get("next_cursor") if pagination.get("has_more") else None
+            if not cursor:
+                return
+
+    def count(self, **params: QueryValue) -> JSON:
+        return self._c.request("GET", "/listings/count", params)
+
+    def get(self, listing_id: int) -> JSON:
+        return self._c.request("GET", f"/listings/{int(listing_id)}")
+
+    def batch(self, ids: Sequence[int]) -> JSON:
+        """Ids that aren't live come back in ``missing_ids``."""
+        return self._c.request("GET", "/listings/batch", {"ids": list(ids)})
+
+    def price_history(self, listing_id: int) -> JSON:
+        return self._c.request("GET", f"/listings/{int(listing_id)}/price-history")
+
+
+class _Cities:
+    def __init__(self, client: Darak) -> None:
+        self._c = client
+
+    def list(self) -> JSON:
+        return self._c.request("GET", "/cities")
+
+    def neighborhoods(self, city: str) -> JSON:
+        return self._c.request("GET", f"/cities/{urllib.parse.quote(city)}/neighborhoods")
+
+    def directions(self, city: str) -> JSON:
+        return self._c.request("GET", f"/cities/{urllib.parse.quote(city)}/directions")
+
+
+def _backoff(attempt: int) -> float:
+    """~0.5s, 1s, 2s … with jitter."""
+    return min(8.0, 0.5 * 2**attempt) * (0.75 + random.random() * 0.5)
+
+
+def _to_error(res: _Response) -> DarakError:
+    try:
+        payload = json.loads(res.body or b"{}").get("error") or {}
+    except ValueError:
+        payload = {}
+    retry_after: Optional[float] = None
+    if "retry-after" in res.headers:
+        try:
+            retry_after = float(res.headers["retry-after"])
+        except ValueError:
+            retry_after = None
+    return DarakError(
+        status=res.status,
+        type=payload.get("type", "api_error"),
+        code=payload.get("code", f"http_{res.status}"),
+        message=payload.get("message", f"The API returned HTTP {res.status}."),
+        request_id=payload.get("request_id") or res.headers.get("x-request-id"),
+        param=payload.get("param"),
+        retry_after=retry_after,
+    )

darak-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "darak"
+version = "0.1.0"
+description = "Official Python client for the Darak API: Saudi real-estate listings and market data."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["darak", "real-estate", "saudi-arabia", "api", "listings"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://platform.darak.app/docs"
+Changelog = "https://platform.darak.app/changelog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["darak"]

darak-0.1.0/tests/test_client.py

@@ -0,0 +1,108 @@
+import json
+import os
+import unittest
+import urllib.error
+
+from darak import Darak, DarakError
+from darak.client import _Response, encode_query
+
+
+class FakeTransport:
+    """Answers from a queue and records the requests."""
+
+    def __init__(self, *replies):
+        self.replies = list(replies)
+        self.requests = []
+
+    def __call__(self, request, timeout):
+        self.requests.append(request)
+        reply = self.replies.pop(0) if self.replies else (200, {}, {})
+        if isinstance(reply, Exception):
+            raise reply
+        status, headers, body = reply
+        return _Response(status, headers, json.dumps(body).encode())
+
+
+def client(transport, **kw):
+    c = Darak("dk_live_test", base_url="https://api.test/v1", transport=transport, **kw)
+    c._sleep = lambda s: None  # no real waiting in tests
+    return c
+
+
+class EncodeQueryTest(unittest.TestCase):
+    def test_lists_bools_and_none(self):
+        self.assertEqual(
+            encode_query({"city": "riyadh", "property_type": ["apartment", "villa"], "furnished": True, "beds": None}),
+            "?city=riyadh&property_type=apartment%2Cvilla&furnished=true",
+        )
+        self.assertEqual(encode_query({}), "")
+
+
+class ClientTest(unittest.TestCase):
+    def test_sends_bearer_key_and_parses_json(self):
+        t = FakeTransport((200, {}, {"data": [{"slug": "riyadh"}]}))
+        self.assertEqual(client(t).cities.list(), {"data": [{"slug": "riyadh"}]})
+        self.assertEqual(t.requests[0].full_url, "https://api.test/v1/cities")
+        self.assertEqual(t.requests[0].get_header("Authorization"), "Bearer dk_live_test")
+
+    def test_needs_a_key(self):
+        saved = os.environ.pop("DARAK_API_KEY", None)
+        try:
+            with self.assertRaises(ValueError):
+                Darak()
+        finally:
+            if saved is not None:
+                os.environ["DARAK_API_KEY"] = saved
+
+    def test_retries_429_and_5xx(self):
+        t = FakeTransport(
+            (429, {"Retry-After": "2"}, {"error": {"code": "rate_limited"}}),
+            (503, {}, {}),
+            (200, {}, {"data": []}),
+        )
+        waits = []
+        c = client(t)
+        c._sleep = waits.append
+        self.assertEqual(c.enums(), {"data": []})
+        self.assertEqual(len(t.requests), 3)
+        self.assertEqual(waits[0], 2.0)
+
+    def test_does_not_wait_out_a_monthly_quota(self):
+        t = FakeTransport(
+            (
+                429,
+                {"Retry-After": "86400", "X-Request-Id": "req_1"},
+                {"error": {"type": "rate_limit_error", "code": "monthly_quota_exceeded", "message": "over"}},
+            )
+        )
+        with self.assertRaises(DarakError) as ctx:
+            client(t).enums()
+        e = ctx.exception
+        self.assertEqual((e.status, e.code, e.request_id, e.retry_after), (429, "monthly_quota_exceeded", "req_1", 86400.0))
+        self.assertEqual(len(t.requests), 1)
+
+    def test_client_errors_are_not_retried(self):
+        t = FakeTransport((400, {}, {"error": {"type": "invalid_request", "code": "unknown_parameter", "param": "bed"}}))
+        with self.assertRaises(DarakError) as ctx:
+            client(t).listings.count(city="riyadh", listing_type="rent", bed=2)
+        self.assertEqual(ctx.exception.param, "bed")
+        self.assertEqual(len(t.requests), 1)
+
+    def test_network_errors_retry_then_raise(self):
+        t = FakeTransport(urllib.error.URLError("down"), urllib.error.URLError("down"))
+        with self.assertRaises(urllib.error.URLError):
+            client(t, max_retries=1).enums()
+        self.assertEqual(len(t.requests), 2)
+
+    def test_search_all_follows_cursors(self):
+        def page(ids, nxt):
+            return (200, {}, {"data": [{"id": i} for i in ids], "pagination": {"next_cursor": nxt, "has_more": nxt is not None}})
+
+        t = FakeTransport(page([1, 2], "c2"), page([3], None))
+        ids = [l["id"] for l in client(t).listings.search_all(city="riyadh", listing_type="rent", limit=2)]
+        self.assertEqual(ids, [1, 2, 3])
+        self.assertIn("cursor=c2", t.requests[1].full_url)
+
+
+if __name__ == "__main__":
+    unittest.main()