pySplash.py 1.0.0__py3-none-any.whl

pySplash/base.py

@@ -0,0 +1,142 @@
+"""Shared utilities for sync and async API clients."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from typing import Any
+
+from .errors import PySplashError
+
+logger = logging.getLogger("pySplash.py")
+
+
+class PySplashBase:
+    """Shared validation, error handling, and URL construction for both sync and async clients."""
+
+    @staticmethod
+    def _compute_hash(value: str) -> str:
+        return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+    @staticmethod
+    def _validate_required(value: Any, field_name: str) -> None:
+        if value is None or value == "":
+            if field_name == "id":
+                message = "Parameter : id is required!"
+            elif field_name == "query":
+                message = "Parameter : query is missing!"
+            else:
+                message = f"Parameter : {field_name} is required and cannot be empty!"
+            raise PySplashError(message)
+
+    @staticmethod
+    def _validate_supported_value(value: str | None, allowed_values: list, field_name: str) -> None:
+        if value is not None and value not in allowed_values:
+            raise PySplashError(f"Parameter : {field_name} has an unsupported value!")
+
+    @staticmethod
+    def _validate_int(value: Any, field_name: str, minimum: int = 1, maximum: int | None = None) -> None:
+        if value is not None:
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise PySplashError(f"Parameter : {field_name} must be an integer!")
+            if value < minimum:
+                raise PySplashError(f"Parameter : {field_name} must be >= {minimum}!")
+            if maximum is not None and value > maximum:
+                raise PySplashError(f"Parameter : {field_name} must be <= {maximum}!")
+
+    @staticmethod
+    def _validate_bool(value: Any, field_name: str) -> None:
+        if value is not None and not isinstance(value, bool):
+            raise PySplashError(f"Parameter : {field_name} must be a boolean or optional!")
+
+    @staticmethod
+    def _build_query_parameters(params: dict[str, Any]) -> dict[str, Any]:
+        return {k: v for k, v in params.items() if v is not None and v != ""}
+
+    @staticmethod
+    def _build_url(base: str, path: str, **replacements: str) -> str:
+        url = base + path
+        for key, value in replacements.items():
+            url = url.replace(f":{key}", value)
+        return url
+
+    @staticmethod
+    def _handle_response_status(data: Any, status: int, status_text: str) -> Any:
+        if status == 204:
+            logger.debug("204 No Content - resource deleted")
+            return {"status": status, "statusText": status_text, "message": "Content Deleted"}
+        if status >= 400:
+            logger.warning("%d %s", status, status_text)
+            raise PySplashError(
+                f"HTTP {status} {status_text}",
+                status_code=status,
+                status_text=status_text,
+            )
+        return data
+
+    @staticmethod
+    def _create_pysplash_error(error: Exception) -> PySplashError:
+        if isinstance(error, PySplashError):
+            return error
+        status_code = getattr(getattr(error, "response", None), "status_code", None)
+        status_text = getattr(
+            getattr(error, "response", None),
+            "reason",
+            getattr(getattr(error, "response", None), "reason_phrase", None),
+        )
+        return PySplashError(
+            str(error),
+            status_code=status_code,
+            status_text=status_text,
+            cause=error,
+        )
+
+    @staticmethod
+    def _default_headers(bearer_token: str | None = None, access_key: str | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {
+            "Content-type": "application/json",
+            "X-Requested-With": "PySplash.py",
+        }
+        if bearer_token:
+            headers["Authorization"] = f"Bearer {bearer_token}"
+            headers["X-PySplash-Header"] = PySplashBase._compute_hash(bearer_token)
+        elif access_key:
+            headers["Authorization"] = f"Client-ID {access_key}"
+            headers["X-PySplash-Header"] = PySplashBase._compute_hash(access_key)
+        return headers
+
+    @staticmethod
+    def _extract_location_params(location: dict[str, Any] | None) -> dict[str, Any]:
+        if not location:
+            return {}
+        result: dict[str, Any] = {}
+        mapping = {
+            "latitude": "location[latitude]",
+            "longitude": "location[longitude]",
+            "name": "location[name]",
+            "city": "location[city]",
+            "country": "location[country]",
+            "confidential": "location[confidential]",
+        }
+        for key, param_name in mapping.items():
+            if key in location and location[key] is not None:
+                result[param_name] = location[key]
+        return result
+
+    @staticmethod
+    def _extract_exif_params(exif: dict[str, Any] | None) -> dict[str, Any]:
+        if not exif:
+            return {}
+        result: dict[str, Any] = {}
+        mapping = {
+            "make": "exif[make]",
+            "model": "exif[model]",
+            "exposure_time": "exif[exposure_time]",
+            "aperture_value": "exif[aperture_value]",
+            "focal_length": "exif[focal_length]",
+            "iso_speed_ratings": "exif[iso_speed_ratings]",
+        }
+        for key, param_name in mapping.items():
+            if key in exif and exif[key] is not None:
+                result[param_name] = exif[key]
+        return result

pySplash/config.py

@@ -0,0 +1,55 @@
+"""Configuration for pySplash.py - URL templates and default HTTP settings."""
+
+API_LOCATION = "https://api.unsplash.com/"
+BEARER_TOKEN_URL = "https://unsplash.com/oauth/token"
+
+URL_CONFIG = {
+    "API_LOCATION": API_LOCATION,
+    "BEARER_TOKEN_URL": BEARER_TOKEN_URL,
+    "USERS_PUBLIC_PROFILE": "users/",
+    "USERS_PORTFOLIO": "users/:username/portfolio",
+    "USERS_PHOTOS": "users/:username/photos",
+    "USERS_LIKED_PHOTOS": "users/:username/likes",
+    "USERS_COLLECTIONS": "users/:username/collections",
+    "USERS_STATISTICS": "users/:username/statistics",
+    "LIST_PHOTOS": "photos",
+    "LIST_CURATED_PHOTOS": "photos/curated",
+    "GET_A_PHOTO": "photos/:id",
+    "GET_A_RANDOM_PHOTO": "photos/random",
+    "GET_A_PHOTO_STATISTICS": "photos/:id/statistics",
+    "GET_A_PHOTO_DOWNLOAD_LINK": "photos/:id/download",
+    "UPDATE_A_PHOTO": "photos/:id",
+    "LIKE_A_PHOTO": "photos/:id/like",
+    "UNLIKE_A_PHOTO": "photos/:id/like",
+    "SEARCH_PHOTOS": "search/photos",
+    "SEARCH_COLLECTIONS": "search/collections",
+    "SEARCH_USERS": "search/users",
+    "CURRENT_USER_PROFILE": "me",
+    "UPDATE_CURRENT_USER_PROFILE": "me",
+    "STATS_TOTALS": "stats/total",
+    "STATS_MONTH": "stats/month",
+    "LIST_COLLECTIONS": "collections",
+    "LIST_FEATURED_COLLECTIONS": "collections/featured",
+    "LIST_CURATED_COLLECTIONS": "collections/curated",
+    "GET_COLLECTION": "collections/:id",
+    "GET_CURATED_COLLECTION": "collections/curated/:id",
+    "GET_COLLECTION_PHOTOS": "collections/:id/photos",
+    "GET_CURATED_COLLECTION_PHOTOS": "collections/curated/:id/photos",
+    "LIST_RELATED_COLLECTION": "collections/:id/related",
+    "CREATE_NEW_COLLECTION": "collections",
+    "UPDATE_EXISTING_COLLECTION": "collections/:id",
+    "DELETE_COLLECTION": "collections/:id",
+    "ADD_PHOTO_TO_COLLECTION": "collections/:collection_id/add",
+    "REMOVE_PHOTO_FROM_COLLECTION": "collections/:collection_id/remove",
+}
+
+DEFAULT_TIMEOUT = 10
+DEFAULT_RETRIES = 2
+DEFAULT_RETRY_DELAY = 0.1
+DEFAULT_HEADERS = {
+    "Content-type": "application/json",
+    "X-Requested-With": "PySplash.py",
+}
+
+AVAILABLE_ORDERS = ["latest", "oldest", "popular"]
+AVAILABLE_ORIENTATIONS = ["landscape", "portrait", "squarish"]

pySplash/errors.py

@@ -0,0 +1,30 @@
+"""Custom exception class for pySplash.py errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class PySplashError(Exception):
+    """Exception raised by pySplash.py for API and validation errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int | None = None,
+        status_text: str | None = None,
+        cause: Any | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.name = "PySplashError"
+        self.status_code = status_code
+        self.statusText = status_text
+        self.cause = cause
+
+    def __repr__(self) -> str:
+        parts = [f"PySplashError({self.args[0]!r}"]
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code}")
+        if self.statusText is not None:
+            parts.append(f"status_text={self.statusText!r}")
+        return ", ".join(parts) + ")"

pySplash/http_client.py

@@ -0,0 +1,97 @@
+"""Synchronous HTTP client with retry support using requests."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import requests
+
+from .config import DEFAULT_HEADERS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY, DEFAULT_TIMEOUT
+from .errors import PySplashError
+
+logger = logging.getLogger("pySplash.py")
+
+
+class HttpResponse:
+    """Wrapper around requests.Response to provide a uniform interface."""
+
+    def __init__(self, response: requests.Response) -> None:
+        self.status: int = response.status_code
+        self.statusText: str = response.reason or ""
+        try:
+            self.data: Any = response.json() if response.content else None
+        except ValueError:
+            self.data = response.text or None
+
+    def raise_for_status(self) -> None:
+        if self.status >= 400:
+            raise PySplashError(
+                f"HTTP {self.status} {self.statusText}",
+                status_code=self.status,
+                status_text=self.statusText,
+            )
+
+
+class HttpClient:
+    """Sync HTTP client with session reuse, retry logic, and error handling."""
+
+    def __init__(
+        self,
+        headers: dict[str, str] | None = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+    ) -> None:
+        self._session = requests.Session()
+        self._session.headers.update(headers or DEFAULT_HEADERS)
+        self.timeout = timeout
+        self.retries = retries
+        self.retry_delay = retry_delay
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def make_request(
+        self,
+        url: str,
+        method: str,
+        query_parameters: dict[str, Any] | None = None,
+        body: Any | None = None,
+    ) -> HttpResponse:
+        if not url:
+            raise ValueError("URL required")
+
+        last_error: Exception | None = None
+
+        for attempt in range(self.retries + 1):
+            try:
+                logger.debug("%s %s (attempt %d/%d)", method, url, attempt + 1, self.retries + 1)
+                response = self._session.request(
+                    method=method or "get",
+                    url=url,
+                    params=query_parameters or {},
+                    json=body,
+                    timeout=self.timeout,
+                    allow_redirects=True,
+                )
+                result = HttpResponse(response)
+                if result.status >= 400:
+                    result.raise_for_status()
+                return result
+            except PySplashError:
+                raise
+            except Exception as exc:
+                last_error = exc
+                logger.warning("Request failed (attempt %d/%d): %s", attempt + 1, self.retries + 1, exc)
+                if attempt < self.retries and self.retry_delay > 0:
+                    time.sleep(self.retry_delay)
+
+        raise last_error  # type: ignore[misc]

pySplash/http_client_async.py

@@ -0,0 +1,107 @@
+"""Asynchronous HTTP client with retry support using httpx."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+import httpx
+
+from .config import DEFAULT_HEADERS, DEFAULT_RETRIES, DEFAULT_RETRY_DELAY, DEFAULT_TIMEOUT
+from .errors import PySplashError
+
+logger = logging.getLogger("pySplash.py")
+
+
+class AsyncHttpResponse:
+    """Wrapper around httpx.Response to provide a uniform interface."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.status: int = response.status_code
+        self.statusText: str = response.reason_phrase or ""
+        try:
+            self.data: Any = response.json() if response.content else None
+        except ValueError:
+            self.data = response.text or None
+
+    def raise_for_status(self) -> None:
+        if self.status >= 400:
+            raise PySplashError(
+                f"HTTP {self.status} {self.statusText}",
+                status_code=self.status,
+                status_text=self.statusText,
+            )
+
+
+class AsyncHttpClient:
+    """Async HTTP client with connection pooling, retry logic, and error handling."""
+
+    def __init__(
+        self,
+        headers: dict[str, str] | None = None,
+        timeout: int = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+    ) -> None:
+        self._headers = headers or DEFAULT_HEADERS
+        self.timeout = timeout
+        self.retries = retries
+        self.retry_delay = retry_delay
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(
+                headers=self._headers,
+                timeout=self.timeout,
+                max_redirects=5,
+            )
+        return self._client
+
+    async def close(self) -> None:
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> AsyncHttpClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def make_request(
+        self,
+        url: str,
+        method: str,
+        query_parameters: dict[str, Any] | None = None,
+        body: Any | None = None,
+    ) -> AsyncHttpResponse:
+        if not url:
+            raise ValueError("URL required")
+
+        last_error: Exception | None = None
+
+        for attempt in range(self.retries + 1):
+            try:
+                logger.debug("%s %s (attempt %d/%d)", method, url, attempt + 1, self.retries + 1)
+                client = self._get_client()
+                response = await client.request(
+                    method=method or "get",
+                    url=url,
+                    params=query_parameters or {},
+                    json=body,
+                )
+                result = AsyncHttpResponse(response)
+                if result.status >= 400:
+                    result.raise_for_status()
+                return result
+            except PySplashError:
+                raise
+            except Exception as exc:
+                last_error = exc
+                logger.warning("Request failed (attempt %d/%d): %s", attempt + 1, self.retries + 1, exc)
+                if attempt < self.retries and self.retry_delay > 0:
+                    await asyncio.sleep(self.retry_delay)
+
+        raise last_error  # type: ignore[misc]

pySplash/models.py

@@ -0,0 +1,173 @@
+"""Typed response models for the Unsplash API."""
+
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+
+class UserLinks(TypedDict, total=False):
+    self: str
+    html: str
+    photos: str
+    likes: str
+    portfolio: str
+
+
+class UserUrls(TypedDict, total=False):
+    raw: str
+    full: str
+    regular: str
+    small: str
+    medium: str
+    large: str
+    profile_image: str
+
+
+class UserProfileImages(TypedDict, total=False):
+    small: str
+    medium: str
+    large: str
+
+
+class User(TypedDict, total=False):
+    id: str
+    username: str
+    name: str
+    first_name: str
+    last_name: str
+    instagram_username: str
+    total_likes: int
+    total_photos: int
+    total_collections: int
+    followers_count: int
+    following_count: int
+    downloads: int
+    bio: str | None
+    location: str | None
+    total_promoted_photos: int
+    followers: int
+    following: int
+    profile_image: UserProfileImages
+    social: dict[str, Any]
+    links: UserLinks
+    tags: list[dict[str, Any]]
+    photos: list[dict[str, Any]]
+    portfolio_url: str | None
+    updated_at: str
+    badge: dict[str, Any]
+    user_links: UserLinks
+
+
+class UserPortfolio(TypedDict, total=False):
+    id: str
+    title: str
+    url: str
+    published_at: str
+    updated_at: str
+    links: dict[str, str]
+
+
+class UserStatistics(TypedDict, total=False):
+    id: str
+    username: str
+    downloads: dict[str, Any]
+    views: dict[str, Any]
+    likes: dict[str, Any]
+    historical: dict[str, Any]
+
+
+class Urls(TypedDict, total=False):
+    raw: str
+    full: str
+    regular: str
+    small: str
+    thumb: str
+    small_s3: str
+
+
+class PhotoLinks(TypedDict, total=False):
+    self: str
+    html: str
+    download: str
+    download_location: str
+
+
+class Photo(TypedDict, total=False):
+    id: str
+    slug: str
+    created_at: str
+    updated_at: str
+    promoted_at: str | None
+    width: int
+    height: int
+    color: str
+    blur_hash: str
+    description: str | None
+    alt_description: str | None
+    breadcrumbs: list[dict[str, Any]]
+    urls: Urls
+    links: PhotoLinks
+    likes: int
+    liked_by_user: bool
+    current_user_collections: list[dict[str, Any]]
+    user: User
+    exif: dict[str, Any]
+    location: dict[str, Any]
+    views: int
+    downloads: int
+    related_collections: dict[str, Any]
+    tags: list[dict[str, Any]]
+    sponsorship: dict[str, Any] | None
+    topic_submissions: dict[str, Any]
+    user_links: UserLinks
+
+
+class PhotoStatistics(TypedDict, total=False):
+    id: str
+    downloads: dict[str, Any]
+    views: dict[str, Any]
+    likes: dict[str, Any]
+    historical: dict[str, Any]
+
+
+class CollectionLinks(TypedDict, total=False):
+    self: str
+    html: str
+    photos: str
+    related: str
+
+
+class Collection(TypedDict, total=False):
+    id: str
+    title: str
+    description: str | None
+    published_at: str
+    updated_at: str
+    curated: bool
+    featured: bool
+    total_photos: int
+    private: bool
+    share_key: str
+    tags: list[dict[str, Any]]
+    links: CollectionLinks
+    user: User
+    cover_photo: Photo
+
+
+class SearchResult(TypedDict, total=False):
+    total: int
+    total_pages: int
+    results: list[dict[str, Any]]
+
+
+class BearerTokenResponse(TypedDict, total=False):
+    access_token: str
+    token_type: str
+    scope: str
+    created_at: int
+
+
+class DeleteResponse(TypedDict, total=False):
+    status: int
+    statusText: str
+    message: str