pexafy 0.1.0__py3-none-any.whl

pexafy/__init__.py

@@ -0,0 +1,61 @@
+"""Python client for the Pexafy image search API.
+
+    from pexafy import Client
+
+    client = Client("your-api-key")
+    for photo in client.search("a quiet street in the rain", per_page=10):
+        print(photo.urls.regular)
+
+Get a key at https://pexafy.com — the free tier does not need a card.
+"""
+
+__version__ = "0.1.0"
+
+from .client import DEFAULT_BASE_URL, AsyncClient, Client
+from .errors import (
+    APIError,
+    AuthenticationError,
+    ConnectionError_,
+    NotFoundError,
+    PermissionError_,
+    PexafyError,
+    RateLimitError,
+    ServerError,
+    TimeoutError_,
+    ValidationError,
+)
+from .models import (
+    Attribution,
+    Collection,
+    CollectionItem,
+    Pagination,
+    Photo,
+    Photographer,
+    PhotoUrls,
+    SearchResult,
+)
+
+__all__ = [
+    "Client",
+    "AsyncClient",
+    "DEFAULT_BASE_URL",
+    "Photo",
+    "PhotoUrls",
+    "Attribution",
+    "Photographer",
+    "Collection",
+    "CollectionItem",
+    "Pagination",
+    "SearchResult",
+    "PexafyError",
+    "APIError",
+    "AuthenticationError",
+    "PermissionError_",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    "ServerError",
+    "TimeoutError_",
+    "ConnectionError_",
+    "__version__",
+]

pexafy/cli.py

@@ -0,0 +1,89 @@
+"""Command line interface.
+
+    pexafy search "morning fog over pine trees" -n 5
+    pexafy photo 019e0eb8-b028-73cb-9296-dfa70f557bc9
+    pexafy similar 019e0eb8-b028-73cb-9296-dfa70f557bc9
+    pexafy usage
+
+Reads the key from PEXAFY_API_KEY.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from . import __version__, errors
+from .client import Client
+
+
+def _print_photos(photos: list[Any], as_json: bool) -> None:
+    if as_json:
+        json.dump([p.raw for p in photos], sys.stdout, indent=2)
+        sys.stdout.write("\n")
+        return
+    for p in photos:
+        score = f"{p.relevance_score:.3f}" if p.relevance_score is not None else "  -  "
+        size = f"{p.width}x{p.height}" if p.width else ""
+        print(
+            f"{score}  {p.photo_id}  {size:>11}  "
+            f"{p.color_name:<10} {p.source:<10} {p.urls.regular}"
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pexafy", description="Search stock photos from the terminal."
+    )
+    parser.add_argument("--version", action="version", version=f"pexafy {__version__}")
+    parser.add_argument("--json", action="store_true", help="raw JSON instead of a table")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("search", help="search by description")
+    s.add_argument("query")
+    s.add_argument("-n", "--per-page", type=int, default=10)
+    s.add_argument("--color")
+    s.add_argument("--orientation")
+    s.add_argument("--source")
+
+    p = sub.add_parser("photo", help="fetch one photo")
+    p.add_argument("photo_id")
+
+    sim = sub.add_parser("similar", help="photos that look like this one")
+    sim.add_argument("photo_id")
+    sim.add_argument("-n", "--per-page", type=int, default=10)
+
+    sub.add_parser("usage", help="current month usage")
+
+    args = parser.parse_args(argv)
+
+    try:
+        with Client() as client:
+            if args.command == "search":
+                result = client.search(
+                    args.query,
+                    per_page=args.per_page,
+                    color_name=args.color,
+                    orientation=args.orientation,
+                    source=args.source,
+                )
+                _print_photos(result.photos, args.json)
+            elif args.command == "photo":
+                photo = client.get_photo(args.photo_id)
+                _print_photos([photo], args.json)
+            elif args.command == "similar":
+                result = client.similar(args.photo_id, per_page=args.per_page)
+                _print_photos(result.photos, args.json)
+            elif args.command == "usage":
+                json.dump(client.usage(), sys.stdout, indent=2)
+                sys.stdout.write("\n")
+    except errors.PexafyError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pexafy/client.py

@@ -0,0 +1,447 @@
+"""Synchronous and asynchronous clients for the Pexafy API."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from collections.abc import AsyncIterator, Iterator, Sequence
+from pathlib import Path
+from typing import Any, BinaryIO, Optional, Union
+
+import httpx
+
+from . import errors
+from .models import (
+    Collection,
+    CollectionItem,
+    Pagination,
+    Photo,
+    Photographer,
+    SearchResult,
+)
+
+__all__ = ["Client", "AsyncClient", "DEFAULT_BASE_URL"]
+
+DEFAULT_BASE_URL = "https://api.pexafy.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_RETRIES = 2
+RETRY_STATUS = {429, 500, 502, 503, 504}
+
+ImageInput = Union[str, Path, bytes, BinaryIO]
+
+
+def _csv(value: Union[str, Sequence[str], None]) -> Optional[str]:
+    """The API takes repeated filters as a comma separated list."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return ",".join(str(v) for v in value)
+
+
+def _clean(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _open_image(image: ImageInput) -> tuple[str, Any]:
+    """Normalise the several things a caller might hand us into a file tuple."""
+    if isinstance(image, (str, Path)):
+        path = Path(image)
+        return path.name, path.read_bytes()
+    if isinstance(image, bytes):
+        return "query.jpg", image
+    name = getattr(image, "name", "query.jpg")
+    return Path(str(name)).name, image.read()
+
+
+class _Base:
+    """Everything that does not touch the network."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_RETRIES,
+    ) -> None:
+        key = api_key or os.environ.get("PEXAFY_API_KEY")
+        if not key:
+            raise errors.PexafyError(
+                "No API key. Pass api_key= or set PEXAFY_API_KEY. "
+                "Keys are created at https://pexafy.com/dashboard/"
+            )
+        self.api_key = key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        from . import __version__
+
+        return {
+            "x-api-key": self.api_key,
+            "accept": "application/json",
+            "user-agent": f"pexafy-python/{__version__}",
+        }
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/api/v1{path}"
+
+    @staticmethod
+    def _retry_delay(attempt: int, response: Optional[httpx.Response]) -> float:
+        """Honour Retry-After when the server sends one, back off otherwise."""
+        if response is not None:
+            header = response.headers.get("retry-after")
+            if header:
+                try:
+                    return min(float(header), 60.0)
+                except ValueError:
+                    pass
+        return min(2.0**attempt, 30.0) + random.random() * 0.3
+
+    def _unwrap(self, response: httpx.Response) -> dict[str, Any]:
+        """Turn the response envelope into data, or raise the right error."""
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+
+        if response.is_success and body.get("success", True):
+            return body
+
+        err = body.get("error") or {}
+        message = (
+            err.get("message") or body.get("detail")
+            or response.reason_phrase or "request failed"
+        )
+        if isinstance(message, list):  # FastAPI validation detail
+            message = "; ".join(str(m.get("msg", m)) for m in message)
+
+        exc_class = errors.from_status(response.status_code)
+        kwargs: dict[str, Any] = {
+            "status_code": response.status_code,
+            "code": err.get("code"),
+            "request_id": err.get("request_id") or (body.get("meta") or {}).get("request_id"),
+            "payload": body,
+        }
+        if exc_class is errors.RateLimitError:
+            retry_after = response.headers.get("retry-after")
+            kwargs["retry_after"] = float(retry_after) if retry_after else None
+        raise exc_class(str(message), **kwargs)
+
+    @staticmethod
+    def _to_search_result(body: dict[str, Any]) -> SearchResult:
+        meta = body.get("meta") or {}
+        return SearchResult(
+            photos=[Photo.from_dict(p) for p in body.get("data") or []],
+            pagination=Pagination.from_dict(body.get("pagination") or {}),
+            request_id=meta.get("request_id", ""),
+            took_ms=meta.get("took_ms"),
+        )
+
+    def _search_params(
+        self,
+        q: Optional[str],
+        *,
+        color_name=None, color_hex=None, color_tolerance=None,
+        orientation=None, source=None, license_type=None, photographer=None,
+        per_page=None, limit=None, score_threshold=None, cursor=None,
+        fields=None, after_date=None, sort_by=None,
+    ) -> dict[str, Any]:
+        return _clean({
+            "q": q,
+            "color_name": _csv(color_name),
+            "color_hex": color_hex,
+            "color_tolerance": color_tolerance,
+            "orientation": _csv(orientation),
+            "source": _csv(source),
+            "license_type": _csv(license_type),
+            "photographer": photographer,
+            "per_page": per_page,
+            "limit": limit,
+            "score_threshold": score_threshold,
+            "cursor": cursor,
+            "fields": _csv(fields),
+            "after_date": str(after_date) if after_date else None,
+            "sort_by": sort_by,
+        })
+
+
+class Client(_Base):
+    """Blocking client.
+
+    >>> from pexafy import Client
+    >>> client = Client("your-api-key")
+    >>> for photo in client.search("sunrise over a foggy valley", per_page=5):
+    ...     print(photo.photo_id, photo.urls.regular)
+
+    Safe to keep around for the lifetime of your process; it holds one
+    connection pool. Close it when you are done, or use it as a context
+    manager.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = httpx.Client(timeout=self.timeout, headers=self._headers)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        url = self._url(path)
+        last_response: Optional[httpx.Response] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(method, url, **kwargs)
+            except httpx.TimeoutException as exc:
+                if attempt >= self.max_retries:
+                    raise errors.TimeoutError_(
+                        f"{method} {path} timed out after {self.timeout}s"
+                    ) from exc
+                time.sleep(self._retry_delay(attempt, None))
+                continue
+            except httpx.TransportError as exc:
+                if attempt >= self.max_retries:
+                    raise errors.ConnectionError_(
+                        f"could not reach {self.base_url}: {exc}"
+                    ) from exc
+                time.sleep(self._retry_delay(attempt, None))
+                continue
+
+            if response.status_code in RETRY_STATUS and attempt < self.max_retries:
+                last_response = response
+                time.sleep(self._retry_delay(attempt, response))
+                continue
+            return self._unwrap(response)
+
+        return self._unwrap(last_response)  # pragma: no cover - loop always returns
+
+    # -- search ---------------------------------------------------------
+
+    def search(self, q: str, **filters: Any) -> SearchResult:
+        """Search by description.
+
+        Write what you would say to a person: `two people hiking on a ridge at
+        dawn` works better than `hiking dawn`. The engine matches meaning, so
+        keyword stuffing makes results worse, not better.
+        """
+        params = self._search_params(q, **filters)
+        return self._to_search_result(self._request("GET", "/search/photos", params=params))
+
+    def iter_search(
+        self, q: str, *, max_results: Optional[int] = None, **filters: Any
+    ) -> Iterator[Photo]:
+        """Walk every page, following the cursor for you."""
+        seen = 0
+        cursor = filters.pop("cursor", None)
+        while True:
+            page = self.search(q, cursor=cursor, **filters)
+            for photo in page.photos:
+                yield photo
+                seen += 1
+                if max_results is not None and seen >= max_results:
+                    return
+            if not page.has_more or not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    def search_by_image(self, image: ImageInput, **filters: Any) -> SearchResult:
+        """Find photos that look like the one you pass in.
+
+        Accepts a path, raw bytes, or an open binary file.
+        """
+        filename, content = _open_image(image)
+        params = self._search_params(None, **filters)
+        body = self._request(
+            "POST", "/search/photos",
+            files={"image": (filename, content)},
+            params=params,
+        )
+        return self._to_search_result(body)
+
+    # -- photos ---------------------------------------------------------
+
+    def get_photo(self, photo_id: str) -> Photo:
+        return Photo.from_dict(self._request("GET", f"/photos/{photo_id}")["data"])
+
+    def similar(self, photo_id: str, **filters: Any) -> SearchResult:
+        params = self._search_params(None, **filters)
+        return self._to_search_result(
+            self._request("GET", f"/photos/{photo_id}/similar", params=params)
+        )
+
+    # -- facets ---------------------------------------------------------
+
+    def colors(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/facets/colors")["data"]
+
+    def sources(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/facets/sources")["data"]
+
+    def orientations(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/facets/orientations")["data"]
+
+    def licenses(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/facets/licenses")["data"]
+
+    def suggest_photographers(self, q: str, *, limit: Optional[int] = None) -> list[Photographer]:
+        params = _clean({"q": q, "limit": limit})
+        data = self._request("GET", "/facets/photographers/suggest", params=params)["data"]
+        return [Photographer.from_dict(p) for p in data]
+
+    def photographer(self, username: str) -> list[Photographer]:
+        data = self._request("GET", f"/facets/photographers/{username}")["data"]
+        return [Photographer.from_dict(p) for p in data]
+
+    # -- collections ----------------------------------------------------
+
+    def collections(self) -> list[Collection]:
+        return [Collection.from_dict(c) for c in self._request("GET", "/collections")["data"]]
+
+    def create_collection(
+        self, name: str, *, description: Optional[str] = None, is_public: bool = False
+    ) -> Collection:
+        body = _clean({"name": name, "description": description, "is_public": is_public})
+        return Collection.from_dict(self._request("POST", "/collections", json=body)["data"])
+
+    def collection(self, collection_id: int) -> Collection:
+        return Collection.from_dict(self._request("GET", f"/collections/{collection_id}")["data"])
+
+    def delete_collection(self, collection_id: int) -> None:
+        self._request("DELETE", f"/collections/{collection_id}")
+
+    def add_to_collection(self, collection_id: int, photo_id: str) -> CollectionItem:
+        body = self._request(
+            "POST", f"/collections/{collection_id}/photos", json={"photo_id": photo_id}
+        )
+        return CollectionItem.from_dict(body["data"])
+
+    def remove_from_collection(self, collection_id: int, photo_id: str) -> None:
+        self._request("DELETE", f"/collections/{collection_id}/photos/{photo_id}")
+
+    # -- usage ----------------------------------------------------------
+
+    def usage(self) -> dict[str, Any]:
+        return self._request("GET", "/usage")["data"]
+
+    def usage_daily(self) -> dict[str, Any]:
+        return self._request("GET", "/usage/daily")["data"]
+
+    def usage_monthly(self) -> dict[str, Any]:
+        return self._request("GET", "/usage/monthly")["data"]
+
+    def usage_by_key(self) -> dict[str, Any]:
+        return self._request("GET", "/usage/by-key")["data"]
+
+
+class AsyncClient(_Base):
+    """Same surface as :class:`Client`, awaitable.
+
+    >>> async with AsyncClient() as client:
+    ...     page = await client.search("empty office at night")
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **kwargs: Any) -> None:
+        super().__init__(api_key, **kwargs)
+        self._http = httpx.AsyncClient(timeout=self.timeout, headers=self._headers)
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        import asyncio
+
+        url = self._url(path)
+        last_response: Optional[httpx.Response] = None
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = await self._http.request(method, url, **kwargs)
+            except httpx.TimeoutException as exc:
+                if attempt >= self.max_retries:
+                    raise errors.TimeoutError_(
+                        f"{method} {path} timed out after {self.timeout}s"
+                    ) from exc
+                await asyncio.sleep(self._retry_delay(attempt, None))
+                continue
+            except httpx.TransportError as exc:
+                if attempt >= self.max_retries:
+                    raise errors.ConnectionError_(
+                        f"could not reach {self.base_url}: {exc}"
+                    ) from exc
+                await asyncio.sleep(self._retry_delay(attempt, None))
+                continue
+
+            if response.status_code in RETRY_STATUS and attempt < self.max_retries:
+                last_response = response
+                await asyncio.sleep(self._retry_delay(attempt, response))
+                continue
+            return self._unwrap(response)
+
+        return self._unwrap(last_response)  # pragma: no cover
+
+    async def search(self, q: str, **filters: Any) -> SearchResult:
+        params = self._search_params(q, **filters)
+        return self._to_search_result(await self._request("GET", "/search/photos", params=params))
+
+    async def iter_search(
+        self, q: str, *, max_results: Optional[int] = None, **filters: Any
+    ) -> AsyncIterator[Photo]:
+        seen = 0
+        cursor = filters.pop("cursor", None)
+        while True:
+            page = await self.search(q, cursor=cursor, **filters)
+            for photo in page.photos:
+                yield photo
+                seen += 1
+                if max_results is not None and seen >= max_results:
+                    return
+            if not page.has_more or not page.next_cursor:
+                return
+            cursor = page.next_cursor
+
+    async def search_by_image(self, image: ImageInput, **filters: Any) -> SearchResult:
+        filename, content = _open_image(image)
+        params = self._search_params(None, **filters)
+        body = await self._request(
+            "POST", "/search/photos", files={"image": (filename, content)}, params=params
+        )
+        return self._to_search_result(body)
+
+    async def get_photo(self, photo_id: str) -> Photo:
+        body = await self._request("GET", f"/photos/{photo_id}")
+        return Photo.from_dict(body["data"])
+
+    async def similar(self, photo_id: str, **filters: Any) -> SearchResult:
+        params = self._search_params(None, **filters)
+        body = await self._request("GET", f"/photos/{photo_id}/similar", params=params)
+        return self._to_search_result(body)
+
+    async def colors(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/facets/colors"))["data"]
+
+    async def sources(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/facets/sources"))["data"]
+
+    async def orientations(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/facets/orientations"))["data"]
+
+    async def licenses(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/facets/licenses"))["data"]
+
+    async def usage(self) -> dict[str, Any]:
+        return (await self._request("GET", "/usage"))["data"]

pexafy/errors.py

@@ -0,0 +1,102 @@
+"""Exceptions raised by the client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class PexafyError(Exception):
+    """Base class for everything this package raises."""
+
+
+class APIError(PexafyError):
+    """The API answered, but with an error.
+
+    ``code`` is the machine readable identifier from the response envelope when
+    the server sent one; it is stable across versions and safe to branch on.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        payload: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.payload = payload or {}
+
+    def __str__(self) -> str:
+        bits = [self.message]
+        if self.status_code:
+            bits.append(f"(HTTP {self.status_code}")
+            if self.code:
+                bits[-1] += f", {self.code}"
+            bits[-1] += ")"
+        if self.request_id:
+            bits.append(f"request_id={self.request_id}")
+        return " ".join(bits)
+
+
+class AuthenticationError(APIError):
+    """Missing, malformed or revoked API key."""
+
+
+class PermissionError_(APIError):
+    """The key is valid but lacks the scope for this call."""
+
+
+class NotFoundError(APIError):
+    """No such photo, collection or photographer."""
+
+
+class RateLimitError(APIError):
+    """Too many requests, or the plan quota is exhausted.
+
+    ``retry_after`` is the number of seconds the server asked us to wait, when
+    it said so.
+    """
+
+    def __init__(self, *args: Any, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class ValidationError(APIError):
+    """The request was rejected before it reached the search engine."""
+
+
+class ServerError(APIError):
+    """Something broke on our side. These are the ones worth retrying."""
+
+
+class TimeoutError_(PexafyError):
+    """The request took longer than the configured timeout."""
+
+
+class ConnectionError_(PexafyError):
+    """The API could not be reached at all."""
+
+
+STATUS_MAP = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionError_,
+    404: NotFoundError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+def from_status(status: int) -> type[APIError]:
+    if status in STATUS_MAP:
+        return STATUS_MAP[status]
+    if status >= 500:
+        return ServerError
+    return APIError

pexafy/models.py

@@ -0,0 +1,237 @@
+"""Response objects.
+
+Plain dataclasses rather than a validation library — the dependency footprint
+stays at httpx alone, and unknown fields are kept in ``raw`` so a server side
+addition never breaks a client that has not been updated yet.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from typing import Any, Optional
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    if not value or not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _parse_date(value: Any) -> Optional[date]:
+    dt = _parse_dt(value)
+    return dt.date() if dt else None
+
+
+@dataclass
+class PhotoUrls:
+    """The same image at five widths. Pick the smallest one that fits."""
+
+    thumb: str = ""
+    small: str = ""
+    regular: str = ""
+    large: str = ""
+    full: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> PhotoUrls:
+        d = d or {}
+        return cls(
+            thumb=d.get("thumb", ""),
+            small=d.get("small", ""),
+            regular=d.get("regular", ""),
+            large=d.get("large", ""),
+            full=d.get("full", ""),
+        )
+
+
+@dataclass
+class Attribution:
+    """Credit line for the photographer, ready to drop into a page."""
+
+    html: str = ""
+    plain: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Attribution:
+        d = d or {}
+        return cls(html=d.get("html", ""), plain=d.get("plain", ""))
+
+
+@dataclass
+class Photo:
+    photo_id: str
+    image_url: str = ""
+    urls: PhotoUrls = field(default_factory=PhotoUrls)
+    width: Optional[int] = None
+    height: Optional[int] = None
+    blur_hash: Optional[str] = None
+    orientation: str = ""
+    color_name: str = ""
+    color_hex: str = ""
+    photographer_username: str = ""
+    photographer_full_name: Optional[str] = None
+    photographer_url: Optional[str] = None
+    source: str = ""
+    license_type: str = ""
+    source_image_url: Optional[str] = None
+    source_description: Optional[str] = None
+    description: Optional[str] = None
+    alt_description: Optional[str] = None
+    uploaded_on: Optional[date] = None
+    relevance_score: Optional[float] = None
+    attribution: Attribution = field(default_factory=Attribution)
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def aspect_ratio(self) -> Optional[float]:
+        if self.width and self.height:
+            return self.width / self.height
+        return None
+
+    @property
+    def alt_text(self) -> str:
+        """Best available text for an ``alt`` attribute."""
+        return self.alt_description or self.description or self.source_description or ""
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Photo:
+        return cls(
+            photo_id=d.get("photo_id", ""),
+            image_url=d.get("image_url", ""),
+            urls=PhotoUrls.from_dict(d.get("urls") or {}),
+            width=d.get("width"),
+            height=d.get("height"),
+            blur_hash=d.get("blur_hash"),
+            orientation=d.get("orientation", ""),
+            color_name=d.get("color_name", ""),
+            color_hex=d.get("color_hex", ""),
+            photographer_username=d.get("photographer_username", ""),
+            photographer_full_name=d.get("photographer_full_name"),
+            photographer_url=d.get("photographer_url"),
+            source=d.get("source", ""),
+            license_type=d.get("license_type", ""),
+            source_image_url=d.get("source_image_url"),
+            source_description=d.get("source_description"),
+            description=d.get("description"),
+            alt_description=d.get("alt_description"),
+            uploaded_on=_parse_date(d.get("uploaded_on")),
+            relevance_score=d.get("relevance_score"),
+            attribution=Attribution.from_dict(d.get("attribution") or {}),
+            raw=d,
+        )
+
+
+@dataclass
+class Photographer:
+    username: str
+    full_name: Optional[str] = None
+    source: str = ""
+    url: Optional[str] = None
+    photos_count: int = 0
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Photographer:
+        return cls(
+            username=d.get("username", ""),
+            full_name=d.get("full_name"),
+            source=d.get("source", ""),
+            url=d.get("url"),
+            photos_count=d.get("photos_count", 0),
+        )
+
+
+@dataclass
+class Collection:
+    id: int
+    name: str = ""
+    description: Optional[str] = None
+    is_public: bool = False
+    cover_photo_id: Optional[str] = None
+    photos_count: int = 0
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Collection:
+        return cls(
+            id=d.get("id", 0),
+            name=d.get("name", ""),
+            description=d.get("description"),
+            is_public=bool(d.get("is_public", False)),
+            cover_photo_id=d.get("cover_photo_id"),
+            photos_count=d.get("photos_count", 0),
+            created_at=_parse_dt(d.get("created_at")),
+            updated_at=_parse_dt(d.get("updated_at")),
+        )
+
+
+@dataclass
+class CollectionItem:
+    id: int
+    photo_id: str
+    photo_thumbnail_url: Optional[str] = None
+    photo_source: Optional[str] = None
+    photo_photographer: Optional[str] = None
+    added_at: Optional[datetime] = None
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> CollectionItem:
+        return cls(
+            id=d.get("id", 0),
+            photo_id=d.get("photo_id", ""),
+            photo_thumbnail_url=d.get("photo_thumbnail_url"),
+            photo_source=d.get("photo_source"),
+            photo_photographer=d.get("photo_photographer"),
+            added_at=_parse_dt(d.get("added_at")),
+        )
+
+
+@dataclass
+class Pagination:
+    next_cursor: Optional[str] = None
+    per_page: int = 0
+    has_more: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> Pagination:
+        d = d or {}
+        return cls(
+            next_cursor=d.get("next_cursor"),
+            per_page=d.get("per_page", 0),
+            has_more=bool(d.get("has_more", False)),
+        )
+
+
+@dataclass
+class SearchResult:
+    """One page of results.
+
+    Iterating it yields photos, so ``for photo in client.search(...)`` reads the
+    way you would expect. Use :meth:`Client.iter_search` to walk every page.
+    """
+
+    photos: list[Photo]
+    pagination: Pagination
+    request_id: str = ""
+    took_ms: Optional[float] = None
+
+    def __iter__(self):
+        return iter(self.photos)
+
+    def __len__(self) -> int:
+        return len(self.photos)
+
+    def __getitem__(self, index: int) -> Photo:
+        return self.photos[index]
+
+    @property
+    def next_cursor(self) -> Optional[str]:
+        return self.pagination.next_cursor
+
+    @property
+    def has_more(self) -> bool:
+        return self.pagination.has_more

pexafy-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: pexafy
+Version: 0.1.0
+Summary: Python client for the Pexafy stock photo search API
+Project-URL: Homepage, https://pexafy.com
+Project-URL: Documentation, https://docs.pexafy.com
+Project-URL: Source, https://github.com/Pexafy/pexafy-python
+Project-URL: Issues, https://github.com/Pexafy/pexafy-python/issues
+Author-email: Marouane Tijani <marouane@pexafy.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,image search,semantic search,stock photos
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pexafy-python
+
+Python client for the [Pexafy](https://pexafy.com) image search API. Search a
+catalogue of free stock photos by describing what you want, or by handing it an
+image to match.
+
+```bash
+pip install pexafy
+```
+
+## Getting started
+
+```python
+from pexafy import Client
+
+client = Client("your-api-key")
+
+for photo in client.search("a quiet street in the rain", per_page=5):
+    print(photo.urls.regular, "-", photo.alt_text)
+```
+
+The key comes from your [dashboard](https://pexafy.com/dashboard/); the free
+tier does not ask for a card. If you would rather not put it in the code, the
+client picks up `PEXAFY_API_KEY` from the environment.
+
+## Writing queries
+
+Search runs on meaning, not keywords, so full sentences work better than a pile
+of nouns. `two people hiking on a ridge at dawn` finds what you would expect;
+`hiking dawn people` gives you a worse ranking, because you have thrown away
+the relationships between the words.
+
+Filters narrow the result set after the semantic match:
+
+```python
+result = client.search(
+    "an empty office at night",
+    orientation="landscape",
+    color_name="blue",
+    source=["Pexels", "Unsplash"],
+    per_page=20,
+)
+
+print(len(result), "photos in", result.took_ms, "ms")
+```
+
+List filters accept either a list or a comma separated string.
+
+## Paging
+
+A single call returns one page. `iter_search` follows the cursor for you and
+yields photos until the results run out or you have seen enough:
+
+```python
+for photo in client.iter_search("vintage typewriter", max_results=200):
+    download(photo.urls.large)
+```
+
+## Search by image
+
+Pass a path, raw bytes, or an open file:
+
+```python
+similar = client.search_by_image("moodboard/reference.jpg", per_page=12)
+```
+
+If you already have a photo id, `client.similar(photo_id)` is cheaper — the
+image does not have to be uploaded and encoded again.
+
+## Async
+
+The same surface, awaitable:
+
+```python
+import asyncio
+from pexafy import AsyncClient
+
+async def main():
+    async with AsyncClient() as client:
+        pages = await asyncio.gather(
+            client.search("desert road"),
+            client.search("snow covered pines"),
+        )
+    for page in pages:
+        print(len(page))
+
+asyncio.run(main())
+```
+
+## Errors
+
+Everything raised inherits from `PexafyError`. The ones worth catching
+separately:
+
+```python
+from pexafy import errors
+
+try:
+    client.search("...")
+except errors.RateLimitError as exc:
+    time.sleep(exc.retry_after or 60)
+except errors.AuthenticationError:
+    ...          # key is missing, malformed or revoked
+except errors.APIError as exc:
+    print(exc.status_code, exc.code, exc.request_id)
+```
+
+`request_id` is worth logging. It is the fastest way to get an answer if you
+need to ask about a specific call.
+
+Timeouts and 5xx responses are retried twice with backoff, and `Retry-After` is
+honoured when the server sends it. Set `max_retries=0` if you would rather
+handle that yourself.
+
+## Command line
+
+```
+$ pexafy search "morning fog over pine trees" -n 3
+0.847  019e0eb8-b028-73cb-9296-dfa70f557bc9   4000x2667   green      Pexels     https://...
+0.812  019e4c9b-3022-7660-b43d-e730b8435f24   6000x4000   green      Unsplash   https://...
+0.798  019e4f39-66d4-7ef2-bc9b-eb5340fd243e   3648x5472   grey       Pexels     https://...
+```
+
+`pexafy photo <id>`, `pexafy similar <id>` and `pexafy usage` are also there.
+Add `--json` to any of them for the raw response.
+
+## Attribution
+
+Photos come from several providers with different licence terms. Every photo
+carries an `attribution` object with a ready made credit line:
+
+```python
+photo.attribution.plain   # Photo by J. Doe
+photo.attribution.html    # <a href="...">J. Doe</a>
+```
+
+Check `photo.license_type` if your use depends on it.
+
+## Reference
+
+| Method | What it does |
+| --- | --- |
+| `search(q, **filters)` | one page of results |
+| `iter_search(q, max_results=None, **filters)` | every page, cursor handled |
+| `search_by_image(image, **filters)` | match an image you supply |
+| `get_photo(photo_id)` | one photo by id |
+| `similar(photo_id, **filters)` | photos close to an existing one |
+| `colors()` `sources()` `orientations()` `licenses()` | filter values you can use |
+| `suggest_photographers(q)` `photographer(username)` | photographer lookup |
+| `collections()` `create_collection(name)` `add_to_collection(id, photo_id)` | saved sets |
+| `usage()` `usage_daily()` `usage_monthly()` `usage_by_key()` | where you are against your quota |
+
+Full API documentation is at [docs.pexafy.com](https://docs.pexafy.com).
+
+## Requirements
+
+Python 3.9 or newer. The only dependency is `httpx`.
+
+## Licence
+
+MIT.

pexafy-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pexafy/__init__.py,sha256=CuOAdSTbI7M5hHUm3PIAOtt3UxzsQ83dl-ZVHKrTIME,1215
+pexafy/cli.py,sha256=dYbtULAKddorxzDO_KhyHkf3298zoAX3og3AlQGEnGw,2969
+pexafy/client.py,sha256=9qw30J-k-6cJRi4YJFptnh0HxnKmH_cqdoiLfO7MjaE,16854
+pexafy/errors.py,sha256=_jAPl0kinUemEA2l6wvU5w8HpThSjXz27mIX5KtGi7g,2653
+pexafy/models.py,sha256=e7UI469qcsHjO84hq73DaWrh0UVJxqA4UqETaBoaCqI,7008
+pexafy-0.1.0.dist-info/METADATA,sha256=G0iX9c77pUcQe9N4AzFT2fAp0KeTo_ddoF1MJdKb2lM,5835
+pexafy-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pexafy-0.1.0.dist-info/entry_points.txt,sha256=Q5qXAXgnc6P2uzdUcC7qmfgX6oKWALSlVzMH0RZ_gJk,43
+pexafy-0.1.0.dist-info/licenses/LICENSE,sha256=witmea33bfrUIQwxv9UzvIkCJKVWehbqCb9mKF1NNeI,1072
+pexafy-0.1.0.dist-info/RECORD,,

pexafy-0.1.0.dist-info/WHEEL

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

pexafy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pexafy = pexafy.cli:main

pexafy-0.1.0.dist-info/licenses/LICENSE

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