aesops 0.1.0__py3-none-any.whl

aesops/__init__.py

@@ -0,0 +1,25 @@
+"""Aesops Python SDK — browse the catalog and load datasets into pandas, polars, or DuckDB."""
+
+from . import colors
+from .client import Client
+from .dataset import Dataset, DescribeTable, Summary
+from .errors import AesopsError, ApiError, AuthError, NotFoundError
+from .models import Column, DatasetDetail, DatasetSummary, Discussion
+
+__all__ = [
+    "Client",
+    "Dataset",
+    "DescribeTable",
+    "Summary",
+    "colors",
+    # models
+    "Column",
+    "DatasetDetail",
+    "DatasetSummary",
+    "Discussion",
+    # errors
+    "AesopsError",
+    "ApiError",
+    "AuthError",
+    "NotFoundError",
+]

aesops/client.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .dataset import Dataset
+from .errors import ApiError, AuthError, NotFoundError
+from .models import DatasetDetail, DatasetSummary, _from_json
+
+DEFAULT_BASE_URL = "https://aesops.co.ke"
+
+
+def _error_message(resp: httpx.Response) -> str:
+    try:
+        return resp.json().get("error", resp.text)
+    except ValueError:
+        return resp.text
+
+
+class Client:
+    """Client for the Aesops dataset API.
+
+    `list()` and `load_dataset()` work without an `api_key` and always show
+    the full catalog. Loading actual data (`Dataset.to_pandas()` etc.) only
+    requires a read-scoped key for datasets that aren't currently keyless —
+    create one at https://aesops.co.ke/profile/api-keys.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(base_url=self.base_url, timeout=timeout)
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, *, auth: bool = True, **kwargs: Any) -> dict[str, Any]:
+        headers = kwargs.pop("headers", {})
+        if auth and self.api_key:
+            headers.setdefault("Authorization", f"Bearer {self.api_key}")
+        resp = self._http.request(method, path, headers=headers, **kwargs)
+        if resp.status_code == 401:
+            raise AuthError(_error_message(resp))
+        if resp.status_code == 404:
+            raise NotFoundError(_error_message(resp))
+        if resp.status_code >= 400:
+            raise ApiError(resp.status_code, _error_message(resp))
+        return resp.json()
+
+    @staticmethod
+    def _csv(v: str | list[str] | None) -> str | None:
+        if v is None:
+            return None
+        return v if isinstance(v, str) else ",".join(v)
+
+    def _list_params(
+        self,
+        query: str | None,
+        license: str | list[str] | None,
+        category: str | list[str] | None,
+        tags: str | list[str] | None,
+        min_size: int | None,
+        max_size: int | None,
+        min_rows: int | None,
+        max_rows: int | None,
+        page: int,
+        page_size: int,
+    ) -> dict[str, Any]:
+        params = {
+            "query": query,
+            "license": self._csv(license),
+            "category": self._csv(category),
+            "tags": self._csv(tags),
+            "min_size": min_size,
+            "max_size": max_size,
+            "min_rows": min_rows,
+            "max_rows": max_rows,
+            "page": page,
+            "page_size": page_size,
+        }
+        return {k: v for k, v in params.items() if v is not None}
+
+    def list(
+        self,
+        query: str | None = None,
+        license: str | list[str] | None = None,
+        category: str | list[str] | None = None,
+        tags: str | list[str] | None = None,
+        min_size: int | None = None,
+        max_size: int | None = None,
+        min_rows: int | None = None,
+        max_rows: int | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> list[DatasetSummary]:
+        """List the full dataset catalog. No API key required or sent; every
+        dataset's metadata is public. Check `.keyless` on each result, or see
+        `load_dataset()`, to know which need a key to load actual data."""
+        params = self._list_params(
+            query, license, category, tags, min_size, max_size, min_rows, max_rows, page, page_size
+        )
+        data = self._request("GET", "/api/v1/datasets", params=params, auth=False)
+        return [_from_json(DatasetSummary, item) for item in data["items"]]
+
+    def load_dataset(self, slug: str) -> Dataset:
+        """Fetch a dataset's metadata + schema (always the latest active
+        version). No API key required — a key is only needed once you call
+        `.to_pandas()` / `.to_polars()` / `.sql()`, and only if the dataset
+        isn't currently keyless."""
+        data = self._request("GET", f"/api/v1/datasets/{slug}")
+        return Dataset(self, slug=data["slug"], detail=_from_json(DatasetDetail, data))
+
+    def _fetch_data_url(self, slug: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/v1/datasets/{slug}/data")

aesops/colors.py

@@ -0,0 +1,142 @@
+"""Aesops brand color tokens, for building charts/dashboards that match the
+platform's own design system.
+
+Mirrors the CSS custom properties in packages/ui/src/styles/globals.css —
+keep both in sync if the brand palette changes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def _hex_to_rgb(hex_color: str) -> tuple[int, int, int]:
+    h = hex_color.lstrip("#")
+    return int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)
+
+
+def _ansi_swatch(hex_color: str) -> str:
+    r, g, b = _hex_to_rgb(hex_color)
+    return f"\x1b[48;2;{r};{g};{b}m  \x1b[0m"
+
+
+@dataclass(frozen=True)
+class Palette:
+    """A color palette matching one of Aesops' light/dark CSS themes.
+
+    Printing a palette (``print(colors.light)``, ``print(colors.dark)``) or
+    displaying it in a Jupyter/IPython notebook renders its 6 `aeschart`
+    chart-series swatches — the colors you'd actually plot with — as actual
+    color chips next to their name and hex value, rather than just hex text.
+    """
+
+    primary: str
+    primary_foreground: str
+    accent: str
+    accent_foreground: str
+    background: str
+    foreground: str
+    card: str
+    card_foreground: str
+    muted: str
+    muted_foreground: str
+    border: str
+    success: str
+    success_foreground: str
+    destructive: str
+    destructive_foreground: str
+    # 6-slot categorical series for charts, in fixed order: teal, peach, rust,
+    # sage, orange, brown. Slot 1 is always the brand primary teal. See
+    # DESIGN.md's chart palette section for how the other 5 slots were
+    # derived (packages/ui/src/components/logo.tsx's 9-stop gradient, nudged
+    # in OKLCH to clear categorical lightness/chroma checks).
+    aeschart: tuple[str, str, str, str, str, str]
+
+    def _swatches(self) -> list[tuple[str, str]]:
+        return [(f"aeschart[{i}]", hex_color) for i, hex_color in enumerate(self.aeschart)]
+
+    def __repr__(self) -> str:
+        name_w = max(len(name) for name, _ in self._swatches())
+        lines = [
+            f"{_ansi_swatch(hex_color)} {name.ljust(name_w)}  {hex_color}"
+            for name, hex_color in self._swatches()
+        ]
+        return "\n".join(lines)
+
+    __str__ = __repr__
+
+    def _repr_html_(self) -> str:
+        """Rich display hook Jupyter/IPython (incl. Zed's REPL) call
+        automatically for the last expression in a cell."""
+        cell = (
+            "display:flex;align-items:center;gap:8px;"
+            "font-family:monospace;padding:2px 0"
+        )
+        swatch = "width:16px;height:16px;border-radius:3px;border:1px solid rgba(0,0,0,0.15)"
+        rows = "".join(
+            f"<div style='{cell}'>"
+            f"<span style='{swatch};background:{hex_color}'></span>"
+            f"<span>{name}</span><span style='color:#888'>{hex_color}</span>"
+            "</div>"
+            for name, hex_color in self._swatches()
+        )
+        return f"<div>{rows}</div>"
+
+
+light = Palette(
+    primary="#155f6b",
+    primary_foreground="#F8F3ED",
+    accent="#D4956A",
+    accent_foreground="#0A2533",
+    background="#F8F3ED",
+    foreground="#0A2533",
+    card="#FFFCF8",
+    card_foreground="#0A2533",
+    muted="#F0EBE4",
+    muted_foreground="#5C6B6E",
+    border="#E5DED4",
+    success="#5A8A7A",
+    success_foreground="#F8F3ED",
+    destructive="#A65D4A",
+    destructive_foreground="#F8F3ED",
+    aeschart=("#155f6b", "#e89f53", "#bc5308", "#4ab59e", "#ff7d00", "#86361d"),
+)
+
+dark = Palette(
+    primary="#D4956A",
+    primary_foreground="#0A2533",
+    accent="#E8C9A0",
+    accent_foreground="#0A2533",
+    background="#0A2533",
+    foreground="#F0EBE4",
+    card="#0F3040",
+    card_foreground="#F0EBE4",
+    muted="#153545",
+    muted_foreground="#9BB3AC",
+    border="#1A4050",
+    success="#6A9A8A",
+    success_foreground="#0A2533",
+    destructive="#A65D4A",
+    destructive_foreground="#F0EBE4",
+    aeschart=("#238595", "#c68031", "#bc5308", "#3ba892", "#e76700", "#934229"),
+)
+
+# Module-level attributes mirror `light` so `from aesops import colors;
+# colors.primary` works directly, without an extra `.light`. Use `colors.dark`
+# for the dark-theme palette.
+primary = light.primary
+primary_foreground = light.primary_foreground
+accent = light.accent
+accent_foreground = light.accent_foreground
+background = light.background
+foreground = light.foreground
+card = light.card
+card_foreground = light.card_foreground
+muted = light.muted
+muted_foreground = light.muted_foreground
+border = light.border
+success = light.success
+success_foreground = light.success_foreground
+destructive = light.destructive
+destructive_foreground = light.destructive_foreground
+aeschart = light.aeschart

aesops/dataset.py

@@ -0,0 +1,422 @@
+from __future__ import annotations
+
+import datetime
+import threading
+import time
+from typing import TYPE_CHECKING, Any
+
+import duckdb
+
+from .models import Discussion
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+_DESCRIBE_FIELDS = ["dtype", "count", "null_count", "null_%", "unique", "mean", "std", "min", "median", "max"]
+
+
+def _describe_fmt(v: Any) -> str:
+    if v is None:
+        return "NaN"
+    if isinstance(v, float):
+        return f"{v:.2f}"
+    return str(v)
+
+
+def _clip(value: Any, limit: int = 100) -> str:
+    if not value:
+        return "—"
+    text = " ".join(str(value).split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"
+
+
+class Summary:
+    """`Dataset.summary()`'s return value — a compact overview of a dataset's
+    identity, description, AI-generated insights, link back to its Aesops
+    page, and any linked community discussions. Built entirely from
+    metadata already fetched by `load_dataset()`, so this makes no network
+    call.
+
+    Renders with box-drawing borders when printed in a terminal, and as a
+    bordered HTML table when the last expression in a Jupyter/IPython
+    notebook cell (via `_repr_html_`).
+
+    A future addition will link to blog articles referencing the dataset,
+    once blog-to-dataset linking exists server-side (community discussions
+    already support an analogous `linked_blog_*` association on threads).
+    """
+
+    def __init__(self, dataset: "Dataset") -> None:
+        self._dataset = dataset
+
+    @property
+    def discussions(self) -> list[Discussion]:
+        return self._dataset.detail.discussion_links
+
+    def _rows(self) -> list[tuple[str, str]]:
+        d = self._dataset.detail
+        discussions = (
+            "; ".join(f"{disc.title} ({self._dataset.link(disc.path)})" for disc in self.discussions)
+            if self.discussions
+            else "—"
+        )
+        return [
+            ("name", d.name),
+            ("slug", d.slug),
+            ("description", _clip(d.description)),
+            ("insights", _clip(d.insights, limit=200)),
+            ("url", self._dataset.url),
+            ("discussions", discussions),
+        ]
+
+    def __repr__(self) -> str:
+        rows = self._rows()
+        label_w = max(len(r[0]) for r in rows)
+        value_w = max(len(r[1]) for r in rows)
+
+        def border(left: str, mid: str, right: str) -> str:
+            return left + mid.join("─" * (w + 2) for w in (label_w, value_w)) + right
+
+        def row_line(label: str, value: str) -> str:
+            return f"│ {label.ljust(label_w)} │ {value.ljust(value_w)} │"
+
+        lines = [
+            border("┌", "┬", "┐"),
+            *(row_line(*r) for r in rows),
+            border("└", "┴", "┘"),
+        ]
+        return "\n".join(lines)
+
+    __str__ = __repr__
+
+    def _repr_html_(self) -> str:
+        """Rich display hook Jupyter/IPython (incl. Zed's REPL) call
+        automatically for the last expression in a cell."""
+        rows = self._rows()
+        cell_style = "padding:4px 10px;border:1px solid var(--jp-border-color2,#ccc);text-align:left"
+        body = "".join(
+            f"<tr><td style='{cell_style};font-weight:600'>{label}</td>"
+            f"<td style='{cell_style}'>{value}</td></tr>"
+            for label, value in rows
+        )
+        return f"<table style='border-collapse:collapse'>{body}</table>"
+
+
+class DescribeTable:
+    """`Dataset.describe()`'s return value — a small, dependency-free table.
+
+    Renders with box-drawing borders when printed in a terminal, and as a
+    bordered HTML `<table>` when the last expression in a Jupyter/IPython
+    notebook cell (via `_repr_html_`), so it looks right either way without
+    requiring pandas. Call `.to_frame()` for a real `pandas.DataFrame` (e.g.
+    to `.loc[...]` or chain further) or `.to_dicts()` for plain rows.
+    """
+
+    def __init__(self, rows: list[dict[str, Any]]) -> None:
+        self._rows = rows
+
+    def to_dicts(self) -> list[dict[str, Any]]:
+        """The underlying rows, one dict per column."""
+        return self._rows
+
+    def to_frame(self):
+        """The same data as a `pandas.DataFrame`, indexed by column name.
+
+        Requires ``pandas`` (``pip install 'aesops[pandas]'``).
+        """
+        try:
+            import pandas as pd
+        except ImportError as exc:
+            raise ImportError(
+                "pandas is not installed. Install it with: pip install 'aesops[pandas]'"
+            ) from exc
+        return pd.DataFrame(self._rows).set_index("column")
+
+    def __len__(self) -> int:
+        return len(self._rows)
+
+    def _cells(self) -> tuple[list[str], list[list[str]]]:
+        headers = ["column", *_DESCRIBE_FIELDS]
+        rows = [
+            [str(row["column"]), *(_describe_fmt(row.get(f)) for f in _DESCRIBE_FIELDS)]
+            for row in self._rows
+        ]
+        return headers, rows
+
+    def __repr__(self) -> str:
+        if not self._rows:
+            return "<empty>"
+
+        headers, rows = self._cells()
+        widths = [max(len(headers[i]), *(len(r[i]) for r in rows)) for i in range(len(headers))]
+
+        def border(left: str, mid: str, right: str) -> str:
+            return left + mid.join("─" * (w + 2) for w in widths) + right
+
+        def row_line(cells: list[str]) -> str:
+            return "│ " + " │ ".join(c.rjust(w) for c, w in zip(cells, widths)) + " │"
+
+        lines = [
+            border("┌", "┬", "┐"),
+            row_line(headers),
+            border("├", "┼", "┤"),
+            *(row_line(r) for r in rows),
+            border("└", "┴", "┘"),
+        ]
+        return "\n".join(lines)
+
+    __str__ = __repr__
+
+    def _repr_html_(self) -> str:
+        """Rich display hook Jupyter/IPython (incl. Zed's REPL) call
+        automatically for the last expression in a cell."""
+        if not self._rows:
+            return "<em>empty</em>"
+
+        headers, rows = self._cells()
+        cell_style = "padding:4px 10px;border:1px solid var(--jp-border-color2,#ccc);text-align:right"
+        thead = "".join(f"<th style='{cell_style}'>{h}</th>" for h in headers)
+        tbody = "".join(
+            "<tr>" + "".join(f"<td style='{cell_style}'>{c}</td>" for c in r) + "</tr>" for r in rows
+        )
+        return f"<table style='border-collapse:collapse'><thead><tr>{thead}</tr></thead><tbody>{tbody}</tbody></table>"
+
+
+class Dataset:
+    """A handle to a single Aesops dataset — always the latest active version.
+
+    Metadata is available immediately (no network required after construction).
+    Data access (:meth:`to_pandas`, :meth:`to_polars`, :meth:`to_duckdb`,
+    :meth:`sql`) fetches a short-lived signed Parquet URL lazily on first use
+    and re-fetches automatically on expiry or 403, so long-running sessions
+    never stall waiting for a new URL.
+    """
+
+    def __init__(
+        self,
+        client: "Client",
+        slug: str,
+        detail: DatasetDetail,
+    ) -> None:
+        self._client = client
+        self.slug = slug
+        self.detail = detail
+        self._url: str | None = None
+        self._url_expires_at: float = 0.0  # unix timestamp
+        self._lock = threading.Lock()
+        self._conn: duckdb.DuckDBPyConnection | None = None
+
+    # ── metadata shortcuts ────────────────────────────────────────────────────
+
+    @property
+    def name(self) -> str:
+        return self.detail.name
+
+    @property
+    def row_count(self) -> int | None:
+        return self.detail.row_count
+
+    @property
+    def column_count(self) -> int | None:
+        return self.detail.column_count
+
+    @property
+    def schema(self) -> list[dict[str, Any]]:
+        return self.detail.schema
+
+    def link(self, path: str) -> str:
+        """Join a server-relative path (e.g. a `Discussion.path`) with this
+        dataset's client's own `base_url` — works against whatever host the
+        `Client` was configured for (production, preview, or local dev),
+        rather than hardcoding a domain."""
+        return f"{self._client.base_url}{path}"
+
+    @property
+    def url(self) -> str:
+        """Link to this dataset's page on the Aesops site, built from the
+        client's `base_url`."""
+        return self.link(f"/datasets/{self.slug}")
+
+    def describe(self) -> DescribeTable:
+        """Per-column summary statistics — count, nulls, unique values, and
+        (for numeric columns) mean/std/min/median/max — built entirely from
+        metadata already fetched by `load_dataset()`, so this makes no network
+        call and never requires pandas.
+
+        Returns a `DescribeTable`: prints with box-drawing borders, renders
+        as a bordered HTML table in a notebook, and has `.to_frame()` if you
+        want a real `pandas.DataFrame`::
+
+            print(ds.describe())
+            ds.describe().to_frame().loc["price"]
+        """
+        rows = []
+        for col in self.detail.columns:
+            count = None if self.row_count is None else self.row_count - col.null_count
+            rows.append(
+                {
+                    "column": col.name,
+                    "dtype": col.dtype,
+                    "count": count,
+                    "null_count": col.null_count,
+                    "null_%": col.null_percent,
+                    "unique": col.unique_count,
+                    "mean": col.mean,
+                    "std": col.std,
+                    "min": col.min,
+                    "median": col.median,
+                    "max": col.max,
+                }
+            )
+        return DescribeTable(rows)
+
+    def summary(self) -> Summary:
+        """A compact overview — name, slug, description, AI insights, a link
+        to the dataset's Aesops page, and any linked community discussions.
+        Built from metadata already fetched by `load_dataset()`, so this
+        makes no network call::
+
+            print(ds.summary())
+        """
+        return Summary(self)
+
+    # ── URL management ────────────────────────────────────────────────────────
+
+    def _get_url(self) -> str:
+        """Return a valid signed Parquet URL, refreshing proactively if it
+        expires within the next 60 seconds."""
+        with self._lock:
+            if self._url is None or time.time() > (self._url_expires_at - 60):
+                self._refresh_url()
+            return self._url  # type: ignore[return-value]
+
+    def _refresh_url(self) -> None:
+        resp = self._client._fetch_data_url(self.slug)
+        self._url = resp["url"]
+        expires_str: str = resp.get("expires_at", "")
+        try:
+            expires_str = expires_str.replace("Z", "+00:00")
+            dt = datetime.datetime.fromisoformat(expires_str)
+            self._url_expires_at = dt.timestamp()
+        except (ValueError, AttributeError):
+            # Fallback: assume the server's 1 h TTL
+            self._url_expires_at = time.time() + 3600
+
+    def _invalidate_url(self) -> None:
+        with self._lock:
+            self._url = None
+            self._url_expires_at = 0.0
+
+    # ── DuckDB helpers ────────────────────────────────────────────────────────
+
+    def _open_conn(self) -> duckdb.DuckDBPyConnection:
+        """Open an in-memory DuckDB connection with httpfs loaded and a ``data``
+        view pointing at the signed Parquet URL.
+
+        Stored on the instance (`self._conn`) rather than only returned —
+        whether a relation keeps its parent connection alive on its own is
+        duckdb-version-dependent, so without this a relation could be handed
+        a connection that's already been garbage-collected out from under it
+        by the time `.fetchall()`/`.df()`/`.pl()` actually runs.
+        """
+        url = self._get_url()
+        conn = duckdb.connect()
+        conn.execute("INSTALL httpfs; LOAD httpfs;")
+        conn.execute(f"CREATE VIEW data AS SELECT * FROM read_parquet('{url}')")
+        self._conn = conn
+        return conn
+
+    def _run(self, sql_str: str) -> duckdb.DuckDBPyRelation:
+        """Execute *sql_str*, retrying once with a fresh URL on an R2 403."""
+        try:
+            return self._open_conn().sql(sql_str)
+        except duckdb.IOException as exc:
+            msg = str(exc)
+            if "403" in msg or "Access Denied" in msg or "Forbidden" in msg:
+                self._invalidate_url()
+                return self._open_conn().sql(sql_str)
+            raise
+
+    # ── public data methods ───────────────────────────────────────────────────
+
+    def to_duckdb(self) -> duckdb.DuckDBPyConnection:
+        """Return an in-memory DuckDB connection with a ``data`` view bound to
+        the signed Parquet URL.
+
+        DuckDB's httpfs extension performs predicate- and projection-pushdown,
+        so only the row-groups your query touches are fetched from R2::
+
+            con = ds.to_duckdb()
+            con.sql("SELECT county, avg(price) FROM data GROUP BY county").df()
+        """
+        return self._open_conn()
+
+    def sql(self, query: str) -> duckdb.DuckDBPyRelation:
+        """Run a SQL query against this dataset. Reference the dataset as
+        ``data``::
+
+            ds.sql("SELECT county, avg(price) FROM data GROUP BY 1")
+
+        Returns a :class:`duckdb.DuckDBPyRelation`; call ``.df()`` for pandas
+        or ``.pl()`` for polars.
+        """
+        return self._run(query)
+
+    @staticmethod
+    def _select(limit: int | None) -> str:
+        if limit is None:
+            return "SELECT * FROM data"
+        if limit < 0:
+            raise ValueError("limit must be >= 0")
+        return f"SELECT * FROM data LIMIT {limit}"
+
+    def to_pandas(self, limit: int | None = None):
+        """Load the dataset into a :class:`pandas.DataFrame`.
+
+        Pass ``limit`` to fetch only the first N rows — DuckDB pushes the
+        LIMIT down through ``read_parquet``, so it also cuts how much of the
+        file crosses the network, not just what ends up in the DataFrame.
+
+        Requires ``pandas`` (``pip install 'aesops[pandas]'``).
+        """
+        try:
+            import pandas  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "pandas is not installed. "
+                "Install it with: pip install 'aesops[pandas]'"
+            ) from exc
+        return self._run(self._select(limit)).df()
+
+    def to_polars(self, limit: int | None = None):
+        """Load the dataset into a :class:`polars.DataFrame`.
+
+        Pass ``limit`` to fetch only the first N rows (see `to_pandas`).
+
+        Requires ``polars`` (``pip install 'aesops[polars]'``).
+        """
+        try:
+            import polars  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "polars is not installed. "
+                "Install it with: pip install 'aesops[polars]'"
+            ) from exc
+        return self._run(self._select(limit)).pl()
+
+    def to_csv(self, path: str, limit: int | None = None) -> None:
+        """Write the dataset to a CSV file (client-side conversion).
+
+        Pass ``limit`` to write only the first N rows (see `to_pandas`).
+
+        No extra server compute — DuckDB reads the Parquet directly and
+        writes the CSV locally.
+        """
+        self._run(f"COPY ({self._select(limit)}) TO '{path}' (FORMAT CSV, HEADER TRUE)")
+
+    def __repr__(self) -> str:
+        return (
+            f"<Dataset slug={self.slug!r} "
+            f"rows={self.detail.row_count} cols={self.detail.column_count}>"
+        )

aesops/errors.py

@@ -0,0 +1,22 @@
+class AesopsError(Exception):
+    """Base class for all aesops SDK errors."""
+
+
+class NotFoundError(AesopsError):
+    """Raised when a dataset or version doesn't exist."""
+
+
+class AuthError(AesopsError):
+    """Raised when an API key is missing, invalid, or lacks the required scope.
+
+    A read key is only required for `Client.download` / `Dataset.to_*` — listing
+    and metadata lookups work without one.
+    """
+
+
+class ApiError(AesopsError):
+    """Raised for any other non-2xx response from the API."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(f"[{status_code}] {message}")
+        self.status_code = status_code

aesops/models.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def _from_json(cls: type[T], data: dict[str, Any]) -> T:
+    """Build a dataclass from an API response, ignoring unknown fields so a new
+    field the server adds later doesn't break older SDK versions."""
+    known = {f.name for f in fields(cls)}
+    return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class Column:
+    name: str
+    dtype: str
+    null_count: int
+    null_percent: float
+    unique_count: int
+    mean: float | None = None
+    std: float | None = None
+    min: float | None = None
+    max: float | None = None
+    median: float | None = None
+    top_values: list[dict[str, Any]] | None = None
+    sample_values: list[Any] | None = None
+
+
+@dataclass
+class DatasetSummary:
+    slug: str
+    name: str
+    description: Any
+    license: str | None
+    category: str | None
+    tags: list[str]
+    size: int
+    row_count: int | None
+    column_count: int | None
+    keyless: bool
+    keyless_until: str | None
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class Discussion:
+    id: str
+    title: str
+    slug: str | None
+    # Relative to the API's host (e.g. "/community/discussions/<id>") — build
+    # a full link by joining with the Client's own `base_url`.
+    path: str
+
+
+@dataclass
+class DatasetDetail:
+    slug: str
+    name: str
+    description: Any
+    license: str | None
+    source: str | None
+    category: str | None
+    tags: list[str]
+    size: int
+    row_count: int | None
+    column_count: int | None
+    schema: list[dict[str, Any]]
+    keyless: bool
+    keyless_until: str | None
+    created_at: str
+    updated_at: str
+    insights: str | None = None
+    discussions: list[dict[str, Any]] = field(default_factory=list)
+
+    @property
+    def columns(self) -> list[Column]:
+        return [_from_json(Column, c) for c in self.schema]
+
+    @property
+    def discussion_links(self) -> list[Discussion]:
+        return [_from_json(Discussion, d) for d in self.discussions]

aesops-0.1.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: aesops
+Version: 0.1.0
+Summary: Python client for the Aesops dataset API — browse the catalog and load datasets into pandas, polars, or DuckDB.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: duckdb>=1.1
+Requires-Dist: httpx>=0.27
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Provides-Extra: polars
+Requires-Dist: polars>=1.0; extra == 'polars'
+Requires-Dist: pyarrow>=14; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# aesops
+
+Python client for the [Aesops](https://aesops.co.ke) dataset API.
+
+Browse the full catalog without any credentials. Load datasets directly into pandas, polars, or a DuckDB connection (with range-request pushdown, so only the row-groups you query are fetched).
+
+## Install
+
+```bash
+pip install aesops                  # core: httpx + duckdb
+pip install 'aesops[pandas]'        # + pandas
+pip install 'aesops[polars]'        # + polars
+pip install 'aesops[pandas,polars]' # both
+```
+
+Requires Python 3.9+.
+
+## Quickstart
+
+```python
+from aesops import Client
+
+# No key needed to browse — the full catalog is public
+client = Client()
+
+datasets = client.list(query="housing", license="MIT")
+for ds in datasets:
+    print(ds.slug, ds.row_count, ds.keyless)
+
+# Fetch metadata + schema (works for any dataset, keyless or not)
+ds = client.load_dataset("kenya-housing-prices")
+print(ds.name, ds.row_count, ds.column_count)
+for col in ds.detail.columns:
+    print(col.name, col.dtype)
+
+# Summary stats per column — no network call, no API key needed; built from
+# the metadata already fetched by load_dataset()
+print(ds.describe())
+# ┌────────┬────────┬───────┬────────────┬────────┬────────┬─────────┬──────┬────────┬────────┬────────┐
+# │ column │  dtype │ count │ null_count │ null_% │ unique │    mean │  std │    min │ median │    max │
+# ├────────┼────────┼───────┼────────────┼────────┼────────┼─────────┼──────┼────────┼────────┼────────┤
+# │   year │ number │   178 │          0 │    0.0 │     16 │ 2018.50 │ 4.30 │ 2011.0 │ 2018.50 │ 2026.0 │
+# │  month │ string │   178 │          0 │    0.0 │     12 │     NaN │  NaN │    NaN │    NaN │    NaN │
+# └────────┴────────┴───────┴────────────┴────────┴────────┴─────────┴──────┴────────┴────────┴────────┘
+
+# In a Jupyter/IPython notebook (or Zed's REPL), the same call renders as a
+# bordered HTML table instead when it's the last expression in a cell.
+
+# Want a real pandas.DataFrame for further chaining (.loc, filtering, etc.)?
+ds.describe().to_frame()
+
+# A compact overview — name, slug, description, AI insights, link to the
+# dataset's Aesops page, and any linked community discussions. Also no
+# network call, no API key needed.
+print(ds.summary())
+```
+
+## Full catalog
+
+`list()` always returns the full catalog and never sends the API key even if
+the `Client` has one configured:
+
+```python
+client = Client()
+datasets = client.list(category="finance")
+for ds in datasets:
+    print(ds.slug, ds.keyless)  # keyless tells you which need a key to load
+```
+
+This is deliberate: the catalog is public for discovery/marketing purposes.
+What's gated is loading actual data (see below).
+
+## Loading data
+
+Loading a dataset's actual rows (`.to_pandas()`, `.to_polars()`, `.to_duckdb()`,
+`.sql()`, `.to_csv()`) requires a **read-scoped API key** — _unless_ the
+dataset is currently keyless (`ds.keyless`), in which case no key is
+needed. Create a key at
+[aesops.co.ke/profile/api-keys](https://aesops.co.ke/profile/api-keys).
+
+```python
+client = Client(api_key="Aes_...")
+
+ds = client.load_dataset("kenya-housing-prices")
+
+# pandas
+df = ds.to_pandas()
+
+# polars
+lf = ds.to_polars()
+
+# DuckDB (predicate + projection pushdown — only fetches the row-groups you touch)
+con = ds.to_duckdb()
+con.sql("SELECT county, avg(price) FROM data GROUP BY county").df()
+
+# or use ds.sql() directly
+ds.sql("SELECT county, avg(price) FROM data GROUP BY 1").df()
+
+# CSV export (client-side, no extra server compute)
+ds.to_csv("/tmp/housing.csv")
+
+# Just want a peek? `limit` is pushed down through read_parquet, so it also
+# cuts what crosses the network, not just what lands in the DataFrame.
+sample = ds.to_pandas(limit=100)
+ds.to_polars(limit=100)
+ds.to_csv("/tmp/sample.csv", limit=100)
+
+# for anything more specific (offset, filters, ordering) use ds.sql() directly
+ds.sql("SELECT * FROM data ORDER BY price DESC LIMIT 20").df()
+```
+
+### New to DuckDB?
+
+`ds.sql()` and `ds.to_duckdb().sql()` return a [`duckdb.DuckDBPyRelation`](https://duckdb.org/docs/stable/clients/python/reference/#duckdb.DuckDBPyRelation) —
+a lazy query result, not a DataFrame. Call `.df()` for pandas, `.pl()` for
+polars, `.arrow()` for an Arrow table, or `.fetchall()` for plain Python
+tuples. If SQL or DuckDB itself is new to you: the
+[DuckDB docs](https://duckdb.org/docs/stable/) are a good starting point, and
+the [Python client guide](https://duckdb.org/docs/stable/clients/python/overview)
+covers the API this SDK builds on.
+
+## Brand colors
+
+The Aesops chart palette is available as plain hex strings, so a chart built
+from Aesops data can match the platform's own look — and printing a palette
+renders actual color swatches, not just hex text:
+
+```python
+from aesops import colors
+
+colors.primary          # '#155f6b' — brand teal
+colors.aeschart         # 6-slot categorical series for chart colors, teal-led
+colors.dark.primary     # '#D4956A' — dark mode swaps primary to terracotta
+colors.dark.aeschart    # dark mode's chart series
+
+# See the actual chart colors, not just hex codes: in a terminal, prints
+# each of the 6 aeschart slots as a colored block (ANSI truecolor) next to
+# its name and hex value — separately for light and dark.
+print(colors.light)
+print(colors.dark)
+
+# In a Jupyter/IPython notebook, colors.light / colors.dark render as HTML
+# swatches automatically when they're the last expression in a cell.
+
+# matplotlib
+import matplotlib.pyplot as plt
+fig, ax = plt.subplots()
+ax.set_prop_cycle(color=list(colors.aeschart))
+```
+
+No network call, no API key required — `colors` mirrors the same design
+tokens the Aesops web app itself uses (see `DESIGN.md`). Full field list:
+`primary`, `accent`, `background`, `foreground`, `card`, `muted`, `border`,
+`success`, `destructive` (each with a `_foreground` counterpart where
+relevant), and `aeschart` — on both the top-level (light) module and
+`colors.light`/`colors.dark` explicitly.
+
+## Context manager
+
+```python
+with Client(api_key="Aes_...") as client:
+    df = client.load_dataset("kenya-housing-prices").to_pandas()
+```
+
+## Error handling
+
+```python
+from aesops import AuthError, NotFoundError, ApiError
+
+try:
+    ds = client.load_dataset("does-not-exist")
+except NotFoundError:
+    print("dataset not found")
+except AuthError:
+    print("invalid or missing API key")
+except ApiError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+## Notes
+
+- Signed URLs are fetched **lazily** at query time (not at `load_dataset`) and
+  automatically re-fetched on expiry or a 403 from storage, so long-running
+  sessions never stall.
+- All format conversion (CSV, Arrow, etc.) happens locally — zero extra server
+  compute.
+- `list()` and `load_dataset()` always work without an `api_key` — the full
+  catalog and every dataset's metadata are public. Loading actual data
+  (`.to_pandas()`, `.to_polars()`, `.to_duckdb()`, `.sql()`, `.to_csv()`)
+  requires a key unless the dataset is currently keyless (`ds.keyless`).
+- `.describe()` and `.summary()` never touch the network or require a key —
+  they summarize the metadata `load_dataset()` already fetched. `.describe()`
+  returns a `DescribeTable` (bordered text/HTML display, no pandas required);
+  call `.to_frame()` on it for a real `pandas.DataFrame`. `.summary()` returns
+  a `Summary` (same bordered text/HTML display) with name, slug, description,
+  AI insights, a link to the dataset's Aesops page, and any linked community
+  discussions.
+- Datasets are always served at their latest active version — there's no
+  version pinning.

aesops-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+aesops/__init__.py,sha256=bkUOqg11LHI2BzEi9DRpw_XHx6f5ASOvrmwQIVN52t4,605
+aesops/client.py,sha256=UNRmFSPuwcrv8oaYSA8VlVfPaV6tXSgHJhETAKB-DSw,4457
+aesops/colors.py,sha256=5vAXlL7CE7TUqpOI4ZwgyFqLdOJ0cZ59qDJsJdPwS7E,4636
+aesops/dataset.py,sha256=NI1xbTXSWoiccLeG-7Ft7PyzmBpEkV0lV6im58NVyPg,15865
+aesops/errors.py,sha256=8LGBlQCI_n7DlXmtYtScKe3HX1Tnbt2yD1KJXtp-Lvo,663
+aesops/models.py,sha256=kUHDEFSvbMnjIgd-EvpC1MOB-8QKgtcvm97le8BbJpo,2075
+aesops-0.1.0.dist-info/METADATA,sha256=iQT5tFXN-Rp9zmV9lBNhe45G25uTIqxqoJK9JTBXzWc,8724
+aesops-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+aesops-0.1.0.dist-info/licenses/LICENSE,sha256=VnKC0z_OU6qUKncNEPwGULw3Q58557DbRIw6hPf5drY,1063
+aesops-0.1.0.dist-info/RECORD,,

aesops-0.1.0.dist-info/WHEEL

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

aesops-0.1.0.dist-info/licenses/LICENSE

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