huntapi 0.1.0__py3-none-any.whl

huntapi/__init__.py

@@ -0,0 +1,61 @@
+"""Official Python SDK for the HuntAPI API."""
+
+from ._endpoints import ENDPOINTS
+from ._version import __version__
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_CONCURRENCY,
+    DEFAULT_RETRY_DELAY,
+    DEFAULT_TIMEOUT,
+    MAX_RETRIES,
+    RETRY_BACKOFF_FACTOR,
+    AsyncHuntApiClient,
+    HuntApiClient,
+)
+from .errors import (
+    HuntApiAPIError,
+    HuntApiConfigurationError,
+    HuntApiError,
+    HuntApiJobTimeoutError,
+    HuntApiResponseDecodingError,
+    HuntApiSerializationError,
+    HuntApiTransportError,
+)
+from .models import (
+    APIResponse,
+    BatchResult,
+    BinaryResponse,
+    EndpointDefinition,
+    HTTPMethod,
+    JsonResponse,
+    RawResponse,
+    RequestOptions,
+)
+
+__all__ = [
+    "APIResponse",
+    "AsyncHuntApiClient",
+    "BatchResult",
+    "BinaryResponse",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_CONCURRENCY",
+    "DEFAULT_RETRY_DELAY",
+    "DEFAULT_TIMEOUT",
+    "MAX_RETRIES",
+    "RETRY_BACKOFF_FACTOR",
+    "ENDPOINTS",
+    "EndpointDefinition",
+    "HTTPMethod",
+    "JsonResponse",
+    "RawResponse",
+    "RequestOptions",
+    "HuntApiAPIError",
+    "HuntApiClient",
+    "HuntApiConfigurationError",
+    "HuntApiError",
+    "HuntApiJobTimeoutError",
+    "HuntApiResponseDecodingError",
+    "HuntApiSerializationError",
+    "HuntApiTransportError",
+    "__version__",
+]

huntapi/_endpoints.py

@@ -0,0 +1,50 @@
+"""Generated from the HuntAPI OpenAPI document. Do not edit by hand."""
+
+from __future__ import annotations
+
+from .models import EndpointDefinition
+
+ENDPOINTS: dict[str, EndpointDefinition] = {
+    "audio_download": EndpointDefinition(
+        path="/v1/audio/download",
+        methods=(
+            "GET",
+            "POST",
+        ),
+        response="json",
+        required=("query",),
+    ),
+    "jobs": EndpointDefinition(
+        path="/v1/jobs/{id}",
+        methods=("GET",),
+        response="json",
+        required=("id",),
+    ),
+    "media_metadata": EndpointDefinition(
+        path="/v1/media/metadata",
+        methods=("GET",),
+        response="json",
+        required=("query",),
+    ),
+    "stats": EndpointDefinition(
+        path="/v1/stats",
+        methods=("GET",),
+        response="json",
+        required=(),
+    ),
+    "usage": EndpointDefinition(
+        path="/v1/usage",
+        methods=("GET",),
+        response="json",
+        required=(),
+    ),
+    "video_download": EndpointDefinition(
+        path="/v1/video/download",
+        methods=(
+            "GET",
+            "POST",
+        ),
+        response="json",
+        required=("query",),
+    ),
+}

huntapi/_operations.py

@@ -0,0 +1,380 @@
+"""Generated from the HuntAPI OpenAPI document. Do not edit by hand."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from .models import APIResponse, JsonResponse, RequestOptions
+
+
+class _SyncOperations:
+    """Generated HuntAPI endpoint methods."""
+
+    __slots__ = ()
+
+    def _call(
+        self, name: str, params: dict[str, Any], options: RequestOptions | None
+    ) -> APIResponse:
+        raise NotImplementedError
+
+    def audio_download(
+        self,
+        *,
+        query: str,
+        download_type: str | None = None,
+        max_duration: int | float | None = None,
+        audio_quality: str | None = None,
+        audio_format: str | None = None,
+        webhook_url: str | None = None,
+        webhook_authorization: str | None = None,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Audio Download. Download audio from a URL via HuntAPI and receive a job id. Credit cost: 1 credit per call.
+
+        ``GET / POST /v1/audio/download``
+
+        Args:
+            query: URL to download audio from.
+            download_type: Desired download type. Supported values: audio (default).
+            max_duration: Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded.
+            audio_quality: Desired audio quality.
+            audio_format: Desired output format for the audio.
+            webhook_url: URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be s…
+            webhook_authorization: Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            self._call(
+                "audio_download",
+                {
+                    "query": query,
+                    "download_type": download_type,
+                    "max_duration": max_duration,
+                    "audio_quality": audio_quality,
+                    "audio_format": audio_format,
+                    "webhook_url": webhook_url,
+                    "webhook_authorization": webhook_authorization,
+                    "fields": fields,
+                    "is_async": is_async,
+                    "soft_fail": soft_fail,
+                },
+                request_options,
+            ),
+        )
+
+    def jobs(
+        self,
+        *,
+        id: str,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Jobs. Poll status, progress (0–100), and result of an async HuntAPI job.
+
+        ``GET /v1/jobs/{id}``
+
+        Args:
+            id: Job UUID returned as job_id by async endpoints such as /v1/video/download and /v1/audio/download.
+        """
+        return cast(JsonResponse, self._call("jobs", {"id": id}, request_options))
+
+    def media_metadata(
+        self,
+        *,
+        query: str,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Media Metadata. Extract metadata from a media URL without downloading the file. Credit cost: 1 credit per call.
+
+        ``GET /v1/media/metadata``
+
+        Args:
+            query: Media URL to inspect (YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, Reddit, etc.).
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            self._call(
+                "media_metadata",
+                {"query": query, "fields": fields, "is_async": is_async, "soft_fail": soft_fail},
+                request_options,
+            ),
+        )
+
+    def stats(
+        self,
+        *,
+        engine: str | None = None,
+        path: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Stats. Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.
+
+        ``GET /v1/stats``
+
+        Args:
+            engine: API family to check, for example video. Provide at least engine or path.
+            path: Specific endpoint to check, for example /v1/video/download. If you also pass engine, use an endpoint from that API.
+        """
+        return cast(
+            JsonResponse, self._call("stats", {"engine": engine, "path": path}, request_options)
+        )
+
+    def usage(
+        self,
+        *,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Usage. Retrieve real-time usage statistics and credit balance for your Huntapi account.
+
+        ``GET /v1/usage``
+        """
+        return cast(JsonResponse, self._call("usage", {}, request_options))
+
+    def video_download(
+        self,
+        *,
+        query: str,
+        download_type: str | None = None,
+        max_duration: int | float | None = None,
+        video_quality: str | None = None,
+        video_format: str | None = None,
+        webhook_url: str | None = None,
+        webhook_authorization: str | None = None,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Video Download. Credit cost: 1 credit per call.
+
+        ``GET / POST /v1/video/download``
+
+        Args:
+            query: Video URL to download.
+            download_type: Desired download type. You have three options:
+            max_duration: Maximum duration of the downloaded content in seconds. If the video/audio is longer than this value, only the content up to this duration will be downloaded.
+            video_quality: Desired video quality. Available options:
+            video_format: Desired output format for the video. Available options:
+            webhook_url: URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be s…
+            webhook_authorization: Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint. This value will be included in the Authorization header when making the webhook request…
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            self._call(
+                "video_download",
+                {
+                    "query": query,
+                    "download_type": download_type,
+                    "max_duration": max_duration,
+                    "video_quality": video_quality,
+                    "video_format": video_format,
+                    "webhook_url": webhook_url,
+                    "webhook_authorization": webhook_authorization,
+                    "fields": fields,
+                    "is_async": is_async,
+                    "soft_fail": soft_fail,
+                },
+                request_options,
+            ),
+        )
+
+
+class _AsyncOperations:
+    """Generated HuntAPI endpoint methods."""
+
+    __slots__ = ()
+
+    async def _call(
+        self, name: str, params: dict[str, Any], options: RequestOptions | None
+    ) -> APIResponse:
+        raise NotImplementedError
+
+    async def audio_download(
+        self,
+        *,
+        query: str,
+        download_type: str | None = None,
+        max_duration: int | float | None = None,
+        audio_quality: str | None = None,
+        audio_format: str | None = None,
+        webhook_url: str | None = None,
+        webhook_authorization: str | None = None,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Audio Download. Download audio from a URL via HuntAPI and receive a job id. Credit cost: 1 credit per call.
+
+        ``GET / POST /v1/audio/download``
+
+        Args:
+            query: URL to download audio from.
+            download_type: Desired download type. Supported values: audio (default).
+            max_duration: Maximum duration of the downloaded content in seconds. If the audio is longer than this value, only the content up to this duration will be downloaded.
+            audio_quality: Desired audio quality.
+            audio_format: Desired output format for the audio.
+            webhook_url: URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be s…
+            webhook_authorization: Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint.
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            await self._call(
+                "audio_download",
+                {
+                    "query": query,
+                    "download_type": download_type,
+                    "max_duration": max_duration,
+                    "audio_quality": audio_quality,
+                    "audio_format": audio_format,
+                    "webhook_url": webhook_url,
+                    "webhook_authorization": webhook_authorization,
+                    "fields": fields,
+                    "is_async": is_async,
+                    "soft_fail": soft_fail,
+                },
+                request_options,
+            ),
+        )
+
+    async def jobs(
+        self,
+        *,
+        id: str,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Jobs. Poll status, progress (0–100), and result of an async HuntAPI job.
+
+        ``GET /v1/jobs/{id}``
+
+        Args:
+            id: Job UUID returned as job_id by async endpoints such as /v1/video/download and /v1/audio/download.
+        """
+        return cast(JsonResponse, await self._call("jobs", {"id": id}, request_options))
+
+    async def media_metadata(
+        self,
+        *,
+        query: str,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Media Metadata. Extract metadata from a media URL without downloading the file. Credit cost: 1 credit per call.
+
+        ``GET /v1/media/metadata``
+
+        Args:
+            query: Media URL to inspect (YouTube, Instagram, TikTok, Vimeo, X, Facebook, Twitch, Reddit, etc.).
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            await self._call(
+                "media_metadata",
+                {"query": query, "fields": fields, "is_async": is_async, "soft_fail": soft_fail},
+                request_options,
+            ),
+        )
+
+    async def stats(
+        self,
+        *,
+        engine: str | None = None,
+        path: str | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Stats. Infrastructure health for an engine or endpoint over the last hour. Not scoped to your account or tenant. Enabled per account: HTTP 403 means contact support to activate it.
+
+        ``GET /v1/stats``
+
+        Args:
+            engine: API family to check, for example video. Provide at least engine or path.
+            path: Specific endpoint to check, for example /v1/video/download. If you also pass engine, use an endpoint from that API.
+        """
+        return cast(
+            JsonResponse,
+            await self._call("stats", {"engine": engine, "path": path}, request_options),
+        )
+
+    async def usage(
+        self,
+        *,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Usage. Retrieve real-time usage statistics and credit balance for your Huntapi account.
+
+        ``GET /v1/usage``
+        """
+        return cast(JsonResponse, await self._call("usage", {}, request_options))
+
+    async def video_download(
+        self,
+        *,
+        query: str,
+        download_type: str | None = None,
+        max_duration: int | float | None = None,
+        video_quality: str | None = None,
+        video_format: str | None = None,
+        webhook_url: str | None = None,
+        webhook_authorization: str | None = None,
+        fields: str | None = None,
+        is_async: bool | None = None,
+        soft_fail: bool | None = None,
+        request_options: RequestOptions | None = None,
+    ) -> JsonResponse:
+        """Video Download. Credit cost: 1 credit per call.
+
+        ``GET / POST /v1/video/download``
+
+        Args:
+            query: Video URL to download.
+            download_type: Desired download type. You have three options:
+            max_duration: Maximum duration of the downloaded content in seconds. If the video/audio is longer than this value, only the content up to this duration will be downloaded.
+            video_quality: Desired video quality. Available options:
+            video_format: Desired output format for the video. Available options:
+            webhook_url: URL of the webhook where results will be sent. When specified, the system will attempt to send the response to this URL up to 3 times with a 5-second delay between each attempt. The results will be s…
+            webhook_authorization: Authorization header for the webhook. This parameter allows you to add authentication to your webhook endpoint. This value will be included in the Authorization header when making the webhook request…
+            fields: Comma-separated list of fields to keep in the response, with dot notation for nested fields (e.g. name,location.city). Does not change the credit cost.
+            is_async: Process the request asynchronously: the response is a job_id to poll on /v1/jobs/{id} (see waitForJob).
+            soft_fail: Return HTTP 200 even when an error occurs; the error is then in the response body.
+        """
+        return cast(
+            JsonResponse,
+            await self._call(
+                "video_download",
+                {
+                    "query": query,
+                    "download_type": download_type,
+                    "max_duration": max_duration,
+                    "video_quality": video_quality,
+                    "video_format": video_format,
+                    "webhook_url": webhook_url,
+                    "webhook_authorization": webhook_authorization,
+                    "fields": fields,
+                    "is_async": is_async,
+                    "soft_fail": soft_fail,
+                },
+                request_options,
+            ),
+        )

huntapi/_response.py

@@ -0,0 +1,82 @@
+"""Buffered HTTP response preservation and decoding."""
+
+from __future__ import annotations
+
+import json
+from types import MappingProxyType
+from typing import Any, Literal
+
+import httpx
+
+from .errors import HuntApiAPIError, HuntApiResponseDecodingError
+from .models import APIResponse, BinaryResponse, JsonResponse, RawResponse
+
+_ERROR_MESSAGE_KEYS = ("error", "message", "error_message", "detail")
+
+
+def create_raw_response(response: httpx.Response, body: bytes) -> RawResponse:
+    grouped: dict[str, list[str]] = {}
+    for name, value in response.headers.multi_items():
+        grouped.setdefault(name.lower(), []).append(value)
+    return RawResponse(
+        status=response.status_code,
+        status_text=response.reason_phrase,
+        headers=MappingProxyType({name: tuple(values) for name, values in grouped.items()}),
+        content_type=response.headers.get("content-type"),
+        body=body,
+    )
+
+
+def create_api_error(raw_response: RawResponse) -> HuntApiAPIError:
+    parsed, value = _try_parse_json(raw_response.body)
+    message = None
+    if parsed and isinstance(value, dict):
+        for key in _ERROR_MESSAGE_KEYS:
+            candidate = value.get(key)
+            if isinstance(candidate, str) and candidate:
+                message = candidate
+                break
+    return HuntApiAPIError(
+        raw_response=raw_response,
+        response_body=value if parsed else None,
+        error_message=message,
+    )
+
+
+def decode_success_response(
+    raw_response: RawResponse, expected: Literal["json", "any"]
+) -> APIResponse:
+    if not _is_json_media_type(raw_response.content_type):
+        if expected == "json":
+            raise HuntApiResponseDecodingError(
+                "HuntAPI returned a successful non-JSON response for a JSON operation.",
+                raw_response,
+                TypeError(f"Unexpected content type: {raw_response.content_type}."),
+            )
+        return BinaryResponse(
+            bytes=raw_response.body,
+            content_type=raw_response.content_type,
+            raw_response=raw_response,
+        )
+    parsed, value = _try_parse_json(raw_response.body)
+    if not parsed:
+        raise HuntApiResponseDecodingError(
+            "HuntAPI returned a successful JSON response that could not be decoded.",
+            raw_response,
+            value if isinstance(value, Exception) else None,
+        )
+    return JsonResponse(data=value, raw_response=raw_response)
+
+
+def _is_json_media_type(content_type: str | None) -> bool:
+    if content_type is None:
+        return False
+    media_type = content_type.split(";", 1)[0].strip().lower()
+    return media_type == "application/json" or media_type.endswith("+json")
+
+
+def _try_parse_json(body: bytes) -> tuple[bool, Any]:
+    try:
+        return True, json.loads(body)
+    except (UnicodeDecodeError, json.JSONDecodeError) as cause:
+        return False, cause

huntapi/_serialization.py

@@ -0,0 +1,109 @@
+"""Request serialization: path filling, query pairs and JSON bodies."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote, urlencode
+
+from .errors import HuntApiSerializationError
+from .models import HTTPMethod
+
+_PATH_PARAM = re.compile(r"\{([^}]+)\}")
+# The API reads the global parameters from the query string, whatever the method.
+QUERY_STRING_PARAMS = ("fields", "is_async", "soft_fail")
+
+
+@dataclass(frozen=True, slots=True)
+class SerializedRequest:
+    path: str
+    query: list[tuple[str, str]]
+    body: dict[str, Any] | None
+
+
+def serialize_request(
+    method: HTTPMethod, path_template: str, params: Mapping[str, Any] | None
+) -> SerializedRequest:
+    """Fill ``{name}`` path segments, then send the rest as query pairs (GET) or a JSON body (POST).
+
+    On POST, the global parameters (``fields``, ``is_async``, ``soft_fail``) still travel in the query string.
+
+    ``None`` values and empty sequences are omitted; ``False`` and ``0`` are sent.
+    """
+
+    if params is not None and not isinstance(params, Mapping):
+        raise HuntApiSerializationError("Request parameters must be a mapping.")
+    remaining = {name: value for name, value in (params or {}).items() if value is not None}
+
+    def fill(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name not in remaining:
+            raise HuntApiSerializationError(f'The "{name}" path parameter is required.', name)
+        return quote(to_wire_string(name, remaining.pop(name)), safe="")
+
+    path = _PATH_PARAM.sub(fill, path_template)
+
+    if method == "GET":
+        query: list[tuple[str, str]] = []
+        for name, value in remaining.items():
+            if isinstance(value, (list, tuple)):
+                query.extend(
+                    (name, to_wire_string(name, item)) for item in value if item is not None
+                )
+            else:
+                query.append((name, to_wire_string(name, value)))
+        return SerializedRequest(path=path, query=query, body=None)
+
+    query = [
+        (name, to_wire_string(name, remaining.pop(name)))
+        for name in QUERY_STRING_PARAMS
+        if name in remaining
+    ]
+    for name, value in remaining.items():
+        if isinstance(value, float) and not math.isfinite(value):
+            raise HuntApiSerializationError(
+                f'The "{name}" parameter must be a finite number.', name
+            )
+    return SerializedRequest(path=path, query=query, body=remaining)
+
+
+def to_wire_string(name: str, value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return value
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise HuntApiSerializationError(
+                f'The "{name}" parameter must be a finite number.', name
+            )
+        return str(int(value)) if value.is_integer() else repr(value)
+    if isinstance(value, (Mapping, list, tuple)):
+        try:
+            return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+        except (TypeError, ValueError) as cause:
+            raise HuntApiSerializationError(
+                f'The "{name}" parameter could not be serialized.', name
+            ) from cause
+    raise HuntApiSerializationError(
+        f'The "{name}" parameter has an unsupported type ({type(value).__name__}).', name
+    )
+
+
+def encode_query(pairs: list[tuple[str, str]]) -> str:
+    return urlencode(pairs, quote_via=quote)
+
+
+def encode_json_body(body: Mapping[str, Any]) -> bytes:
+    try:
+        return json.dumps(body, ensure_ascii=False, allow_nan=False).encode("utf-8")
+    except (TypeError, ValueError) as cause:
+        raise HuntApiSerializationError(
+            "The request body could not be serialized as JSON."
+        ) from cause

huntapi/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"