kite-sa 0.3.0__py3-none-any.whl

kite_sa/__init__.py

@@ -0,0 +1,13 @@
+"""Official Python client for the Kite API (https://platform.kite.sa/docs).
+
+    from kite_sa import Kite
+
+    kite = Kite()  # reads KITE_API_KEY
+    for listing in kite.listings.search_all(city="riyadh", listing_type="rent"):
+        print(listing["id"], listing["price"]["yearly_sar"])
+"""
+
+from .client import Kite, KiteError
+
+__all__ = ["Kite", "KiteError"]
+__version__ = "0.3.0"

kite_sa/_generated.py

@@ -0,0 +1,455 @@
+# Generated from src/lib/api-v1/openapi.v1.json (spec 1a42b6a863454caf).
+# Do not edit: run `python packages/sdk-python/scripts/generate.py`.
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Union
+from urllib.parse import quote
+
+JSON = Any
+QueryValue = Any
+
+
+def _idempotency_headers(key: Optional[str]) -> Optional[Dict[str, str]]:
+    return {"Idempotency-Key": key} if key else None
+
+
+class _Analytics:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def deals(self, **params: QueryValue) -> JSON:
+        """
+        Find below-market listings. Residential listings asking noticeably less than
+        similar listings nearby, biggest gap first. Each listing is compared with
+        Darak's published nearby asking-price comparison: the same property type and
+        bedroom count, a similar area, within a calibrated radius and look-back
+        (disclosed per listing in `comparison`), one observation per distinct unit, and
+        the subject's own duplicates excluded
+        """
+        return self._c.request("GET", "/market/deals", params)
+
+    def listing_comparables(self, id: Union[int, str], **params: QueryValue) -> JSON:
+        """
+        Get comparable listings. Active listings similar to this one, nearest first,
+        with how each one differs. A comparable has the same city, listing type and
+        property type, is within about 5 km, and has an area between 2/3 and 1.5 times
+        this listing's (the comparison-approach caliper)
+        """
+        return self._c.request("GET", f"/listings/{quote(str(id))}/comparables", params)
+
+    def listing_market_position(self, id: Union[int, str]) -> JSON:
+        """
+        Get a listing's market position. Where a listing's price sits in its market:
+        percentile, quartiles and difference from the median, against like-for-like
+        listings in its neighborhood and in its city. The cohort is listings with the
+        same listing type, category and property type, and for residential listings the
+        same bedroom count
+        """
+        return self._c.request("GET", f"/listings/{quote(str(id))}/market-position")
+
+    def listing_price_band(self, id: Union[int, str]) -> JSON:
+        """
+        Get a listing's nearby asking-price band. The 25th percentile, median and 75th
+        percentile of asking prices for comparable units near this listing, in SAR and
+        per m², where this listing's price sits against them, and the cohort and
+        stability behind the numbers
+        """
+        return self._c.request("GET", f"/listings/{quote(str(id))}/price-band")
+
+    def neighborhoods_compare(self, **params: QueryValue) -> JSON:
+        """
+        Compare neighborhoods. Side-by-side profile of 2 to 5 neighborhoods: price
+        quartiles, area, price per m², amenity shares, bedroom and property-type mix,
+        and for rentals the gross yield against the same cohort's sale prices
+        """
+        return self._c.request("GET", "/market/neighborhoods/compare", params)
+
+    def rental_yield(self, **params: QueryValue) -> JSON:
+        """
+        Get gross rental yield. Gross rental yield (median yearly asking rent ÷ median
+        asking sale price) for one property type, over the whole city (or the requested
+        neighborhoods) and per neighborhood, highest yield first. Rent and sale medians
+        come from the same cohort (property type, and bedrooms if given) in the same
+        area
+        """
+        return self._c.request("GET", "/market/rental-yield", params)
+
+    def trends(self, **params: QueryValue) -> JSON:
+        """
+        Get price trends. Monthly median asking price over recent months (up to 36), for
+        a city or for up to five neighborhoods (one series each). Computed from Darak's
+        listing history, not from today's listings: every listing Darak has recorded,
+        including ones since rented, sold or removed, and every price change (the price
+        in force at each point in time, not the current one). - `on_market` (default): a
+        listing counts in a month if it was live at any point that month (first seen
+        before the month ended, and still active or last seen on or after the month
+        started), at the price it had at the end of the month, or when last seen if it
+        went off the market earlier. - `new_listings`: a listing counts in the month
+        Darak first saw it, at its first recorded asking price. Listings are
+        deduplicated across sources and pass the same outlier filter as the current
+        market (fences are today's), but not the 30-day freshness window, which doesn't
+        apply to history
+        """
+        return self._c.request("GET", "/market/trends", params)
+
+
+class _Exports:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def create(self, *, idempotency_key: Optional[str] = None, **body: Any) -> JSON:
+        """
+        Create an export. Starts an export of a whole dataset as files, for loading into
+        a warehouse
+        """
+        return self._c.request("POST", "/exports", body=body, headers=_idempotency_headers(idempotency_key))
+
+    def get(self, export_id: Union[int, str]) -> JSON:
+        """
+        Get an export. An export's status and, once `completed`, a signed download link
+        for every file, valid for 60 minutes; call again for fresh links
+        """
+        return self._c.request("GET", f"/exports/{quote(str(export_id))}")
+
+    def list(self, **params: QueryValue) -> JSON:
+        """
+        List exports. Your organization's exports, newest first, without download links
+        (GET one export for those)
+        """
+        return self._c.request("GET", "/exports", params)
+
+
+class _Listings:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def batch(self, **params: QueryValue) -> JSON:
+        """Get listings by id. Up to 100 listings in one call, in the order requested"""
+        return self._c.request("GET", "/listings/batch", params)
+
+    def count(self, **params: QueryValue) -> JSON:
+        """Count listings. How many listings match the same filters as search."""
+        return self._c.request("GET", "/listings/count", params)
+
+    def get(self, id: Union[int, str]) -> JSON:
+        """Get a listing. One active listing"""
+        return self._c.request("GET", f"/listings/{quote(str(id))}")
+
+    def price_history(self, id: Union[int, str]) -> JSON:
+        """
+        Get a listing's price history. Every price change Darak recorded for an active
+        listing, oldest first
+        """
+        return self._c.request("GET", f"/listings/{quote(str(id))}/price-history")
+
+    def search(self, **params: QueryValue) -> JSON:
+        """
+        Search listings. Active, deduplicated listings in one city, quality-filtered
+        like darak.app
+        """
+        return self._c.request("GET", "/listings", params)
+
+
+class _Market:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def area_distribution(self, **params: QueryValue) -> JSON:
+        """
+        Area distribution. Histogram and percentiles of floor/plot area (m²) over
+        listings in the sample that state an area (`without_area_count` did not)
+        """
+        return self._c.request("GET", "/market/area-distribution", params)
+
+    def land_prices(self, **params: QueryValue) -> JSON:
+        """
+        Land prices per m². Median registered price per m² of land plots, per quarter,
+        for a city or for each of up to 20 neighborhoods, with quarter-on-quarter and
+        year-on-year change
+        """
+        return self._c.request("GET", "/market/land-prices", params)
+
+    def neighborhoods(self, **params: QueryValue) -> JSON:
+        """
+        Prices by neighborhood. Median and quartile price per neighborhood in a city,
+        most expensive first
+        """
+        return self._c.request("GET", "/market/neighborhoods", params)
+
+    def price_distribution(self, **params: QueryValue) -> JSON:
+        """Price distribution. Histogram and percentiles of price"""
+        return self._c.request("GET", "/market/price-distribution", params)
+
+    def summary(self, **params: QueryValue) -> JSON:
+        """
+        Market summary. Headline numbers for a city (or neighborhoods): listing count,
+        median and quartile price, median area and price per m², how recently listings
+        were updated, and breakdowns by property type, top neighborhoods by volume, and
+        source. Computed over the market sample: active, deduplicated listings updated
+        in the last 30 days (`updated_at`), after the same outlier filter darak.app uses
+        (per-tier price fences from the median and MAD of log price, bedroom and area
+        sanity checks, and a floor at 30% of the neighborhood median)
+        """
+        return self._c.request("GET", "/market/summary", params)
+
+    def supply(self, **params: QueryValue) -> JSON:
+        """
+        New supply. How many listings came onto the market recently: listings first seen
+        in the last 7 days vs the 7 days before, and the last 30 days vs the 30 days
+        before (rolling windows ending now)
+        """
+        return self._c.request("GET", "/market/supply", params)
+
+    def transactions(self, **params: QueryValue) -> JSON:
+        """
+        Registered deal statistics. Deal counts and median, 25th and 75th percentile
+        price per m² and total price, per quarter and land-use class, for a city, a set
+        of neighborhoods combined (`group_by=city` with `neighborhood_id`), or each
+        neighborhood (`group_by=neighborhood`)
+        """
+        return self._c.request("GET", "/market/transactions", params)
+
+    def vacancy(self, **params: QueryValue) -> JSON:
+        """
+        Vacancy indicator. How long listings in the sample have been on the market, as a
+        proxy for vacancy (actual occupancy isn't observed)
+        """
+        return self._c.request("GET", "/market/vacancy", params)
+
+
+class _Official:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def market_index(self, **params: QueryValue) -> JSON:
+        """
+        Darak Property Index. **Free on every plan (0 units).** Series built on Saudi
+        open data are served under the Saudi Open Data License v2.0 with attribution:
+        show `attribution.notice` wherever you display or pass on those figures
+        """
+        return self._c.request("GET", "/market/property-index", params)
+
+    def registered_rents(self, **params: QueryValue) -> JSON:
+        """
+        Registered rents (REGA). **Free on every plan (0 units).** This is Saudi open
+        data, served at no charge under the Saudi Open Data License v2.0 with
+        attribution: show `attribution.notice` wherever you display or pass on the
+        figures. Registered rents from REGA's quarterly rent index ("مؤشر الايجار",
+        published on open.data.gov.sa): for each neighborhood and property type, the
+        **mean** yearly rent of the residential leases registered on Ejar that quarter,
+        the mean yearly rent per m², and the number of contracts behind them. - **These
+        are means, not medians.** REGA publishes the mean; a few large leases pull it
+        up, so it usually sits above a median
+        """
+        return self._c.request("GET", "/market/registered-rents", params)
+
+
+class _OrganizationAuditEvents:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def list(self, **params: QueryValue) -> JSON:
+        """List audit events. Newest first, 50 per page"""
+        return self._c.request("GET", "/organization/audit-events", params)
+
+
+class _OrganizationKeys:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def create(self, *, idempotency_key: Optional[str] = None, **body: Any) -> JSON:
+        """Create a data key. Creates a `dk_live_…` key"""
+        return self._c.request("POST", "/organization/keys", body=body, headers=_idempotency_headers(idempotency_key))
+
+    def list(self) -> JSON:
+        """List data keys. Active data keys (`dk_live_…`)"""
+        return self._c.request("GET", "/organization/keys")
+
+    def revoke(self, key_id: Union[int, str], *, idempotency_key: Optional[str] = None) -> JSON:
+        """Revoke a key. Requests with the key are rejected right away"""
+        return self._c.request("POST", f"/organization/keys/{quote(str(key_id))}/revoke", headers=_idempotency_headers(idempotency_key))
+
+
+class _OrganizationMembers:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def list(self) -> JSON:
+        """
+        List members and invitations. Everyone with access to this organization and
+        every invitation not yet accepted, with each person's role.
+        """
+        return self._c.request("GET", "/organization/members")
+
+
+class _OrganizationProjects:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def list(self) -> JSON:
+        """List projects. The projects this organization's keys belong to"""
+        return self._c.request("GET", "/organization/projects")
+
+
+class _OrganizationRequestLogs:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def list(self, **params: QueryValue) -> JSON:
+        """
+        List request logs. Calls this organization made, newest first, within its
+        retention window (7, 30 or 90 days, set on the Settings page)
+        """
+        return self._c.request("GET", "/organization/request-logs", params)
+
+
+class _OrganizationWebhooks:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def create(self, *, idempotency_key: Optional[str] = None, **body: Any) -> JSON:
+        """Create a webhook endpoint. Subscribes an HTTPS URL to listing events"""
+        return self._c.request("POST", "/organization/webhooks", body=body, headers=_idempotency_headers(idempotency_key))
+
+    def delete(self, webhook_id: Union[int, str], *, idempotency_key: Optional[str] = None) -> JSON:
+        """
+        Delete a webhook endpoint. Stops delivery and removes the endpoint and its
+        delivery history.
+        """
+        return self._c.request("POST", f"/organization/webhooks/{quote(str(webhook_id))}/delete", headers=_idempotency_headers(idempotency_key))
+
+    def deliveries(self, webhook_id: Union[int, str], **params: QueryValue) -> JSON:
+        """
+        List deliveries. What was sent to this endpoint, newest first, with what it
+        answered
+        """
+        return self._c.request("GET", f"/organization/webhooks/{quote(str(webhook_id))}/deliveries", params)
+
+    def list(self) -> JSON:
+        """List webhook endpoints. Every endpoint this organization has subscribed"""
+        return self._c.request("GET", "/organization/webhooks")
+
+    def replay(self, webhook_id: Union[int, str], delivery_id: Union[int, str], *, idempotency_key: Optional[str] = None) -> JSON:
+        """
+        Replay a delivery. Queues the same payload again, with its original `event_id`
+        so a receiver that already handled it can recognise the repeat
+        """
+        return self._c.request("POST", f"/organization/webhooks/{quote(str(webhook_id))}/deliveries/{quote(str(delivery_id))}/replay", headers=_idempotency_headers(idempotency_key))
+
+
+class _Organization:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+        self.audit_events = _OrganizationAuditEvents(client)
+        self.keys = _OrganizationKeys(client)
+        self.members = _OrganizationMembers(client)
+        self.projects = _OrganizationProjects(client)
+        self.request_logs = _OrganizationRequestLogs(client)
+        self.webhooks = _OrganizationWebhooks(client)
+
+    def get(self) -> JSON:
+        """Get your organization. Name, plan and limits, and this month's usage."""
+        return self._c.request("GET", "/organization")
+
+    def usage(self, **params: QueryValue) -> JSON:
+        """
+        Daily usage. Requests and units per UTC day, key, endpoint and result class, for
+        the last 7, 30 or 90 days.
+        """
+        return self._c.request("GET", "/organization/usage", params)
+
+
+class _Projects:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def developers(self, **params: QueryValue) -> JSON:
+        """List developers. Developers with active projects on Darak, most projects first"""
+        return self._c.request("GET", "/developers", params)
+
+    def get(self, id: Union[int, str]) -> JSON:
+        """
+        Get a project. One project with its description, boundary, amenities, financing
+        banks and a summary of the units listed on Darak
+        """
+        return self._c.request("GET", f"/projects/{quote(str(id))}")
+
+    def search(self, **params: QueryValue) -> JSON:
+        """
+        Search projects. Off-plan and newly built residential and commercial projects
+        from Saudi developers and portals, one entry per project (copies from several
+        sources are merged)
+        """
+        return self._c.request("GET", "/projects", params)
+
+    def units(self, id: Union[int, str], **params: QueryValue) -> JSON:
+        """
+        List a project's units. Active listings on Darak linked to one project: units
+        for sale (total price) and, for some projects, rentals (yearly rent)
+        """
+        return self._c.request("GET", f"/projects/{quote(str(id))}/units", params)
+
+    def units_search(self, **params: QueryValue) -> JSON:
+        """
+        Search project units. Units across all projects: active listings linked to a
+        project, filtered by the unit (bedrooms, price, area) and by its project (city,
+        developer, status)
+        """
+        return self._c.request("GET", "/project-units", params)
+
+
+class _Reference:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def cities(self) -> JSON:
+        """List cities. Cities Darak covers"""
+        return self._c.request("GET", "/cities")
+
+    def directions(self, city: Union[int, str]) -> JSON:
+        """
+        List city directions. Groupings of neighborhoods by part of the city (north,
+        east, …)
+        """
+        return self._c.request("GET", f"/cities/{quote(str(city))}/directions")
+
+    def enums(self) -> JSON:
+        """List enumerated values. Allowed values for enumerated fields and filters"""
+        return self._c.request("GET", "/enums")
+
+    def limits(self) -> JSON:
+        """
+        Get this key's limits. The plan, rate limit, monthly quota, page size and paging
+        depth that apply to the key making the request, and the APIs it can reach
+        """
+        return self._c.request("GET", "/limits")
+
+    def neighborhoods(self, city: Union[int, str]) -> JSON:
+        """List neighborhoods. Active neighborhoods in a city"""
+        return self._c.request("GET", f"/cities/{quote(str(city))}/neighborhoods")
+
+
+class _Transactions:
+    def __init__(self, client: Any) -> None:
+        self._c = client
+
+    def search(self, **params: QueryValue) -> JSON:
+        """
+        Search registered deals. Individual sale deals registered with the Ministry of
+        Justice, from its quarterly open data, in one city: month, neighborhood, land-
+        use class, area, price and price per m²
+        """
+        return self._c.request("GET", "/transactions", params)
+
+
+def attach(client: Any) -> None:
+    """Attaches every namespace in the spec to the client."""
+    client.analytics = _Analytics(client)
+    client.exports = _Exports(client)
+    client.listings = _Listings(client)
+    client.market = _Market(client)
+    client.official = _Official(client)
+    client.organization = _Organization(client)
+    client.projects = _Projects(client)
+    client.reference = _Reference(client)
+    client.transactions = _Transactions(client)

kite_sa/client.py

@@ -0,0 +1,250 @@
+"""The Kite 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
+import uuid
+from ._generated import attach as _attach_endpoints, _Listings as _ListingsGenerated, _Reference
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Sequence, Union
+
+__all__ = ["Kite", "KiteError"]
+
+JSON = Dict[str, Any]
+QueryValue = Union[str, int, float, bool, Sequence[Union[str, int]], None]
+
+DEFAULT_BASE_URL = "https://api.kite.sa/v1"
+
+
+def _user_agent() -> str:
+    """Read from the package rather than hardcoded, which drifted once already."""
+    from . import __version__
+
+    return f"kite-sa-python/{__version__}"
+# Longest Retry-After worth sleeping through; longer (a monthly quota) raises.
+MAX_RETRY_WAIT_S = 60
+
+
+class KiteError(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"KiteError(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 Kite:
+    """Client for the Kite API.
+
+    Args:
+        api_key: Defaults to the ``KITE_API_KEY`` environment variable.
+        base_url: Defaults to https://api.kite.sa/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("KITE_API_KEY")
+        if not key:
+            raise ValueError("Pass api_key or set KITE_API_KEY. Get a key at https://platform.kite.sa.")
+        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
+        # Every endpoint in the spec, generated. A new one appears here as
+        # soon as it appears in the spec — the hand-written surface silently
+        # covered nine of thirty-four and nothing failed to say so.
+        _attach_endpoints(self)
+        # `listings` gains search_all on top of the generated methods, and the
+        # names the 0.1.0 client used keep working.
+        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,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> JSON:
+        """Calls any endpoint; prefer the typed helpers.
+
+        A POST without an ``Idempotency-Key`` header gets a fresh one, made once
+        here and sent again on every retry, so a lost response can't run the
+        write twice (a second API key whose secret the caller never saw).
+        """
+        url = f"{self.base_url}{path}{encode_query(query or {})}"
+        data = json.dumps(body).encode() if body is not None else None
+        merged: Dict[str, str] = dict(headers or {})
+        # Ours win over the caller's, so optional headers can't replace the key.
+        merged.update(
+            {
+                "Authorization": f"Bearer {self._api_key}",
+                "Accept": "application/json",
+                "User-Agent": _user_agent(),
+            }
+        )
+        headers = merged
+        if method.upper() == "POST" and not any(k.lower() == "idempotency-key" for k in headers):
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        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")
+
+
+
+class _Listings(_ListingsGenerated):
+    """The generated listing methods, plus paging that follows the cursor."""
+
+    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
+
+
+class _Cities(_Reference):
+    """Kept from 0.1.0. The generated names live on `client.reference`."""
+
+    def list(self) -> JSON:
+        return self.cities()
+
+    def neighborhoods(self, city: str) -> JSON:  # type: ignore[override]
+        return _Reference.neighborhoods(self, city)
+
+    def directions(self, city: str) -> JSON:  # type: ignore[override]
+        return _Reference.directions(self, city)
+
+
+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) -> KiteError:
+    try:
+        parsed = json.loads(res.body or b"{}")
+    except ValueError:
+        parsed = None
+    # Valid JSON that isn't an object (null, [], "x") has no error to read.
+    payload = parsed.get("error") if isinstance(parsed, dict) else None
+    if not isinstance(payload, dict):
+        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 KiteError(
+        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,
+    )

kite_sa-0.3.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: kite-sa
+Version: 0.3.0
+Summary: Official Python client for the Kite API: Saudi real-estate listings and market data.
+Project-URL: Documentation, https://platform.kite.sa/docs
+Project-URL: Source, https://github.com/basseko/kite/tree/main/packages/sdk-python
+Project-URL: Issues, https://github.com/basseko/kite/issues
+Project-URL: Changelog, https://platform.kite.sa/changelog
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,kite,listings,real-estate,saudi-arabia
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# kite-sa
+
+The official Python client for the [Kite API](https://platform.kite.sa/docs): every live rental and sale listing in Saudi Arabia, deduplicated across 20+ sources. Standard library only, Python 3.9+.
+
+```bash
+pip install kite-sa
+```
+
+```python
+from kite_sa import Kite, KiteError
+
+kite = Kite()  # reads KITE_API_KEY
+
+page = kite.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 kite.listings.search_all(city="jeddah", listing_type="sale"):
+    print(listing["id"], listing["location"]["neighborhood_name_en"])
+
+try:
+    kite.listings.get(1)
+except KiteError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+Get a key at [platform.kite.sa](https://platform.kite.sa).
+
+- 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.
+- Namespaces, generated from the API's OpenAPI spec so they track it exactly:
+  `listings`, `market`, `analytics`, `projects`, `reference`, and
+  `organization` (admin keys). `listings.search_all(...)` pages for you by
+  following the cursor, and `request(method, path, query, body)` reaches
+  anything not yet wrapped.
+- `cities.list / neighborhoods / directions` still work; they are the 0.1.0
+  names for what is now `reference`.
+
+Tests: `python3 -m unittest discover -s tests`.

kite_sa-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+kite_sa/__init__.py,sha256=galZDBOtPCMAfxcSEcaIZrb9MekV_nQAhWfxgSL2re0,385
+kite_sa/_generated.py,sha256=jF-woUzfVyAShvfdHZEp05DyebsvDYPIfhAmscdk4Dc,19880
+kite_sa/client.py,sha256=42Lg-ezE24MMmMyQo1rzKiFZBmA0a29HeVATDX_yjKE,9262
+kite_sa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kite_sa-0.3.0.dist-info/METADATA,sha256=b6R00YwETIChr8flSV9jEatpEveRy-AcjzwzkYITIbc,2170
+kite_sa-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+kite_sa-0.3.0.dist-info/licenses/LICENSE,sha256=3DxRir0wp0CBd3x-qCDYqaDFJx4x_GpEWV__8ZiZL3Y,1075
+kite_sa-0.3.0.dist-info/RECORD,,

kite_sa-0.3.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

kite_sa-0.3.0.dist-info/licenses/LICENSE

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