rtbnext 1.0.0__py3-none-any.whl

rtbnext/__init__.py

@@ -0,0 +1,26 @@
+"""
+RTBNext Python SDK
+
+Official Python SDK for the RTBNext API.
+
+Provides access to all RTBNext API endpoints, resources, and data models.
+The SDK offers lazy loading, transparent caching, automatic revalidation,
+and a resource-oriented API for working with lists, profiles, filters,
+statistics, and time series data.
+
+Author: Paul Köhler (komed3)
+License: MIT
+"""
+
+from rtbnext._version import __version__
+from rtbnext.core.http_client import ClientIdentity
+from rtbnext.core.loader import CacheMode, CacheType
+from rtbnext.rtbnext import RTBNext, rtbnext
+
+__all__ = [
+    "RTBNext",
+    "rtbnext",
+    "ClientIdentity",
+    "CacheType",
+    "CacheMode"
+]

rtbnext/_version.py

@@ -0,0 +1,7 @@
+"""
+Version
+
+Declares the RTBNext Python SDK version.
+"""
+
+__version__ = "1.0.0"

rtbnext/core/cache.py

@@ -0,0 +1,102 @@
+"""
+Cache
+
+Implements a cache interface for storing and retrieving resource states.
+
+The cache protocol can be used to implement different storage backends,
+such as in-memory caches or external databases.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from rtbnext.core.loader import ResourceState
+
+
+@runtime_checkable
+class Cache( Protocol ):
+    """
+    Interface for cache implementations.
+
+    A cache stores and retrieves resource states using string keys.
+    Implementations may choose any storage backend, such as memory,
+    the filesystem or an external database.
+    """
+
+    @property
+    def size( self ) -> int:
+        """Returns the number of cached resource states."""
+        ...
+
+    async def get( self, key: str ) -> ResourceState | None:
+        """Retrieves a cached resource state."""
+        ...
+
+    async def set( self, key: str, value: ResourceState ) -> None:
+        """Stores a resource state."""
+        ...
+
+    async def delete( self, key: str ) -> None:
+        """Removes a resource state from the cache."""
+        ...
+
+    async def clear( self ) -> None:
+        """Removes all resource states from the cache."""
+        ...
+
+
+class EmptyCache( Cache ):
+    """
+    Cache implementation that never stores any data.
+
+    All read operations return `None`, while write operations are ignored.
+    This implementation can be used to disable caching without changing the
+    SDK's cache interface.
+    """
+
+    @property
+    def size( self ) -> int:
+        return 0
+
+    async def get( self, _key: str ) -> ResourceState | None:
+        return None
+
+    async def set( self, _key: str, _value: ResourceState ) -> None:
+        pass
+
+    async def delete( self, _key: str ) -> None:
+        pass
+
+    async def clear( self ) -> None:
+        pass
+
+
+class MemoryCache ( Cache ):
+    """
+    Simple in-memory cache backed by a dictionary.
+
+    Suitable for short-lived applications where persistence is not required.
+    Cached entries remain until they are explicitly removed or the cache is
+    cleared.
+    """
+
+    def __init__( self ) -> None:
+        self._store: dict[ str, ResourceState ] = {}
+
+    @property
+    def size( self ) -> int:
+        return len( self._store )
+
+    async def get( self, key: str ) -> ResourceState | None:
+        return self._store.get( key )
+
+    async def set( self, key: str, value: ResourceState ) -> None:
+        self._store[ key ] = value
+
+    async def delete( self, key: str ) -> None:
+        self._store.pop( key, None )
+
+    async def clear( self ) -> None:
+        self._store.clear()

rtbnext/core/http_client.py

@@ -0,0 +1,153 @@
+"""
+HTTP Client
+
+Implements an HTTP client with built-in rate limiting, request deduplication
+and proper client identification.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from time import perf_counter
+from typing import Self
+from urllib.parse import urljoin
+
+import httpx
+
+from rtbnext._version import __version__
+from rtbnext.core.rate_limiter import RateLimiter, RateLimitMode
+from rtbnext.defaults import (
+    DEFAULT_API_URL, DEFAULT_MAX_REQUESTS, DEFAULT_PER_SECONDS, DEFAULT_RATE_LIMIT_MODE,
+    DEFAULT_TIMEOUT
+)
+
+type HttpHeader = httpx.Headers | dict[ str, str ] | None
+
+
+@dataclass( slots= True, frozen= True )
+class ClientIdentity:
+    """Information used to identify the client making API requests."""
+
+    name: str
+    version: str
+    contact: str | None = None
+    email: str | None = None
+
+    def __post_init__( self ) -> None:
+        if not self.name.strip():
+            raise ValueError( "Client name is required." )
+        if not self.version.strip():
+            raise ValueError( "Client version is required." )
+
+
+@dataclass( slots= True, frozen= True, kw_only= True )
+class HttpResponse:
+    """Represents the response returned by an HTTP request."""
+
+    url: str
+    ok: bool
+    status: int
+    body: bytes
+    headers: httpx.Headers
+    latency: int
+
+
+class HttpClient:
+    """
+    HTTP client with built-in rate limiting and request deduplication.
+
+    Concurrent requests to the same URL share the same underlying request,
+    preventing duplicate network traffic.
+    """
+
+    def __init__(
+        self, client: ClientIdentity, *,
+        base_url: str = DEFAULT_API_URL,
+        max_requests: int = DEFAULT_MAX_REQUESTS,
+        per_seconds: float = DEFAULT_PER_SECONDS,
+        timeout: float = DEFAULT_TIMEOUT
+    ) -> None:
+        self._base_url, self._client_info, self._timeout = base_url, client, timeout
+
+        self._limiter = RateLimiter( max_requests, per_seconds )
+        self._client = httpx.AsyncClient( headers= self._create_headers(), follow_redirects= True )
+        self._pending: dict[ str, asyncio.Task[ HttpResponse ] ] = {}
+
+    async def __aenter__( self ) -> Self:
+        return self
+
+    async def __aexit__( self, *_ ) -> None:
+        await self.aclose()
+
+    def _create_headers( self ) -> httpx.Headers:
+        """Creates the default headers sent with every request."""
+
+        client = self._client_info
+        info = "; ".join( value for value in ( client.contact, client.email ) if value )
+
+        headers = httpx.Headers( {
+            "User-Agent": (
+                f"{ client.name }/{ client.version }"
+                f"{ f' ({ info })' if info else '' }"
+                f" @rtbnext/sdk/{ __version__ }"
+            ),
+            "X-Client-Name": client.name,
+            "X-Client-Version": client.version
+        } )
+
+        if client.contact:
+            headers[ "X-Client-Contact" ] = client.contact
+
+        return headers
+
+    async def _execute(
+        self, url: str, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> HttpResponse:
+        """Executes a single HTTP request."""
+
+        await self._limiter.acquire( mode )
+
+        try:
+            start = perf_counter()
+            res = await self._client.get(
+                url, headers= headers, timeout= self._timeout if timeout is None else timeout
+            )
+
+        except httpx.HTTPError as exc:
+            raise RuntimeError( f"Fetch failed: { exc }" ) from exc
+
+        return HttpResponse(
+            url= str( res.url ), ok= res.is_success, status= res.status_code, body= res.content,
+            headers= res.headers, latency= round( ( perf_counter() - start ) * 1000 )
+        )
+
+    async def request(
+        self, path: str, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> HttpResponse:
+        """Sends a request relative to the configured base URL."""
+
+        url = urljoin( self._base_url, path )
+
+        if task := self._pending.get( url ):
+            return await task
+
+        self._pending[ url ] = task = asyncio.create_task( self._execute(
+            url, headers= headers, mode= mode, timeout= timeout
+        ) )
+
+        try:
+            return await task
+        finally:
+            self._pending.pop( url, None )
+
+    async def aclose( self ) -> None:
+        """Closes the underlying HTTP client and release network resources."""
+
+        await self._client.aclose()

rtbnext/core/loader.py

@@ -0,0 +1,173 @@
+"""
+Resource State Loader
+
+Implements the resource state loader with build-in caching and HTTP revalidation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from time import time
+from typing import Literal, Self
+
+import httpx
+
+from rtbnext.core.cache import Cache, EmptyCache, MemoryCache
+from rtbnext.core.http_client import HttpClient, HttpHeader, HttpResponse, RateLimitMode
+from rtbnext.defaults import DEFAULT_CACHE_MODE, DEFAULT_CACHE_TYPE, DEFAULT_RATE_LIMIT_MODE
+
+type CacheType = Cache | Literal[ "memory", False ]
+type CacheMode = Literal[ "ttl", "session", "revalidate" ]
+
+
+@dataclass( slots= True, kw_only= True )
+class ResourceState:
+    """Represents the state of a cached resource."""
+
+    response: HttpResponse
+    created: float
+    expires: float | None = None
+    etag: str | None = None
+    last_modified: str | None = None
+
+
+class ResourceStateLoader:
+    """
+    Loads resource states with optional caching and HTTP revalidation.
+
+    The loader supports session, TTL and revalidation cache modes while
+    transparently handling conditional HTTP requests.
+    """
+
+    def __init__(
+        self, *,
+        client: HttpClient,
+        cache: CacheType = DEFAULT_CACHE_TYPE,
+        mode: CacheMode = DEFAULT_CACHE_MODE
+    ) -> None:
+        self._client, self._mode = client, mode
+
+        match cache:
+            case "memory": self._cache = MemoryCache()
+            case False: self._cache = EmptyCache()
+            case _ if isinstance( cache, Cache ): self._cache = cache
+            case _: raise ValueError( f"Invalid cache type: { cache }" )
+
+    async def __aenter__( self ) -> Self:
+        return self
+
+    async def __aexit__( self, *_ ) -> None:
+        await self.aclose()
+
+    def _state( self, res: HttpResponse, prev: ResourceState | None = None ) -> ResourceState:
+        """Creates a cached resource state from an HTTP response."""
+
+        created = time()
+
+        max_age = next( (
+            int( p.split( "=" )[ 1 ] )
+            for p in res.headers.get( "Cache-Control", "" ).split( "," )
+            if p.strip().startswith( "max-age=" )
+        ), None )
+
+        expires = created + max_age if max_age is not None else getattr( prev, "expires", None )
+        etag = res.headers.get( "ETag" ) or getattr( prev, "etag", None )
+        last_modified = res.headers.get( "Last-Modified" ) or getattr( prev, "last_modified", None )
+
+        if res.status == 304 and prev:
+            res = HttpResponse(
+                url= prev.response.url, ok= prev.response.ok, status= prev.response.status,
+                body= prev.response.body, headers= res.headers, latency= res.latency
+            )
+
+        return ResourceState(
+            response= res, created= created, expires= expires,
+            etag= etag, last_modified= last_modified
+        )
+
+    async def _fetch(
+        self, path: str, prev: ResourceState | None = None, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> ResourceState:
+        """Fetches a resource from the network."""
+
+        headers = httpx.Headers( headers or {} )
+
+        if prev and prev.etag:
+            headers[ "If-None-Match" ] = prev.etag
+        if prev and prev.last_modified:
+            headers[ "If-Modified-Since" ] = prev.last_modified
+
+        res = await self._client.request( path, headers= headers, mode= mode, timeout= timeout )
+        return self._state( res, prev )
+
+    async def refresh(
+        self, path: str, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> ResourceState:
+        """Refreshes a cached resource."""
+
+        state = await self._fetch(
+            path, await self._cache.get( path ),
+            headers= headers, mode= mode, timeout= timeout
+        )
+
+        await self._cache.set( path, state )
+        return state
+
+    def _is_expired( self, state: ResourceState ) -> bool:
+        """Determines whether a cached resource has expired."""
+
+        return state.expires is not None and state.expires <= time()
+
+    def valid( self, state: ResourceState | None ) -> bool:
+        """Determines whether a cached resource is valid."""
+
+        return ( state is not None and ( self._mode == "session" or (
+            self._mode == "ttl" and not self._is_expired( state )
+        ) ) )
+
+    async def load(
+        self, path: str, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> ResourceState:
+        """Loads a resource using the configured cache policy."""
+
+        if self._mode == "revalidate":
+            return await self.refresh( path, headers= headers, mode= mode, timeout= timeout )
+
+        if ( cached := await self._cache.get( path ) ) and self.valid( cached ):
+            return cached
+
+        state = await self._fetch( path, None, headers= headers, mode= mode, timeout= timeout )
+        if self._mode == "session" or state.expires:
+            await self._cache.set( path, state )
+
+        return state
+
+    @property
+    def size( self ) -> int:
+        """Returns the number of cached resource states."""
+
+        return self._cache.size
+
+    async def delete( self, path: str ) -> None:
+        """Removes a resource from the cache."""
+
+        await self._cache.delete( path )
+
+    async def clear( self ) -> None:
+        """Removes all cached resource states."""
+
+        await self._cache.clear()
+
+    async def aclose( self ) -> None:
+        """Closes the underlying HTTP client and release network resources."""
+
+        await self._client.aclose()

rtbnext/core/parser.py

@@ -0,0 +1,84 @@
+"""
+Parser
+
+Implements the HTTP response body parser methods for simple text,
+JSON responses and CSV data.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from io import StringIO
+from typing import Callable, Generic, Literal, TypeVar
+
+from rtbnext.core.http_client import HttpResponse
+
+D = TypeVar( "D" )
+
+type ParserFn[ D ] = Callable[ [ HttpResponse ], D ]
+type ParserMode = Literal[ "text", "json", "csv" ]
+
+
+class Parser( Generic[ D ] ):
+    """
+    Parses HTTP response bodies into text or objects.
+
+    The parser validates the response status and ensures that
+    the response contains data before decoding it.
+    """
+
+    @staticmethod
+    def _number( value: str ) -> str | int | float:
+        """Parses an individual CSV field value, converting numeric strings to numbers."""
+
+        value = value.strip()
+
+        try:
+            return float( value ) if "." in value else int( value ) if value else value
+        except ValueError:
+            return value
+
+    @staticmethod
+    def text( res: HttpResponse ) -> str:
+        """Converts an HTTP response body to UTF-8 text."""
+
+        if not res.ok:
+            raise RuntimeError( f"Request failed with status { res.status }." )
+        if not res.body:
+            raise RuntimeError( "Response contains no data." )
+
+        try:
+            return res.body.decode()
+        except Exception as exc:
+            raise RuntimeError( f"Failed to decode response: { exc }" ) from exc
+
+    @staticmethod
+    def json( res: HttpResponse ) -> D:
+        """Parses an HTTP response body as JSON."""
+
+        try:
+            return json.loads( Parser.text( res ) )
+        except Exception as exc:
+            raise RuntimeError( f"Failed to parse JSON: { exc }" ) from exc
+
+    @staticmethod
+    def csv( res: HttpResponse, delimiter: str = "," ) -> list[ list[ str | int | float ] ]:
+        """Parses an HTTP response body as CSV."""
+
+        return [
+            [ Parser._number( value ) for value in row ]
+            for row in csv.reader( StringIO( Parser.text( res ) ), delimiter= delimiter )
+        ]
+
+
+def parser( mode: ParserMode ) -> ParserFn[ D ]:
+    """
+    Returns the parser function based on the given mode.
+    Raises if the parser for the given mode is not implemented.
+    """
+
+    if not hasattr( Parser, mode ):
+        raise ValueError( f"Unsupported parser mode: { mode }" )
+
+    return getattr( Parser, mode )

rtbnext/core/rate_limiter.py

@@ -0,0 +1,86 @@
+"""
+Rate Limiter
+
+Implements a rate limiter supporting burst and spread strategies.
+
+Supports two strategies:
+- `burst`: allows short bursts of requests
+- `spread`: distributes requests evenly over time
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+from time import monotonic
+from typing import Literal
+
+from rtbnext.defaults import DEFAULT_MAX_REQUESTS, DEFAULT_PER_SECONDS
+
+type RateLimitMode = Literal[ "burst", "spread" ]
+
+
+class RateLimiter:
+    """
+    Rate limitting API requests.
+    
+    Async rate limiter supporting burst and spread strategies:
+    - `burst`: allows short bursts of requests
+    - `spread`: distributes requests evenly over time
+    """
+
+    def __init__(
+        self,
+        max_requests: int = DEFAULT_MAX_REQUESTS,
+        per_seconds: float = DEFAULT_PER_SECONDS
+    ) -> None:
+        self._max_requests, self._per_seconds = max_requests, per_seconds
+        self._interval = self._per_seconds / max_requests
+
+        self._burst = deque[ float ]()
+        self._next_allowed = 0.0
+
+        self._lock = asyncio.Lock()
+
+    async def _spread_refill( self ) -> None:
+        """Waits until the next evenly distributed request is allowed."""
+
+        async with self._lock:
+            now = monotonic()
+            self._next_allowed = max( self._next_allowed, now )
+            wait = self._next_allowed - now
+            self._next_allowed += self._interval
+
+        if wait > 0:
+            await asyncio.sleep( wait )
+
+    async def burst( self ) -> None:
+        """
+        Allows up to max_requests immediately.
+        Further requests wait until the rolling window expires.
+        """
+
+        while True:
+            async with self._lock:
+                now = monotonic()
+
+                while self._burst and now - self._burst[ 0 ] >= self._per_seconds:
+                    self._burst.popleft()
+
+                if len( self._burst ) < self._max_requests:
+                    self._burst.append( now )
+                    return
+
+                wait = self._per_seconds - ( now - self._burst[ 0 ] )
+
+            await asyncio.sleep( wait )
+
+    async def spread( self ) -> None:
+        """Distributes requests evenly across the configured time window."""
+
+        await self._spread_refill()
+
+    async def acquire( self, mode: RateLimitMode = "burst" ) -> None:
+        """Acquires permission to perform a request."""
+
+        await getattr( self, mode )()

rtbnext/defaults.py

@@ -0,0 +1,26 @@
+"""
+Defaults
+
+Declares default values for options.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rtbnext.core.loader import CacheMode, CacheType
+    from rtbnext.core.rate_limiter import RateLimitMode
+
+DEFAULT_API_URL: str = "https://api.rtbnext.de"
+
+DEFAULT_MAX_REQUESTS: int = 60
+DEFAULT_PER_SECONDS: float = 10.0
+DEFAULT_RATE_LIMIT_MODE: RateLimitMode = "burst"
+
+DEFAULT_TIMEOUT: float = 30.0
+
+DEFAULT_CACHE_TYPE: CacheType = "memory"
+DEFAULT_CACHE_MODE: CacheMode = "ttl"
+
+DEFAULT_PER_PAGE: int = 10