ticketfairy 0.1.0__tar.gz

ticketfairy-0.1.0/.gitignore

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

ticketfairy-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [0.1.0]
+
+- First release.
+- Public event listings: `events.list` and `events.iter`.
+- Organiser API: `events.create` (with an `Idempotency-Key`) and `events.sales`.
+- Setup copies: `setup_copy.start`, `setup_copy.get` and `setup_copy.wait`.
+- Typed errors and a retry policy that never repeats a write the API cannot tell apart from a new one.

ticketfairy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Ticket Fairy, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ticketfairy-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: ticketfairy
+Version: 0.1.0
+Summary: Python client for the Ticket Fairy API: public event listings, organiser events, sales and setup copies
+Project-URL: Homepage, https://www.ticketfairy.com/developers
+Project-URL: Documentation, https://www.ticketfairy.com/developers
+Project-URL: Source, https://github.com/theticketfairy/ticketfairy-cli/tree/main/python
+Project-URL: Issues, https://github.com/theticketfairy/ticketfairy-cli/issues
+Project-URL: Changelog, https://github.com/theticketfairy/ticketfairy-cli/blob/main/python/CHANGELOG.md
+Author-email: Ticket Fairy <support@theticketfairy.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,events,sdk,ticketfairy,ticketing,tickets
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# ticketfairy (Python)
+
+The Python client for the [Ticket Fairy](https://www.ticketfairy.com) API. Use it to:
+
+- read public event listings;
+- create events for a brand you manage;
+- read an event's sales;
+- copy another event's setup into an event, as a background job you can follow.
+
+It has no dependencies outside the Python standard library and needs Python 3.9 or later.
+
+```sh
+pip install ticketfairy
+```
+
+The same API is available from Node.js and the command line in the [`ticketfairy` npm package](https://www.npmjs.com/package/ticketfairy).
+
+## Public event listings
+
+The public listing needs no account.
+
+```python
+from ticketfairy import TicketFairy
+
+tf = TicketFairy()
+
+page = tf.events.list(country="GB", date_from="2026-11-01", size=50)
+for event in page["events"]:
+    print(event["displayName"], event["startDate"], event["url"])
+
+# Every matching event, page after page:
+for event in tf.events.iter(search="jazz", limit=200):
+    print(event["displayName"])
+```
+
+`list` takes these filters:
+
+| Filter | Meaning |
+| --- | --- |
+| `search` | Words to match against event names and descriptions |
+| `country` | An ISO 3166-1 alpha-2 country code |
+| `state` | A region, state or province |
+| `date_from`, `date_to` | Dates as `YYYY-MM-DD` |
+| `section_type` | The listing section to read |
+| `timezone` | An IANA timezone for the date window |
+| `sort` | `created_at`, `updated_at` or `start_date` |
+| `order` | `asc` or `desc` |
+| `brand_id` | Only events from this brand |
+| `include` | The kinds of event to include |
+| `size` | Events per page, up to 200 |
+
+`iter` takes the same filters and follows `pagination.nextCursor` for you.
+
+## Organiser API
+
+The organiser API acts as you. To get a token:
+
+1. Create a personal access token in your Ticket Fairy account settings.
+2. Pass it to the client, or set it in the `TICKETFAIRY_TOKEN` environment variable.
+
+The token can do what your roles allow, and nothing more.
+
+```python
+from ticketfairy import TicketFairy
+
+org = TicketFairy(token="...")  # or set TICKETFAIRY_TOKEN
+
+# Create a draft event for a brand where you are admin or owner.
+event = org.events.create(
+    brand_id=1234,
+    attributes={"displayName": "Summer Festival 2027", "slug": "summer-festival-2027", "flagDraft": True},
+)
+print(event["id"])
+
+# Tickets sold and revenue, by day and by ticket type and release.
+sales = org.events.sales(event["id"])
+```
+
+`create` sends an `Idempotency-Key` with each request. If a network error happens, a retry cannot create a second event.
+
+### Copy another event's setup
+
+The copy runs in the background. `start` returns at once with the run. `wait` follows the run until it stops.
+
+```python
+run = org.setup_copy.start(new_event_id, source_event_id=last_year_event_id)
+run = org.setup_copy.wait(new_event_id, run, timeout=600)
+
+print(run["status"])  # done, partly_done or failed
+for part in run["parts"]:
+    print(part)
+```
+
+How a copy works:
+
+- Both events must belong to the same brand.
+- You need the owner, admin or producer role on both events.
+- Forms need the owner or admin role.
+- Leave out `parts` to copy everything, or name the parts you want.
+
+`start` sends a `request_key`. Sending the same key and the same choice of parts again returns the same run, so a retried start does not copy twice.
+
+## Errors
+
+Every error is a `TicketFairyError`. Each error has these attributes:
+
+- `status`: the HTTP status.
+- `code`: a stable code, when the API sends one.
+- `message`: the API's own explanation.
+- `hint`: what to do next, when the API says.
+- `body`: the response.
+
+| Error | When |
+| --- | --- |
+| `AuthenticationError` | The token is missing, expired or revoked |
+| `PermissionDeniedError` | Your role does not allow this |
+| `NotFoundError` | No such event or run |
+| `ValidationError` | A parameter or field is not valid; the message names it |
+| `ConflictError` | A key was already used for something else, or a copy is already running |
+| `RateLimitedError` | Too many requests; wait `retry_after` seconds |
+| `ServerError` | Ticket Fairy could not complete the request |
+| `NetworkError` | No response arrived |
+| `SetupCopyTimeoutError` | `wait` gave up while the copy was still running; the copy carries on |
+
+### When the client retries
+
+Reads are retried after a rate limit, a server error or a network error. For a rate limit, the client first waits for the `Retry-After` time.
+
+Writes are retried in the same cases only when the API can tell a repeat from a new request. That is the case for `create`, which sends an `Idempotency-Key`, and for `setup_copy.start`, which sends a `request_key`. A repeat sends the same key, so it returns the first attempt's result rather than doing the work twice.
+
+When the retries run out, the error is raised. A `RateLimitedError` carries `retry_after`.
+
+## API reference
+
+The client follows these OpenAPI documents:
+
+- [Public listing](https://www.ticketfairy.com/api/v1/openapi.json)
+- [Organiser API](https://www.theticketfairy.com/api/openapi.json)
+
+The developer guide is at [ticketfairy.com/developers](https://www.ticketfairy.com/developers).

ticketfairy-0.1.0/README.md

@@ -0,0 +1,140 @@
+# ticketfairy (Python)
+
+The Python client for the [Ticket Fairy](https://www.ticketfairy.com) API. Use it to:
+
+- read public event listings;
+- create events for a brand you manage;
+- read an event's sales;
+- copy another event's setup into an event, as a background job you can follow.
+
+It has no dependencies outside the Python standard library and needs Python 3.9 or later.
+
+```sh
+pip install ticketfairy
+```
+
+The same API is available from Node.js and the command line in the [`ticketfairy` npm package](https://www.npmjs.com/package/ticketfairy).
+
+## Public event listings
+
+The public listing needs no account.
+
+```python
+from ticketfairy import TicketFairy
+
+tf = TicketFairy()
+
+page = tf.events.list(country="GB", date_from="2026-11-01", size=50)
+for event in page["events"]:
+    print(event["displayName"], event["startDate"], event["url"])
+
+# Every matching event, page after page:
+for event in tf.events.iter(search="jazz", limit=200):
+    print(event["displayName"])
+```
+
+`list` takes these filters:
+
+| Filter | Meaning |
+| --- | --- |
+| `search` | Words to match against event names and descriptions |
+| `country` | An ISO 3166-1 alpha-2 country code |
+| `state` | A region, state or province |
+| `date_from`, `date_to` | Dates as `YYYY-MM-DD` |
+| `section_type` | The listing section to read |
+| `timezone` | An IANA timezone for the date window |
+| `sort` | `created_at`, `updated_at` or `start_date` |
+| `order` | `asc` or `desc` |
+| `brand_id` | Only events from this brand |
+| `include` | The kinds of event to include |
+| `size` | Events per page, up to 200 |
+
+`iter` takes the same filters and follows `pagination.nextCursor` for you.
+
+## Organiser API
+
+The organiser API acts as you. To get a token:
+
+1. Create a personal access token in your Ticket Fairy account settings.
+2. Pass it to the client, or set it in the `TICKETFAIRY_TOKEN` environment variable.
+
+The token can do what your roles allow, and nothing more.
+
+```python
+from ticketfairy import TicketFairy
+
+org = TicketFairy(token="...")  # or set TICKETFAIRY_TOKEN
+
+# Create a draft event for a brand where you are admin or owner.
+event = org.events.create(
+    brand_id=1234,
+    attributes={"displayName": "Summer Festival 2027", "slug": "summer-festival-2027", "flagDraft": True},
+)
+print(event["id"])
+
+# Tickets sold and revenue, by day and by ticket type and release.
+sales = org.events.sales(event["id"])
+```
+
+`create` sends an `Idempotency-Key` with each request. If a network error happens, a retry cannot create a second event.
+
+### Copy another event's setup
+
+The copy runs in the background. `start` returns at once with the run. `wait` follows the run until it stops.
+
+```python
+run = org.setup_copy.start(new_event_id, source_event_id=last_year_event_id)
+run = org.setup_copy.wait(new_event_id, run, timeout=600)
+
+print(run["status"])  # done, partly_done or failed
+for part in run["parts"]:
+    print(part)
+```
+
+How a copy works:
+
+- Both events must belong to the same brand.
+- You need the owner, admin or producer role on both events.
+- Forms need the owner or admin role.
+- Leave out `parts` to copy everything, or name the parts you want.
+
+`start` sends a `request_key`. Sending the same key and the same choice of parts again returns the same run, so a retried start does not copy twice.
+
+## Errors
+
+Every error is a `TicketFairyError`. Each error has these attributes:
+
+- `status`: the HTTP status.
+- `code`: a stable code, when the API sends one.
+- `message`: the API's own explanation.
+- `hint`: what to do next, when the API says.
+- `body`: the response.
+
+| Error | When |
+| --- | --- |
+| `AuthenticationError` | The token is missing, expired or revoked |
+| `PermissionDeniedError` | Your role does not allow this |
+| `NotFoundError` | No such event or run |
+| `ValidationError` | A parameter or field is not valid; the message names it |
+| `ConflictError` | A key was already used for something else, or a copy is already running |
+| `RateLimitedError` | Too many requests; wait `retry_after` seconds |
+| `ServerError` | Ticket Fairy could not complete the request |
+| `NetworkError` | No response arrived |
+| `SetupCopyTimeoutError` | `wait` gave up while the copy was still running; the copy carries on |
+
+### When the client retries
+
+Reads are retried after a rate limit, a server error or a network error. For a rate limit, the client first waits for the `Retry-After` time.
+
+Writes are retried in the same cases only when the API can tell a repeat from a new request. That is the case for `create`, which sends an `Idempotency-Key`, and for `setup_copy.start`, which sends a `request_key`. A repeat sends the same key, so it returns the first attempt's result rather than doing the work twice.
+
+When the retries run out, the error is raised. A `RateLimitedError` carries `retry_after`.
+
+## API reference
+
+The client follows these OpenAPI documents:
+
+- [Public listing](https://www.ticketfairy.com/api/v1/openapi.json)
+- [Organiser API](https://www.theticketfairy.com/api/openapi.json)
+
+The developer guide is at [ticketfairy.com/developers](https://www.ticketfairy.com/developers).

ticketfairy-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ticketfairy"
+dynamic = ["version"]
+description = "Python client for the Ticket Fairy API: public event listings, organiser events, sales and setup copies"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Ticket Fairy", email = "support@theticketfairy.com" }]
+keywords = ["ticketfairy", "events", "tickets", "ticketing", "api", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://www.ticketfairy.com/developers"
+Documentation = "https://www.ticketfairy.com/developers"
+Source = "https://github.com/theticketfairy/ticketfairy-cli/tree/main/python"
+Issues = "https://github.com/theticketfairy/ticketfairy-cli/issues"
+Changelog = "https://github.com/theticketfairy/ticketfairy-cli/blob/main/python/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/ticketfairy/version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ticketfairy"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/ticketfairy", "tests", "README.md", "CHANGELOG.md", "LICENSE"]

ticketfairy-0.1.0/src/ticketfairy/__init__.py

@@ -0,0 +1,58 @@
+"""Python client for the Ticket Fairy API.
+
+    from ticketfairy import TicketFairy
+
+    tf = TicketFairy()                      # public listings need no token
+    for event in tf.events.iter(country="GB", limit=20):
+        print(event["displayName"])
+
+    org = TicketFairy(token="...")          # organiser API
+    run = org.setup_copy.start(123, source_event_id=100)
+    run = org.setup_copy.wait(123, run)
+"""
+
+from .client import (
+    ORGANISER_BASE_URL,
+    PUBLIC_BASE_URL,
+    SALES_SECTIONS,
+    SETUP_COPY_FINAL_STATUSES,
+    Events,
+    SetupCopy,
+    TicketFairy,
+    flatten,
+)
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    NetworkError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitedError,
+    ServerError,
+    SetupCopyTimeoutError,
+    TicketFairyError,
+    ValidationError,
+)
+from .version import __version__
+
+__all__ = [
+    "AuthenticationError",
+    "ConflictError",
+    "Events",
+    "NetworkError",
+    "NotFoundError",
+    "ORGANISER_BASE_URL",
+    "PUBLIC_BASE_URL",
+    "PermissionDeniedError",
+    "RateLimitedError",
+    "SALES_SECTIONS",
+    "SETUP_COPY_FINAL_STATUSES",
+    "ServerError",
+    "SetupCopy",
+    "SetupCopyTimeoutError",
+    "TicketFairy",
+    "TicketFairyError",
+    "ValidationError",
+    "__version__",
+    "flatten",
+]

ticketfairy-0.1.0/src/ticketfairy/_http.py

@@ -0,0 +1,207 @@
+"""HTTP transport: one request, the retry policy and error mapping.
+
+Retries follow the same rule as the ``ticketfairy`` npm package, so a retry
+never runs a write twice:
+
+- A network error or a 5xx is retried only for a request that is safe to
+  repeat: GET, HEAD, OPTIONS, PUT and DELETE, a write that carries an
+  ``Idempotency-Key``, or a write the caller marks as safe (one the server
+  deduplicates by a key in its body).
+- A 429 gets the same rule, after the ``Retry-After`` seconds. A keyed write
+  sent again while its first attempt is still running is answered 429, and
+  waiting then sending the same key returns the first attempt's result.
+"""
+
+from __future__ import annotations
+
+import datetime
+import email.utils
+import http.client
+import json
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Mapping, Optional
+
+from .errors import NetworkError, error_for_status
+
+class _NoRedirects(urllib.request.HTTPRedirectHandler):
+    """The API never redirects. Following one would send the token to another address."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirects)
+
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+
+@dataclass
+class Response:
+    status: int
+    headers: Dict[str, str]
+    body: Any = field(default=None)
+
+    def header(self, name: str) -> Optional[str]:
+        return self.headers.get(name.lower())
+
+
+class Transport:
+    def __init__(
+        self,
+        *,
+        user_agent: str,
+        timeout: float,
+        max_retries: int,
+        max_retry_wait: float,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.user_agent = user_agent
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.max_retry_wait = max_retry_wait
+        self.sleep = sleep
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json_body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        safe_to_repeat: bool = False,
+    ) -> Response:
+        method = method.upper()
+        all_headers = {"User-Agent": self.user_agent, "Accept": "application/json"}
+        all_headers.update(headers or {})
+        data = None
+        if json_body is not None:
+            data = json.dumps(json_body).encode("utf-8")
+            all_headers.setdefault("Content-Type", "application/json")
+        if params:
+            query = urllib.parse.urlencode({k: _query_value(v) for k, v in params.items() if v is not None})
+            if query:
+                url = f"{url}{'&' if '?' in url else '?'}{query}"
+
+        has_key = any(name.lower() == "idempotency-key" for name in all_headers)
+        repeatable = safe_to_repeat or has_key or method in _SAFE_METHODS
+        attempt = 0
+        while True:
+            try:
+                response = self._send(method, url, data, all_headers)
+            except NetworkError:
+                if repeatable and attempt < self.max_retries:
+                    self.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                raise
+
+            # A redirect is not followed (see _NoRedirects), so only 2xx succeeds.
+            if 200 <= response.status < 300:
+                return response
+
+            retry_after = _retry_after(response.header("retry-after"))
+            if (response.status == 429 or response.status >= 500) and repeatable and attempt < self.max_retries:
+                # A Retry-After on a 429 or a load-shedding 503 replaces the backoff.
+                wait = retry_after if retry_after is not None else self._backoff(attempt)
+                self.sleep(min(max(wait, 0.5), self.max_retry_wait))
+                attempt += 1
+                continue
+
+            message, code = _describe(response)
+            raise error_for_status(
+                response.status,
+                message,
+                code=code,
+                body=response.body,
+                request_id=response.header("x-request-id"),
+                retry_after=retry_after,
+            )
+
+    def _send(self, method: str, url: str, data: Optional[bytes], headers: Mapping[str, str]) -> Response:
+        request = urllib.request.Request(url, data=data, method=method, headers=dict(headers))
+        try:
+            with _OPENER.open(request, timeout=self.timeout) as raw:
+                return _response(raw.status, raw.headers, raw.read())
+        except urllib.error.HTTPError as failure:
+            try:
+                with failure:
+                    return _response(failure.code, failure.headers, failure.read())
+            except _TRANSPORT_FAILURES as cut_off:
+                raise _network_error(cut_off) from cut_off
+        except _TRANSPORT_FAILURES as failure:
+            raise _network_error(failure) from failure
+
+    @staticmethod
+    def _backoff(attempt: int) -> float:
+        return float(min(0.5 * (2**attempt), 8.0))
+
+
+# HTTPException covers a body cut off after the headers (IncompleteRead).
+_TRANSPORT_FAILURES = (urllib.error.URLError, http.client.HTTPException, socket.timeout, TimeoutError, ConnectionError)
+
+
+def _network_error(failure: BaseException) -> NetworkError:
+    return NetworkError(f"Could not reach Ticket Fairy: {getattr(failure, 'reason', failure)}")
+
+
+def _response(status: int, headers: Any, raw: bytes) -> Response:
+    lowered = {name.lower(): value for name, value in headers.items()} if headers else {}
+    body: Any = None
+    if raw:
+        text = raw.decode("utf-8", errors="replace")
+        try:
+            body = json.loads(text)
+        except ValueError:
+            body = text
+    return Response(status=status, headers=lowered, body=body)
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _retry_after(value: Optional[str]) -> Optional[float]:
+    """Seconds to wait, from either form of Retry-After: seconds or an HTTP date."""
+    if value is None:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError, IndexError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=datetime.timezone.utc)
+    return max(0.0, (when - datetime.datetime.now(datetime.timezone.utc)).total_seconds())
+
+
+def _describe(response: Response) -> "tuple[str, Optional[str]]":
+    """The API's own message and code from any of its error shapes."""
+    body = response.body
+    message: Optional[str] = None
+    code: Optional[str] = None
+    if isinstance(body, dict):
+        if isinstance(body.get("message"), str):
+            message = body["message"]
+        elif isinstance(body.get("error"), str):
+            message = body["error"]
+        errors = body.get("errors")
+        if message is None and isinstance(errors, list) and errors and isinstance(errors[0], dict):
+            message = errors[0].get("detail") or errors[0].get("title")
+            if isinstance(errors[0].get("code"), str):
+                code = errors[0]["code"]
+        if isinstance(body.get("code"), str):
+            code = body["code"]
+    elif isinstance(body, str) and body.strip() and len(body) <= 500:
+        message = body.strip()
+    return message or f"Ticket Fairy answered HTTP {response.status}.", code