prdb-sdk 0.1.0__tar.gz

prdb_sdk-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Local, machine-specific agent instructions — never committed
+CLAUDE.local.md
+
+# Kiota writes a generation log next to the output; it is noise, not source.
+.kiota.log
+
+# Python
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/
+.venv/
+
+# TypeScript
+node_modules/
+typescript/dist/
+typescript/.test-dist/
+*.tsbuildinfo
+
+# .NET
+bin/
+obj/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

prdb_sdk-0.1.0/LICENSE

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

prdb_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: prdb-sdk
+Version: 0.1.0
+Summary: Python SDK for the prdb Public API
+Project-URL: Homepage, https://github.com/prdb-net/prdb-sdk
+Project-URL: Repository, https://github.com/prdb-net/prdb-sdk
+Project-URL: Issues, https://github.com/prdb-net/prdb-sdk/issues
+License: MIT
+License-File: LICENSE
+Keywords: api,client,prdb,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: microsoft-kiota-bundle<2.0.0,>=1.11.7
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# prdb-sdk (Python)
+
+Python client for the [prdb Public API](https://apidocs.prdb.net/).
+
+## Install
+
+```bash
+pip install prdb-sdk
+```
+
+Requires Python 3.10 or newer. The client is async and uses `httpx` under the
+hood, by way of the Kiota bundle.
+
+## Usage
+
+```python
+import asyncio
+from uuid import UUID
+
+from prdb_sdk import create_client
+
+
+async def main() -> None:
+    client = create_client(api_key="...")
+
+    # GET /videos
+    page = await client.videos.get()
+    for video in page.items or []:
+        print(video.title)
+
+    # GET /videos/{id}
+    video = await client.videos.by_id(UUID("...")).get()
+
+    # Query parameters are typed, including the closed-set ones.
+    from prdb_sdk.generated.videos.videos_request_builder import VideosRequestBuilder
+
+    config = VideosRequestBuilder.VideosRequestBuilderGetRequestConfiguration(
+        query_parameters=VideosRequestBuilder.VideosRequestBuilderGetQueryParameters(
+            page=2,
+            page_size=50,
+            search="...",
+        )
+    )
+    page_two = await client.videos.get(request_configuration=config)
+
+
+asyncio.run(main())
+```
+
+The request builders mirror the API's URL structure, so `GET /videos/{id}/filehashes`
+is `client.videos.by_id(video_id).filehashes.get()`.
+
+## Authentication
+
+`create_client` sends the key in the `X-Api-Key` header, and keeps it on the API
+host: a redirect to a different origin raises `CrossOriginRedirectError` rather
+than handing your credential to whoever answers there. Redirects that stay on
+the same origin are followed normally.
+
+`base_url` must use `https`, so the key is never sent in cleartext.
+
+`GET /health` is the only endpoint that works without a key; use
+`create_anonymous_client()` for health probes. That one has no credential to
+protect, so it accepts a plain `http` base URL.
+
+## Options
+
+```python
+client = create_client(
+    api_key="...",
+    base_url="https://api.prdb.net",   # override for a staging deployment
+    http_client=my_httpx_async_client, # control timeouts, proxies, connection limits
+)
+```
+
+The client you pass in is configured with the SDK's middleware in place, so it
+behaves like the one built for you — same redirect rule, same retry handling.
+
+## Generated code
+
+Everything under `prdb_sdk/generated/` is produced by Kiota from
+`spec/openapi.json` in the repository root and is overwritten on every
+regeneration. Do not edit it — see the [root README](../README.md#regenerating).

prdb_sdk-0.1.0/README.md

@@ -0,0 +1,83 @@
+# prdb-sdk (Python)
+
+Python client for the [prdb Public API](https://apidocs.prdb.net/).
+
+## Install
+
+```bash
+pip install prdb-sdk
+```
+
+Requires Python 3.10 or newer. The client is async and uses `httpx` under the
+hood, by way of the Kiota bundle.
+
+## Usage
+
+```python
+import asyncio
+from uuid import UUID
+
+from prdb_sdk import create_client
+
+
+async def main() -> None:
+    client = create_client(api_key="...")
+
+    # GET /videos
+    page = await client.videos.get()
+    for video in page.items or []:
+        print(video.title)
+
+    # GET /videos/{id}
+    video = await client.videos.by_id(UUID("...")).get()
+
+    # Query parameters are typed, including the closed-set ones.
+    from prdb_sdk.generated.videos.videos_request_builder import VideosRequestBuilder
+
+    config = VideosRequestBuilder.VideosRequestBuilderGetRequestConfiguration(
+        query_parameters=VideosRequestBuilder.VideosRequestBuilderGetQueryParameters(
+            page=2,
+            page_size=50,
+            search="...",
+        )
+    )
+    page_two = await client.videos.get(request_configuration=config)
+
+
+asyncio.run(main())
+```
+
+The request builders mirror the API's URL structure, so `GET /videos/{id}/filehashes`
+is `client.videos.by_id(video_id).filehashes.get()`.
+
+## Authentication
+
+`create_client` sends the key in the `X-Api-Key` header, and keeps it on the API
+host: a redirect to a different origin raises `CrossOriginRedirectError` rather
+than handing your credential to whoever answers there. Redirects that stay on
+the same origin are followed normally.
+
+`base_url` must use `https`, so the key is never sent in cleartext.
+
+`GET /health` is the only endpoint that works without a key; use
+`create_anonymous_client()` for health probes. That one has no credential to
+protect, so it accepts a plain `http` base URL.
+
+## Options
+
+```python
+client = create_client(
+    api_key="...",
+    base_url="https://api.prdb.net",   # override for a staging deployment
+    http_client=my_httpx_async_client, # control timeouts, proxies, connection limits
+)
+```
+
+The client you pass in is configured with the SDK's middleware in place, so it
+behaves like the one built for you — same redirect rule, same retry handling.
+
+## Generated code
+
+Everything under `prdb_sdk/generated/` is produced by Kiota from
+`spec/openapi.json` in the repository root and is overwritten on every
+regeneration. Do not edit it — see the [root README](../README.md#regenerating).

prdb_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "prdb-sdk"
+version = "0.1.0"
+description = "Python SDK for the prdb Public API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["prdb", "sdk", "api", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Pulls in kiota abstractions, HTTP and the four serializers the generated
+    # code imports (json, text, form, multipart).
+    "microsoft-kiota-bundle>=1.11.7,<2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Homepage = "https://github.com/prdb-net/prdb-sdk"
+Repository = "https://github.com/prdb-net/prdb-sdk"
+Issues = "https://github.com/prdb-net/prdb-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+# Packaged as a whole directory: the generated tree uses PEP 420 implicit
+# namespace packages and carries no __init__.py files.
+packages = ["src/prdb_sdk"]
+
+[tool.hatch.build.targets.sdist]
+# LICENSE is a copy of the repository's, so the published artifact carries its
+# own licence rather than pointing at a file the consumer does not have.
+include = ["src/prdb_sdk", "README.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Every wrapper test drives an async client, so async tests need no marker.
+asyncio_mode = "auto"

prdb_sdk-0.1.0/src/prdb_sdk/__init__.py

@@ -0,0 +1,31 @@
+"""Python SDK for the prdb Public API.
+
+The request builders under the returned client mirror the API's URL structure::
+
+    from prdb_sdk import create_client
+
+    client = create_client(api_key="...")
+    page = await client.videos.get()
+    video = await client.videos.by_id(video_id).get()
+
+Everything under ``prdb_sdk.generated`` is produced by Kiota from
+``spec/openapi.json`` and is overwritten on every regeneration. Do not edit it.
+"""
+
+from .client import (
+    API_KEY_HEADER,
+    DEFAULT_BASE_URL,
+    CrossOriginRedirectError,
+    PrdbClient,
+    create_anonymous_client,
+    create_client,
+)
+
+__all__ = [
+    "API_KEY_HEADER",
+    "DEFAULT_BASE_URL",
+    "CrossOriginRedirectError",
+    "PrdbClient",
+    "create_anonymous_client",
+    "create_client",
+]

prdb_sdk-0.1.0/src/prdb_sdk/client.py

@@ -0,0 +1,178 @@
+"""Client construction for the prdb Public API."""
+
+from __future__ import annotations
+
+from typing import Optional
+from urllib.parse import urlparse
+
+import httpx
+from kiota_abstractions.authentication.anonymous_authentication_provider import (
+    AnonymousAuthenticationProvider,
+)
+from kiota_abstractions.authentication.authentication_provider import (
+    AuthenticationProvider,
+)
+from kiota_abstractions.authentication.api_key_authentication_provider import (
+    ApiKeyAuthenticationProvider,
+    KeyLocation,
+)
+from kiota_bundle.default_request_adapter import DefaultRequestAdapter
+from kiota_http.kiota_client_factory import KiotaClientFactory
+from kiota_http.middleware.options import RedirectHandlerOption
+
+from .generated.prdb_client import PrdbClient
+
+#: Header the API expects the key in.
+API_KEY_HEADER = "X-Api-Key"
+
+#: Production base URL, also the default baked into the generated client.
+DEFAULT_BASE_URL = "https://api.prdb.net"
+
+
+class CrossOriginRedirectError(RuntimeError):
+    """Raised when the API redirects to a different origin.
+
+    Following such a redirect would hand the API key to whoever answers at the
+    new location, so the SDK refuses it. Redirects that stay on the same origin
+    are followed normally.
+    """
+
+
+def create_client(
+    api_key: str,
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    http_client: Optional[httpx.AsyncClient] = None,
+) -> PrdbClient:
+    """Create a client authenticated with an API key.
+
+    Args:
+        api_key: The API key, sent in the ``X-Api-Key`` header on every request.
+        base_url: Override the API root. Useful for a staging deployment. Must
+            use ``https``, so the key never travels in cleartext.
+        http_client: Supply your own ``httpx.AsyncClient`` to control timeouts,
+            proxies or connection limits. One is created for you when omitted.
+            Either way the SDK's middleware is installed on it, which modifies
+            the client you pass in place.
+
+    Returns:
+        A client whose request builders mirror the API's URL structure, so
+        ``GET /videos/{id}`` is ``client.videos.by_id(video_id).get()``.
+
+    Raises:
+        ValueError: If ``api_key`` is empty, or ``base_url`` is not an absolute
+            ``https`` URL.
+    """
+    if not api_key:
+        raise ValueError("api_key must not be empty")
+
+    host = _resolve_host(base_url, require_https=True)
+
+    auth_provider = ApiKeyAuthenticationProvider(
+        key_location=KeyLocation.Header,
+        api_key=api_key,
+        parameter_name=API_KEY_HEADER,
+        allowed_hosts=[host],
+    )
+
+    return _build_client(auth_provider, base_url, http_client)
+
+
+def create_anonymous_client(
+    *,
+    base_url: str = DEFAULT_BASE_URL,
+    http_client: Optional[httpx.AsyncClient] = None,
+) -> PrdbClient:
+    """Create a client without credentials.
+
+    Only ``GET /health`` is reachable this way; every other endpoint answers
+    401. Provided so health probes do not need an API key.
+
+    With no key to protect, ``base_url`` may use plain ``http``.
+
+    Raises:
+        ValueError: If ``base_url`` is not an absolute URL.
+    """
+    _resolve_host(base_url, require_https=False)
+
+    return _build_client(AnonymousAuthenticationProvider(), base_url, http_client)
+
+
+def _build_client(
+    auth_provider: AuthenticationProvider,
+    base_url: str,
+    http_client: Optional[httpx.AsyncClient],
+) -> PrdbClient:
+    request_adapter = DefaultRequestAdapter(
+        authentication_provider=auth_provider,
+        http_client=_build_http_client(http_client),
+    )
+    request_adapter.base_url = base_url
+
+    return PrdbClient(request_adapter)
+
+
+def _build_http_client(http_client: Optional[httpx.AsyncClient]) -> httpx.AsyncClient:
+    """Load the SDK's middleware pipeline onto a client, creating one if needed.
+
+    A client handed straight to the request adapter carries no middleware at
+    all, which loses redirect handling, retries and Kiota's parameter name
+    decoding. Routing both paths through this function keeps a caller-supplied
+    client behaving like the one we build ourselves.
+    """
+    redirect_options = RedirectHandlerOption(
+        scrub_sensitive_headers=_refuse_cross_origin_redirect,
+    )
+
+    return KiotaClientFactory.create_with_default_middleware(
+        client=http_client,
+        options={RedirectHandlerOption.get_key(): redirect_options},
+    )
+
+
+def _refuse_cross_origin_redirect(
+    new_request: httpx.Request,
+    original_url: httpx.URL,
+) -> None:
+    """Refuse a redirect that leaves the origin the request started on.
+
+    This runs in place of Kiota's default header scrubbing, which drops only
+    ``Authorization`` and ``Cookie``. The prdb API key travels in a custom
+    header, and no layer below strips it: neither Kiota's redirect handler nor
+    httpx's own touch anything but ``Authorization``. A redirect off the API
+    host would therefore hand the credential to whoever answered.
+
+    The header is removed before raising as well, so the key is gone even if a
+    caller catches the error and reuses the request.
+    """
+    new_url = new_request.url
+    same_origin = (
+        original_url.scheme == new_url.scheme
+        and original_url.host == new_url.host
+        and original_url.port == new_url.port
+    )
+    if same_origin:
+        return
+
+    new_request.headers.pop(API_KEY_HEADER, None)
+    new_request.headers.pop("Authorization", None)
+    new_request.headers.pop("Cookie", None)
+
+    raise CrossOriginRedirectError(
+        f"refusing to follow a redirect from {original_url.host} to "
+        f"{new_url.host}; the api key is bound to the first host"
+    )
+
+
+def _resolve_host(base_url: str, *, require_https: bool) -> str:
+    parsed = urlparse(base_url)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        raise ValueError(f"base_url must be an absolute URL, got {base_url!r}")
+
+    if require_https and parsed.scheme != "https":
+        raise ValueError(
+            f"base_url must use https so the api key is not sent in cleartext, "
+            f"got {base_url!r}"
+        )
+
+    return parsed.hostname

prdb_sdk-0.1.0/src/prdb_sdk/generated/actors/actors_request_builder.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+import datetime
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from kiota_abstractions.base_request_builder import BaseRequestBuilder
+from kiota_abstractions.base_request_configuration import RequestConfiguration
+from kiota_abstractions.default_query_parameters import QueryParameters
+from kiota_abstractions.get_path_parameters import get_path_parameters
+from kiota_abstractions.method import Method
+from kiota_abstractions.request_adapter import RequestAdapter
+from kiota_abstractions.request_information import RequestInformation
+from kiota_abstractions.request_option import RequestOption
+from kiota_abstractions.serialization import Parsable, ParsableFactory
+from typing import Any, Optional, TYPE_CHECKING, Union
+from uuid import UUID
+from warnings import warn
+
+if TYPE_CHECKING:
+    from ..models.list_actors_response import ListActorsResponse
+    from ..models.problem_details import ProblemDetails
+    from .batch.batch_request_builder import BatchRequestBuilder
+    from .changes.changes_request_builder import ChangesRequestBuilder
+    from .get_sort_direction_query_parameter_type import GetSortDirectionQueryParameterType
+    from .item.actors_item_request_builder import ActorsItemRequestBuilder
+
+class ActorsRequestBuilder(BaseRequestBuilder):
+    """
+    Builds and executes requests for operations under /actors
+    """
+    def __init__(self,request_adapter: RequestAdapter, path_parameters: Union[str, dict[str, Any]]) -> None:
+        """
+        Instantiates a new ActorsRequestBuilder and sets the default values.
+        param path_parameters: The raw url or the url-template parameters for the request.
+        param request_adapter: The request adapter to use to execute the requests.
+        Returns: None
+        """
+        super().__init__(request_adapter, "{+baseurl}/actors{?CreatedAfter*,CreatedBefore*,Page*,PageSize*,Search*,SortBy*,SortDirection*}", path_parameters)
+    
+    def by_id(self,id: UUID) -> ActorsItemRequestBuilder:
+        """
+        Gets an item from the prdb_sdk.generated.actors.item collection
+        param id: Unique identifier of the item
+        Returns: ActorsItemRequestBuilder
+        """
+        if id is None:
+            raise TypeError("id cannot be null.")
+        from .item.actors_item_request_builder import ActorsItemRequestBuilder
+
+        url_tpl_params = get_path_parameters(self.path_parameters)
+        url_tpl_params["id"] = id
+        return ActorsItemRequestBuilder(self.request_adapter, url_tpl_params)
+    
+    async def get(self,request_configuration: Optional[RequestConfiguration[ActorsRequestBuilderGetQueryParameters]] = None) -> Optional[ListActorsResponse]:
+        """
+        Returns a paged list of actors. Supports free-text search by name or alias, and sorting by name or creation date. Default page size is 100, maximum is 500. Requires API key authentication.
+        param request_configuration: Configuration for the request such as headers, query parameters, and middleware options.
+        Returns: Optional[ListActorsResponse]
+        """
+        request_info = self.to_get_request_information(
+            request_configuration
+        )
+        from ..models.problem_details import ProblemDetails
+
+        error_mapping: dict[str, type[ParsableFactory]] = {
+            "401": ProblemDetails,
+        }
+        if not self.request_adapter:
+            raise Exception("Http core is null") 
+        from ..models.list_actors_response import ListActorsResponse
+
+        return await self.request_adapter.send_async(request_info, ListActorsResponse, error_mapping)
+    
+    def to_get_request_information(self,request_configuration: Optional[RequestConfiguration[ActorsRequestBuilderGetQueryParameters]] = None) -> RequestInformation:
+        """
+        Returns a paged list of actors. Supports free-text search by name or alias, and sorting by name or creation date. Default page size is 100, maximum is 500. Requires API key authentication.
+        param request_configuration: Configuration for the request such as headers, query parameters, and middleware options.
+        Returns: RequestInformation
+        """
+        request_info = RequestInformation(Method.GET, self.url_template, self.path_parameters)
+        request_info.configure(request_configuration)
+        request_info.headers.try_add("Accept", "application/json")
+        return request_info
+    
+    def with_url(self,raw_url: str) -> ActorsRequestBuilder:
+        """
+        Returns a request builder with the provided arbitrary URL. Using this method means any other path or query parameters are ignored.
+        param raw_url: The raw URL to use for the request builder.
+        Returns: ActorsRequestBuilder
+        """
+        if raw_url is None:
+            raise TypeError("raw_url cannot be null.")
+        return ActorsRequestBuilder(self.request_adapter, raw_url)
+    
+    @property
+    def batch(self) -> BatchRequestBuilder:
+        """
+        The batch property
+        """
+        from .batch.batch_request_builder import BatchRequestBuilder
+
+        return BatchRequestBuilder(self.request_adapter, self.path_parameters)
+    
+    @property
+    def changes(self) -> ChangesRequestBuilder:
+        """
+        The changes property
+        """
+        from .changes.changes_request_builder import ChangesRequestBuilder
+
+        return ChangesRequestBuilder(self.request_adapter, self.path_parameters)
+    
+    @dataclass
+    class ActorsRequestBuilderGetQueryParameters():
+        """
+        Returns a paged list of actors. Supports free-text search by name or alias, and sorting by name or creation date. Default page size is 100, maximum is 500. Requires API key authentication.
+        """
+        def get_query_parameter(self,original_name: str) -> str:
+            """
+            Maps the query parameters names to their encoded names for the URI template parsing.
+            param original_name: The original query parameter name in the class.
+            Returns: str
+            """
+            if original_name is None:
+                raise TypeError("original_name cannot be null.")
+            if original_name == "created_after":
+                return "CreatedAfter"
+            if original_name == "created_before":
+                return "CreatedBefore"
+            if original_name == "page":
+                return "Page"
+            if original_name == "page_size":
+                return "PageSize"
+            if original_name == "search":
+                return "Search"
+            if original_name == "sort_by":
+                return "SortBy"
+            if original_name == "sort_direction":
+                return "SortDirection"
+            return original_name
+        
+        created_after: Optional[datetime.datetime] = None
+
+        created_before: Optional[datetime.datetime] = None
+
+        page: Optional[int] = None
+
+        page_size: Optional[int] = None
+
+        search: Optional[str] = None
+
+        sort_by: Optional[str] = None
+
+        sort_direction: Optional[GetSortDirectionQueryParameterType] = None
+
+    
+    @dataclass
+    class ActorsRequestBuilderGetRequestConfiguration(RequestConfiguration[ActorsRequestBuilderGetQueryParameters]):
+        """
+        Configuration for the request such as headers, query parameters, and middleware options.
+        """
+        warn("This class is deprecated. Please use the generic RequestConfiguration class generated by the generator.", DeprecationWarning)
+    
+