kite-sa 0.3.0__tar.gz

kite_sa-0.3.0/.gitignore

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

kite_sa-0.3.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# kite-sa
+
+Formerly `darak` on PyPI, which is deprecated. Versions before 0.3.0 were published under that name.
+
+## 0.3.0 (unreleased)
+
+- **Renamed** from `darak` to `kite-sa` for the move to Kite: `pip install kite-sa`,
+  `from kite_sa import Kite, KiteError` (was `from darak import Darak, DarakError`),
+  and the key is read from `KITE_API_KEY` (was `DARAK_API_KEY`). The default base URL
+  is `https://api.kite.sa/v1`; `https://api.darak.app/v1` keeps working. Webhook
+  headers (`Darak-*`) and the `darak.read` scope are part of the API and unchanged.
+
+## 0.2.2
+
+- Writes are safe to retry. A POST now carries an `Idempotency-Key`, made once
+  per call and reused on every retry, so a lost response can no longer create a
+  second API key whose secret you never saw. Pass your own with the
+  keyword-only `idempotency_key=` on the generated POST methods
+  (`organization.keys.create(name=..., idempotency_key="...")`), or
+  `headers=` on `request()`.
+- A non-2xx response whose body is valid JSON but not an object (`null`, `[]`,
+  `{"error": "text"}`) raised `AttributeError`; it is now a `DarakError`, and
+  retried when the status is 429 or 5xx.
+
+## 0.2.1
+
+- The `User-Agent` is derived from the package version instead of a hardcoded
+  string, which had already drifted once.
+- Ships a LICENSE, and links its repository and issue tracker from PyPI.
+
+## 0.2.0
+
+- Every endpoint in the API is now reachable. The client's namespaces are
+  generated from the OpenAPI spec, so `market`, `analytics`, `projects`,
+  `reference` and `organization` are all present — the hand-written surface
+  covered 9 of 34, and `market.summary` raised `AttributeError`.
+- `cities.*` keep working; they are the 0.1.0 names for what is now `reference`.
+- Removed `broker_listings()`: `POST /broker-listings` was removed from the API.
+
+## 0.1.0
+
+- Initial release.

kite_sa-0.3.0/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.

kite_sa-0.3.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,39 @@
+# 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/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-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-0.3.0/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/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kite-sa"
+version = "0.3.0"
+description = "Official Python client for the Kite API: Saudi real-estate listings and market data."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["kite", "real-estate", "saudi-arabia", "api", "listings"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://platform.kite.sa/docs"
+Source = "https://github.com/basseko/kite/tree/main/packages/sdk-python"
+Issues = "https://github.com/basseko/kite/issues"
+Changelog = "https://platform.kite.sa/changelog"
+
+[tool.hatch.build.targets.wheel]
+packages = ["kite_sa"]

kite_sa-0.3.0/scripts/generate.py

@@ -0,0 +1,193 @@
+"""Regenerates kite_sa/_generated.py from the API's committed OpenAPI spec.
+
+The hand-written client covered nine endpoints and silently stayed that way as
+the API grew to thirty-four: a Python caller reaching for `market.summary` got
+an AttributeError, and nothing failed to say so. Generating the surface means
+a new endpoint appears here the moment it appears in the spec, and
+tests/test_generated.py fails until it does.
+
+Stdlib only, like the package itself. Run:
+
+    python packages/sdk-python/scripts/generate.py
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import pathlib
+import textwrap
+from typing import Any, Dict, List, Tuple
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+SPEC = ROOT / "src" / "lib" / "api-v1" / "openapi.v1.json"
+OUT = pathlib.Path(__file__).resolve().parents[1] / "kite_sa" / "_generated.py"
+
+METHODS = ("get", "post", "put", "patch", "delete")
+
+
+def spec_hash(raw: str) -> str:
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def wrap(text: str, indent: str) -> List[str]:
+    """A docstring the way a person would write it, not one long line."""
+    clean = " ".join((text or "").split())
+    if not clean:
+        return []
+    lines = textwrap.wrap(clean, width=88 - len(indent))
+    return [f"{indent}{line}" for line in lines]
+
+
+def py_name(part: str) -> str:
+    return part.replace("-", "_")
+
+
+def collect() -> Tuple[Dict[str, Any], str]:
+    raw = SPEC.read_text()
+    spec = json.loads(raw)
+    # operationId is `namespace.method` or `namespace.group.method`; the spec
+    # already names things the way a client should, so nothing is invented here.
+    tree: Dict[str, Any] = {}
+    for path, item in spec["paths"].items():
+        for method, op in item.items():
+            if method not in METHODS:
+                continue
+            op_id = op.get("operationId")
+            if not op_id:
+                raise SystemExit(f"{method.upper()} {path} has no operationId")
+            parts = [py_name(p) for p in op_id.split(".")]
+            if len(parts) < 2:
+                raise SystemExit(f"operationId {op_id!r} is not namespace.method")
+            node = tree
+            for part in parts[:-1]:
+                node = node.setdefault(part, {})
+            node[parts[-1]] = {
+                "path": path,
+                "method": method,
+                "summary": op.get("summary") or "",
+                "description": op.get("description") or "",
+                "path_params": [
+                    q["name"] for q in op.get("parameters", []) if q.get("in") == "path"
+                ],
+                "has_query": any(
+                    q.get("in") == "query" for q in op.get("parameters", [])
+                ),
+                "has_body": bool(op.get("requestBody")),
+                "idempotent": any(
+                    q.get("in") == "header" and q.get("name") == "Idempotency-Key"
+                    for q in op.get("parameters", [])
+                ),
+            }
+    return tree, spec_hash(raw)
+
+
+def render_method(name: str, op: Dict[str, Any]) -> List[str]:
+    args = ["self"]
+    for p in op["path_params"]:
+        args.append(f"{py_name(p)}: Union[int, str]")
+    # Keyword-only, like the JS SDK's idempotencyKey. Left out, request() makes
+    # one per call and reuses it across retries.
+    if op["idempotent"]:
+        args.extend(["*", "idempotency_key: Optional[str] = None"])
+    if op["has_query"]:
+        args.append("**params: QueryValue")
+    elif op["has_body"]:
+        args.append("**body: Any")
+
+    out = [f"    def {name}({', '.join(args)}) -> JSON:"]
+
+    doc = op["summary"]
+    # The first sentence of the description adds what the summary leaves out.
+    extra = op["description"].split(". ")[0] if op["description"] else ""
+    if extra and extra.lower() not in doc.lower():
+        doc = f"{doc}. {extra}" if doc else extra
+    body_doc = wrap(doc, "        ")
+    if body_doc:
+        if len(body_doc) == 1:
+            out.append(f'        """{body_doc[0].strip()}"""')
+        else:
+            out.append('        """')
+            out.extend(body_doc)
+            out.append('        """')
+
+    # Path parameters are interpolated and escaped; everything else is a query.
+    if op["path_params"]:
+        expr = op["path"]
+        for p in op["path_params"]:
+            expr = expr.replace("{" + p + "}", f"{{quote(str({py_name(p)}))}}")
+        target = f'f"{expr}"'
+    else:
+        target = f'"{op["path"]}"'
+
+    verb = op["method"].upper()
+    extra_args = ", headers=_idempotency_headers(idempotency_key)" if op["idempotent"] else ""
+    if op["has_query"]:
+        out.append(f'        return self._c.request("{verb}", {target}, params{extra_args})')
+    elif op["has_body"]:
+        out.append(f'        return self._c.request("{verb}", {target}, body=body{extra_args})')
+    else:
+        out.append(f'        return self._c.request("{verb}", {target}{extra_args})')
+    return out
+
+
+def render_namespace(name: str, node: Dict[str, Any]) -> Tuple[List[str], List[str]]:
+    """Returns (class source, nested class sources rendered first)."""
+    nested: List[str] = []
+    lines = [f"class _{name.title().replace('_', '')}:", "    def __init__(self, client: Any) -> None:", "        self._c = client"]
+    for key, value in sorted(node.items()):
+        if "path" in value:
+            continue
+        child_cls = f"_{(name + '_' + key).title().replace('_', '')}"
+        sub_lines, sub_nested = render_namespace(f"{name}_{key}", value)
+        nested.extend(sub_nested)
+        nested.append("\n".join(sub_lines))
+        lines.append(f"        self.{key} = {child_cls}(client)")
+    lines.append("")
+    ops = {k: v for k, v in node.items() if "path" in v}
+    for key in sorted(ops):
+        lines.extend(render_method(key, ops[key]))
+        lines.append("")
+    return lines, nested
+
+
+def main() -> None:
+    tree, digest = collect()
+    chunks: List[str] = []
+    attach: List[str] = []
+    for name in sorted(tree):
+        lines, nested = render_namespace(name, tree[name])
+        chunks.extend(nested)
+        chunks.append("\n".join(lines))
+        cls = f"_{name.title().replace('_', '')}"
+        attach.append(f"    client.{name} = {cls}(client)")
+
+    header = (
+        f"# Generated from src/lib/api-v1/openapi.v1.json (spec {digest}).\n"
+        "# Do not edit: run `python packages/sdk-python/scripts/generate.py`.\n"
+    )
+    preamble = (
+        "from __future__ import annotations\n\n"
+        "from typing import Any, Dict, Optional, Union\n"
+        "from urllib.parse import quote\n\n"
+        "JSON = Any\n"
+        "QueryValue = Any\n\n\n"
+        "def _idempotency_headers(key: Optional[str]) -> Optional[Dict[str, str]]:\n"
+        "    return {\"Idempotency-Key\": key} if key else None\n\n\n"
+    )
+    # A function, not a class: it attaches the namespaces to the client
+    # itself. Setting them on a throwaway object would look right and do
+    # nothing, which is the failure this whole file exists to prevent.
+    footer = (
+        "def attach(client: Any) -> None:\n"
+        '    """Attaches every namespace in the spec to the client."""\n'
+        + "\n".join(attach)
+        + "\n"
+    )
+    OUT.write_text(header + preamble + "\n\n".join(chunks) + "\n\n" + footer)
+    count = sum(1 for _ in json.loads(SPEC.read_text())["paths"])
+    print(f"kite_sa/_generated.py written ({count} paths, spec {digest})")
+
+
+if __name__ == "__main__":
+    main()

kite_sa-0.3.0/tests/test_client.py

@@ -0,0 +1,170 @@
+import json
+import os
+import pathlib
+import unittest
+import urllib.error
+
+import kite_sa
+from kite_sa import Kite, KiteError
+from kite_sa import client as client_module
+from kite_sa.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 = Kite("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("KITE_API_KEY", None)
+        try:
+            with self.assertRaises(ValueError):
+                Kite()
+        finally:
+            if saved is not None:
+                os.environ["KITE_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(KiteError) 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(KiteError) 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_post_reuses_one_generated_idempotency_key_across_retries(self):
+        t = FakeTransport(urllib.error.URLError("lost"), (503, {}, {}), (200, {}, {"data": {}}))
+        client(t).organization.keys.create(name="ci")
+        keys = [r.get_header("Idempotency-key") for r in t.requests]
+        self.assertEqual(len(keys), 3)
+        self.assertTrue(keys[0])
+        self.assertEqual(len(set(keys)), 1)
+        # A separate call is a separate write: it gets its own key.
+        t2 = FakeTransport()
+        c = client(t2)
+        c.organization.keys.create(name="a")
+        c.organization.keys.create(name="b")
+        self.assertNotEqual(t2.requests[0].get_header("Idempotency-key"), t2.requests[1].get_header("Idempotency-key"))
+
+    def test_caller_idempotency_key_is_sent_on_every_attempt(self):
+        t = FakeTransport((502, {}, {}), (200, {}, {}))
+        client(t).organization.keys.create(name="ci", idempotency_key="mine-1")
+        self.assertEqual([r.get_header("Idempotency-key") for r in t.requests], ["mine-1", "mine-1"])
+        t = FakeTransport()
+        client(t).organization.keys.revoke("key_1", idempotency_key="mine-2")
+        self.assertEqual(t.requests[0].get_header("Idempotency-key"), "mine-2")
+
+    def test_get_sends_no_idempotency_key_and_headers_cannot_replace_auth(self):
+        t = FakeTransport()
+        client(t).request("GET", "/enums", headers={"Authorization": "Bearer other", "X-Extra": "1"})
+        r = t.requests[0]
+        self.assertIsNone(r.get_header("Idempotency-key"))
+        self.assertEqual(r.get_header("Authorization"), "Bearer dk_live_test")
+        self.assertEqual(r.get_header("X-extra"), "1")
+
+    def test_non_object_error_bodies_become_retryable_kite_errors(self):
+        for body in (b"null", b"[]", b'{"error":"str"}', b'"x"', b"not json"):
+            with self.subTest(body=body):
+                raw = lambda request, timeout, body=body: _Response(503, {}, body)
+                with self.assertRaises(KiteError) as ctx:
+                    client(raw, max_retries=0).enums()
+                self.assertEqual((ctx.exception.status, ctx.exception.code), (503, "http_503"))
+                calls = []
+
+                def flaky(request, timeout, body=body, calls=calls):
+                    calls.append(1)
+                    return _Response(503, {}, body) if len(calls) == 1 else _Response(200, {}, b"{}")
+
+                self.assertEqual(client(flaky).enums(), {})
+                self.assertEqual(len(calls), 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()
+
+
+class TestUserAgent(unittest.TestCase):
+    """The hardcoded string drifted from __version__ once; keep them together."""
+
+    def test_matches_the_package_version(self) -> None:
+        import tomllib
+
+        root = pathlib.Path(__file__).resolve().parents[1]
+        with open(root / "pyproject.toml", "rb") as fh:
+            version = tomllib.load(fh)["project"]["version"]
+        self.assertEqual(kite_sa.__version__, version)
+        self.assertEqual(client_module._user_agent(), f"kite-sa-python/{version}")

kite_sa-0.3.0/tests/test_generated.py

@@ -0,0 +1,61 @@
+"""The generated surface has to match the API's committed spec.
+
+The hand-written client covered nine of thirty-four endpoints and nothing
+failed to say so: `market.summary` raised AttributeError and the tests stayed
+green, because they only tested what the client implemented. These two tests
+are the ones that would have caught it.
+"""
+
+import hashlib
+import json
+import pathlib
+import unittest
+
+from kite_sa import Kite
+from kite_sa import _generated
+
+ROOT = pathlib.Path(__file__).resolve().parents[3]
+SPEC = ROOT / "src" / "lib" / "api-v1" / "openapi.v1.json"
+GENERATED = pathlib.Path(_generated.__file__)
+
+METHODS = ("get", "post", "put", "patch", "delete")
+
+
+class TestGenerated(unittest.TestCase):
+    def test_matches_the_committed_spec(self) -> None:
+        raw = SPEC.read_text()
+        digest = hashlib.sha256(raw.encode()).hexdigest()[:16]
+        header = GENERATED.read_text().split("\n")[0]
+        self.assertIn(
+            f"(spec {digest})",
+            header,
+            "Out of date: run python packages/sdk-python/scripts/generate.py "
+            "and commit kite_sa/_generated.py.",
+        )
+
+    def test_every_endpoint_is_reachable(self) -> None:
+        """Walks the spec and resolves each operationId on a real client.
+
+        A path the client cannot reach is the bug this package shipped with,
+        so it is asserted directly rather than inferred from the file's hash.
+        """
+        client = Kite(api_key="test-key")
+        spec = json.loads(SPEC.read_text())
+        missing = []
+        for path, item in spec["paths"].items():
+            for method, op in item.items():
+                if method not in METHODS:
+                    continue
+                target = client
+                for part in op["operationId"].replace("-", "_").split("."):
+                    target = getattr(target, part, None)
+                    if target is None:
+                        missing.append(f"{op['operationId']} ({method.upper()} {path})")
+                        break
+                else:
+                    self.assertTrue(callable(target), f"{op['operationId']} is not callable")
+        self.assertEqual(missing, [], f"unreachable from the client: {missing}")
+
+
+if __name__ == "__main__":
+    unittest.main()