festivalapi 0.2.0__py3-none-any.whl

festivalapi/__init__.py

@@ -0,0 +1,32 @@
+"""Festival API Python Client
+
+A lightweight Python client for the Festival API.
+
+    pip install festivalapi
+
+Usage:
+    from festivalapi import FestivalAPI
+
+    client = FestivalAPI("fda_your_api_key")
+
+    # Search festivals
+    festivals = client.festivals.list(category="short_film")
+
+    # Get festival detail
+    festival = client.festivals.get(1)
+
+    # Get festival roster
+    roster = client.festivals.roster(1)
+
+    # Get scored festivals
+    scored = client.festivals.scored(min_score=70)
+
+    # Health check (no auth)
+    health = client.health()
+"""
+
+from .client import FestivalAPI
+from .exceptions import FestivalAPIError, AuthenticationError, InsufficientCreditsError
+
+__all__ = ["FestivalAPI", "FestivalAPIError", "AuthenticationError", "InsufficientCreditsError"]
+__version__ = "0.2.0"

festivalapi/client.py

@@ -0,0 +1,165 @@
+import urllib.request
+import urllib.error
+import urllib.parse
+import json
+import os
+from typing import Optional, Dict, Any, List
+from .exceptions import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    FestivalAPIError,
+)
+
+
+class FestivalAPI:
+    """Client for the Festival API.
+
+    Args:
+        api_key: Your Festival API key (starts with 'fda_').
+        base_url: Override the API base URL. Defaults to production.
+        timeout: Request timeout in seconds. Default 30.
+    """
+
+    BASE_URL = "https://festivalapi.com/v1"
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        self.api_key = api_key or os.environ.get("FESTIVALAPI_KEY")
+        self.base_url = base_url or self.BASE_URL
+        self.timeout = timeout
+        self.festivals = FestivalEndpoints(self)
+        self.health = lambda: self._get("/health", auth_required=False)
+        self.categories = lambda: self._get("/categories", auth_required=False)
+
+    def _auth_headers(self) -> Dict[str, str]:
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        auth_required: bool = True,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        headers = {"Accept": "application/json", "User-Agent": "festivalapi-python/0.1.0"}
+        if auth_required:
+            if not self.api_key:
+                raise AuthenticationError(
+                    "API key required. Pass api_key='fda_...' to FestivalAPI(), "
+                    "or set FESTIVALAPI_KEY environment variable."
+                )
+            headers.update(self._auth_headers())
+
+        if params:
+            filtered = {k: v for k, v in params.items() if v is not None}
+            if filtered:
+                url = f"{url}?{urllib.parse.urlencode(filtered)}"
+
+        req = urllib.request.Request(url, method=method, headers=headers)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            body = {}
+            try:
+                body = json.loads(e.read().decode("utf-8"))
+            except Exception:
+                pass
+            self._raise_error(e.code, body)
+            return {}  # unreachable, satisfies type checker
+        except urllib.error.URLError as e:
+            raise FestivalAPIError(f"Connection error: {e.reason}") from e
+
+    def _get(
+        self, path: str, params=None, auth_required=True
+    ) -> Dict[str, Any]:
+        return self._request("GET", path, params, auth_required)
+
+    @staticmethod
+    def _raise_error(status: int, body: dict):
+        detail = body.get("detail") or body.get("message", "")
+        if status == 401:
+            raise AuthenticationError(detail or "Invalid or missing API key.")
+        if status == 402:
+            required = body.get("required", "?")
+            balance = body.get("balance", "?")
+            msg = f"Insufficient credits. Need {required}, have {balance}."
+            raise InsufficientCreditsError(msg)
+        if status == 404:
+            raise NotFoundError(detail or "Resource not found.")
+        if status == 429:
+            raise RateLimitError(detail or "Too many requests.")
+        if 500 <= status < 600:
+            raise ServerError(detail or f"Server error (HTTP {status}).")
+        raise FestivalAPIError(f"HTTP {status}: {detail or 'Unknown error'}")
+
+
+class FestivalEndpoints:
+    """Access festival-related endpoints."""
+
+    def __init__(self, client: FestivalAPI):
+        self._client = client
+
+    def list(
+        self,
+        category: Optional[str] = None,
+        country: Optional[str] = None,
+        genre: Optional[str] = None,
+        deadline_before: Optional[str] = None,
+        fee_max: Optional[int] = None,
+        q: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """List festivals with optional filters.
+
+        Args:
+            category: Festival category (e.g. short_film, feature, documentary).
+            country: Country code (e.g. US, UK, CA).
+            genre: Accepted genre (e.g. drama, comedy, horror).
+            deadline_before: Filter by submission deadline before date (YYYY-MM-DD).
+            fee_max: Maximum submission fee in USD.
+            q: Full-text search on festival name.
+        """
+        return self._client._get("/festivals", {
+            "category": category,
+            "country": country,
+            "genre": genre,
+            "deadline_before": deadline_before,
+            "fee_max": fee_max,
+            "q": q,
+        })
+
+    def get(self, festival_id: int) -> Dict[str, Any]:
+        """Get full detail for a single festival."""
+        return self._client._get(f"/festivals/{festival_id}")
+
+    def roster(self, festival_id: int) -> Dict[str, Any]:
+        """Get the submission roster for a festival."""
+        return self._client._get(f"/festivals/{festival_id}/roster")
+
+    def scored(
+        self,
+        category: Optional[str] = None,
+        min_score: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Get festivals ranked by Festival Score.
+
+        Args:
+            category: Filter by category.
+            min_score: Minimum score threshold (0-100).
+            limit: Max results.
+        """
+        return self._client._get("/festivals/scored", {
+            "category": category,
+            "min_score": min_score,
+            "limit": limit,
+        })

festivalapi/exceptions.py

@@ -0,0 +1,28 @@
+class FestivalAPIError(Exception):
+    """Base exception for Festival API errors."""
+    pass
+
+
+class AuthenticationError(FestivalAPIError):
+    """Invalid or missing API key (HTTP 401)."""
+    pass
+
+
+class InsufficientCreditsError(FestivalAPIError):
+    """Not enough credits for the request (HTTP 402)."""
+    pass
+
+
+class NotFoundError(FestivalAPIError):
+    """Resource not found (HTTP 404)."""
+    pass
+
+
+class RateLimitError(FestivalAPIError):
+    """Rate limit exceeded (HTTP 429)."""
+    pass
+
+
+class ServerError(FestivalAPIError):
+    """Server-side error (HTTP 5xx)."""
+    pass

festivalapi-0.2.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: festivalapi
+Version: 0.2.0
+Summary: Python client for the Festival API — film festival data for developers
+Author-email: Festival API <hello@festivalapi.com>
+License-Expression: MIT
+Project-URL: Homepage, https://festivalapi.com
+Project-URL: Documentation, https://festivalapi.com/docs
+Project-URL: Repository, https://github.com/rv888/festivalapi_com
+Project-URL: Issues, https://github.com/rv888/festivalapi_com/issues
+Keywords: film-festival,festival,submissions,film,api
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Festival API — Python Client
+
+Client library for the [Festival API](https://festivalapi.com).
+
+```bash
+pip install festivalapi
+```
+
+## Usage
+
+```python
+from festivalapi import FestivalAPI
+
+client = FestivalAPI("fda_your_api_key")
+
+# Search festivals
+festivals = client.festivals.list(category="short_film")
+
+# Get festival detail
+festival = client.festivals.get(1)
+
+# Get festival roster
+roster = client.festivals.roster(1)
+
+# Get scored festivals
+scored = client.festivals.scored(min_score=70)
+
+# List categories (no auth required)
+categories = client.categories()
+
+# Health check (no auth)
+client.health()
+```
+
+## API Key
+
+Sign up at [festivalapi.com](https://festivalapi.com) to get your API key. You can also set the `FESTIVALAPI_KEY` environment variable.
+
+## Error Handling
+
+```python
+from festivalapi import FestivalAPI, NotFoundError, InsufficientCreditsError
+
+client = FestivalAPI("fda_your_api_key")
+
+try:
+    festival = client.festivals.get(999999)
+except NotFoundError:
+    print("Festival not found")
+except InsufficientCreditsError as e:
+    print(f"Need more credits: {e}")
+```
+
+## Requirements
+
+- Python 3.9+
+- Zero dependencies (uses only stdlib `urllib`)
+
+## License
+
+MIT

festivalapi-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+festivalapi/__init__.py,sha256=PAI40RcrYTKGuM081yp8fz-MvQBUh6tlSr04DqqZoxo,805
+festivalapi/client.py,sha256=LeFJ-p2wY8eXxC5zk0O3Ap7RjVYtRQJxPHwl0KbZiL0,5724
+festivalapi/exceptions.py,sha256=YJFlQAsfxs4IdMVrj0hwifCmnP8-toi1Z8L6PeZTc8w,589
+festivalapi-0.2.0.dist-info/METADATA,sha256=77afAFusAX7XVFYnTXo3wouLRB0mWlrrndAf59sMeKs,2194
+festivalapi-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+festivalapi-0.2.0.dist-info/top_level.txt,sha256=kqEdtGIbJ43qJVla03SfVkMbM5ccJQdtwZKJwrRxWfk,12
+festivalapi-0.2.0.dist-info/RECORD,,

festivalapi-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

festivalapi-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+festivalapi