rtbnext 1.0.0__py3-none-any.whl

rtbnext/resource/series.py

@@ -0,0 +1,266 @@
+"""
+Time Series Resource
+
+Implements the resource wrapper for time-series endpoints.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date as date_type
+from statistics import mean, median
+from typing import Callable, Generic, Literal, TypedDict, TypeVar, cast
+
+from rtbnext.core.loader import ResourceStateLoader
+from rtbnext.core.parser import ParserFn
+from rtbnext.resource.base import Resource
+from rtbnext.resource.collection import DateCollectionBase
+
+TimePoint = TypedDict( "TimePoint", { "date": str } )
+type TimeSeriesRow = tuple
+
+AggregateValue = TypedDict( "AggregateValue", {
+    "first": float,
+    "last": float,
+    "min": float,
+    "max": float,
+    "avg": float,
+    "median": float,
+    "sum": float
+} )
+
+AggregateRange = TypedDict( "AggregateRange", {
+    "from": str,
+    "to": str
+} )
+
+AggregatePoint = TypedDict( "AggregatePoint", {
+    "date": str,
+    "label": str,
+    "range": AggregateRange
+} )
+
+A = TypeVar( "A", bound= AggregatePoint )
+D = TypeVar( "D", bound= list[ TimeSeriesRow ] )
+R = TypeVar( "R", bound= TimePoint )
+
+type AggregatePeriod = Literal[ "week", "month", "quarter", "year" ]
+type NumberCallback[ R ] = Callable[ [ R ], int | float ]
+type PointFn[ D, R ] = Callable[ [ D ], R ]
+
+
+class TimeSeriesCollection( DateCollectionBase[ R, R ], Generic[ R, A ] ):
+    """
+    Collection wrapper for time-series resources.
+
+    This class is the base for CSV resource collections, providing methods
+    to access dated data points, aggregate them and get statistical values
+    like min, max, median etc.
+    """
+
+    def _numbers( self, callback: NumberCallback | None = None ) -> list[ float ]:
+        """Returns numeric values from points."""
+
+        return (
+            [ float( callback( point ) ) for point in self ]
+            if callback is not None else
+            [
+                float( value ) for point in self for key, value in point.items()
+                if key != "date" and isinstance( value, ( int, float ) )
+            ]
+        )
+
+    def _period( self, date: str, period: AggregatePeriod ) -> str:
+        """Creates an aggregation key from a date."""
+
+        year, month, day = map( int, date.split( "-" ) )
+
+        if period == "year":
+            return str( year )
+
+        if period == "quarter":
+            return f"{ year }-Q{ ( month - 1 ) // 3 + 1 }"
+
+        if period == "month":
+            return f"{ year }-{month:02d}"
+
+        if period == "week":
+            iso_year, iso_week, _ = date_type( year, month, day ).isocalendar()
+            return f"{ iso_year }-W{iso_week:02d}"
+
+        raise ValueError( f"Invalid aggregate period: { period }" )
+
+    def _aggregate( self, points: list[ R ], label: str | None = None ) -> A:
+        """Aggregates a group of points."""
+
+        sorted_points = sorted( points, key= lambda point: point[ "date" ] )
+
+        result: dict[ str, object ] = {
+            "date": sorted_points[ -1 ][ "date" ],
+            "label": label or sorted_points[ -1 ][ "date" ],
+            "range": {
+                "from": sorted_points[ 0 ][ "date" ],
+                "to": sorted_points[ -1 ][ "date" ]
+            }
+        }
+
+        keys = sorted_points[ 0 ].keys()
+
+        for key in keys:
+            if key == "date":
+                continue
+
+            values = [
+                float( point[ key ] ) for point in sorted_points
+                if isinstance( point.get( key ), ( int, float ) )
+            ]
+
+            if not values:
+                continue
+
+            result[ key ] = {
+                "first": values[ 0 ],
+                "last": values[ -1 ],
+                "min": min( values ),
+                "max": max( values ),
+                "avg": float( mean( values ) ),
+                "median": float( median( values ) ),
+                "sum": sum( values )
+            }
+
+        return cast( A, result )
+
+    def _aggregated_series( self, points: list[ A ] ) -> TimeSeriesCollection[ A, A ]:
+        """Returns a time series collection of aggregated points."""
+
+        return TimeSeriesCollection(
+            points,
+            factory= lambda item: item,
+            date= lambda item: item[ "date" ]
+        )
+
+    @property
+    def points( self ) -> list[ R ]:
+        """Returns all time series points."""
+
+        return self._items
+
+    def min( self, callback: NumberCallback[ R ] | None = None ) -> float:
+        """Returns the minimum value."""
+
+        return min( self._numbers( callback ) )
+
+    def max( self, callback: NumberCallback[ R ] | None = None ) -> float:
+        """Returns the maximum value."""
+
+        return max( self._numbers( callback ) )
+
+    def sum( self, callback: NumberCallback[ R ] | None = None ) -> float:
+        """Returns the sum of values."""
+
+        return sum( self._numbers( callback ) )
+
+    def avg( self, callback: NumberCallback[ R ] | None = None ) -> float:
+        """Returns the average value."""
+
+        return float( mean( self._numbers( callback ) ) )
+
+    def median( self, callback: NumberCallback[ R ] | None = None ) -> float:
+        """Returns the median value."""
+
+        return float( median( self._numbers( callback ) ) )
+
+    @property
+    def labels( self ) -> list[ str ]:
+        """Returns the date labels."""
+
+        return [ point[ "date" ] for point in self ]
+
+    @property
+    def columns( self ) -> dict[ str, list[ object ] ]:
+        """Returns the values grouped by column."""
+
+        result: dict[ str, list[ object ] ] = {}
+
+        for point in self:
+            for key, value in point.items():
+                result.setdefault( key, [] ).append( value )
+
+        return result
+
+    def values( self, callback: NumberCallback ) -> list[ int | float ]:
+        """Returns the mapped numeric values."""
+
+        return [ callback( point ) for point in self ]
+
+    def column( self, key: str ) -> list[ object ]:
+        """Returns all values of a column."""
+
+        return [ point[ key ] for point in self ]
+
+    def aggregate(
+        self,
+        period: AggregatePeriod | Callable[ [ R ], str ]
+    ) -> TimeSeriesCollection[ A, A ]:
+        """Aggregates points by period."""
+
+        groups: dict[ str, list[ R ] ] = defaultdict( list )
+
+        for point in self:
+            groups[ (
+                period( point ) if callable( period )
+                else self._period( point[ "date" ], period )
+            ) ].append( point )
+
+        return self._aggregated_series( [
+            self._aggregate( group, label )
+            for label, group in groups.items()
+        ] )
+
+    def buckets( self, count: int ) -> TimeSeriesCollection[ A, A ]:
+        """Splits points into equally sized buckets."""
+
+        if count >= self.count:
+            return self._aggregated_series( [
+                self._aggregate( [ point ], f"{ index + 1 }/{ self.count }" )
+                for index, point in enumerate( self )
+            ] )
+
+        size, points = self.count / count, self.items
+        result: list[ A ] = []
+
+        for index in range( count ):
+            start, end = int( index * size ), int( ( index + 1 ) * size )
+            result.append( self._aggregate( points[ start : end ], f"{ index + 1 }/{ count }" ) )
+
+        return self._aggregated_series( result )
+
+
+class TimeSeriesResource( Resource[ D ], Generic[ D, R, A ] ):
+    """
+    Resource wrapper for time-series endpoints.
+
+    This class converts raw CSV rows into typed time-series points and
+    exposes them through a time-series collection.
+    """
+
+    def __init__(
+        self, path: str, loader: ResourceStateLoader, parser: ParserFn[ D ], *,
+        point: PointFn[ TimeSeriesRow, R ]
+    ) -> None:
+        super().__init__( path, loader, parser )
+        self._point = point
+
+    def _collect_points( self, rows: D ) -> TimeSeriesCollection[ R, A ]:
+        """Creates a time-series collection from raw rows."""
+
+        return TimeSeriesCollection(
+            [ self._point( row ) for row in reversed( rows ) ],
+            factory= lambda item: item,
+            date= lambda point: point[ "date" ]
+        )
+
+    async def series( self ) -> TimeSeriesCollection[ R, A ]:
+        """Returns the parsed time-series data as a typed collection."""
+
+        return await self._transform( self._collect_points )

rtbnext/rtbnext.py

@@ -0,0 +1,107 @@
+"""
+RTBNext
+
+Implements the main entry point class for the RTBNext Python SDK exposing
+all API endpoints.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Self
+
+from rtbnext.core.http_client import ClientIdentity, HttpClient
+from rtbnext.core.loader import CacheMode, CacheType, ResourceStateLoader
+from rtbnext.defaults import (
+    DEFAULT_API_URL, DEFAULT_CACHE_MODE, DEFAULT_CACHE_TYPE, DEFAULT_TIMEOUT
+)
+from rtbnext.endpoint.filter import FilterEndpoint
+from rtbnext.endpoint.list import ListEndpoint
+from rtbnext.endpoint.mover import MoverEndpoint
+from rtbnext.endpoint.profile import ProfileEndpoint
+from rtbnext.endpoint.stats import StatsEndpoint
+from rtbnext.endpoint.system import SystemEndpoint
+from rtbnext.resource.base import ResourcePool
+
+
+@dataclass( slots= True, kw_only= True )
+class Endpoints:
+    """Endpoints available in the RTBNext SDK."""
+
+    profile: ProfileEndpoint
+    list: ListEndpoint
+    mover: MoverEndpoint
+    filter: FilterEndpoint
+    stats: StatsEndpoint
+    system: SystemEndpoint
+
+
+class RTBNext:
+    """
+    Main entry point of the RTBNext SDK.
+
+    Provides access to all RTBNext API endpoints through a single client
+    instance while internally managing HTTP communication, resource loading,
+    caching, and endpoint initialization.
+    """
+
+    def __init__(
+        self, client: ClientIdentity, *,
+        base_url: str = DEFAULT_API_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        cache: CacheType = DEFAULT_CACHE_TYPE,
+        mode: CacheMode = DEFAULT_CACHE_MODE
+    ) -> None:
+        self._client = HttpClient( client= client, base_url= base_url, timeout= timeout )
+        self._loader = ResourceStateLoader( client= self._client, cache= cache, mode= mode )
+        self._pool = ResourcePool()
+
+        endpoints = Endpoints.__new__( Endpoints )
+        args = ( self._loader, self._pool, endpoints )
+
+        self.profile = endpoints.profile = ProfileEndpoint( *args )
+        self.list = endpoints.list = ListEndpoint( *args )
+        self.mover = endpoints.mover = MoverEndpoint( *args )
+        self.filter = endpoints.filter = FilterEndpoint( *args )
+        self.stats = endpoints.stats = StatsEndpoint( *args )
+        self.system = endpoints.system = SystemEndpoint( *args )
+
+        self.endpoints = endpoints
+
+    async def __aenter__( self ) -> Self:
+        return self
+
+    async def __aexit__( self, *_ ) -> None:
+        await self.close()
+
+    async def close( self ) -> None:
+        """Closes the underlying HTTP client and release network resources."""
+
+        await self._loader.aclose()
+
+
+def rtbnext(
+    client: ClientIdentity, *,
+    base_url: str = DEFAULT_API_URL,
+    timeout: float = DEFAULT_TIMEOUT,
+    cache: CacheType = DEFAULT_CACHE_TYPE,
+    mode: CacheMode = DEFAULT_CACHE_MODE
+) -> RTBNext:
+    """
+    Creates a new RTBNext SDK instance.
+
+    Args:
+        client: Client identity information.
+        base_url: RTBNext API base URL.
+        timeout: HTTP request timeout.
+        cache: Cache implementation.
+        mode: Cache mode.
+
+    Returns:
+        A configured RTBNext SDK instance.
+    """
+
+    return RTBNext(
+        client, base_url= base_url, timeout= timeout,
+        cache= cache, mode= mode
+    )

rtbnext/schema/assets.py

@@ -0,0 +1,101 @@
+"""
+Assets
+
+Declares shared types for assets, net worth, rankings, performance metrics,
+and historical financial data.
+"""
+
+from typing import Literal, NotRequired, TypedDict
+
+from rtbnext.schema.generic import AssetType, ChangeFlag
+
+type ReturnsPeriod = Literal[
+    "week", "month", "quarter", "halfYear", "year", "twoYear", "fiveYear"
+]
+
+ChangeItem = TypedDict( "ChangeItem", {
+    "value": float,
+    "percent": float
+} )
+
+AssetInfo = TypedDict( "AssetInfo", {
+    "exchange": str,
+    "ticker": str,
+    "shares": NotRequired[ float ],
+    "price": float,
+    "currency": str,
+    "exRate": float
+} )
+
+Asset = TypedDict( "Asset", {
+    "type": AssetType,
+    "label": str,
+    "value": NotRequired[ float ],
+    "info": NotRequired[ AssetInfo ]
+} )
+
+DataPoint = TypedDict( "DataPoint", {
+    "date": str,
+    "networth": float,
+    "rank": NotRequired[ int ]
+} )
+
+Extrema = TypedDict( "Extrema", {
+    "high": NotRequired[ DataPoint ],
+    "low": NotRequired[ DataPoint ]
+} )
+
+type Returns = dict[ ReturnsPeriod, ChangeItem ]
+
+Performance = TypedDict( "Performance", {
+    "extrema": NotRequired[ Extrema ],
+    "returns": NotRequired[ Returns ]
+} )
+
+RankingHistoryItem = TypedDict( "RankingHistoryItem", {
+    "date": str,
+    "rank": NotRequired[ int ],
+    "networth": NotRequired[ float ],
+    "prev": NotRequired[ str ],
+    "next": NotRequired[ str ]
+} )
+
+Ranking = TypedDict( "Ranking", {
+    "list": str,
+    "name": str,
+    "date": str,
+    "rank": NotRequired[ int ],
+    "networth": NotRequired[ float ],
+    "prev": NotRequired[ str ],
+    "next": NotRequired[ str ],
+    "history": NotRequired[ list[ RankingHistoryItem ] ]
+} )
+
+Realtime = TypedDict( "Realtime", {
+    "date": str,
+    "rank": NotRequired[ int ],
+    "networth": NotRequired[ float ],
+    "prev": NotRequired[ str ],
+    "next": NotRequired[ str ],
+    "today": NotRequired[ ChangeItem ],
+    "ytd": NotRequired[ ChangeItem ]
+} )
+
+AnnualRecord = TypedDict( "AnnualRecord", {
+    "first": int | float,
+    "last": int | float,
+    "diff": int | float,
+    "flag": ChangeFlag,
+    "mean": float,
+    "median": float,
+    "max": int | float,
+    "min": int | float,
+    "range": int | float,
+    "stdDev": float
+} )
+
+Annual = TypedDict( "Annual", {
+    "year": int,
+    "rank": NotRequired[ AnnualRecord ],
+    "networth": NotRequired[ AnnualRecord ]
+} )

rtbnext/schema/filter.py

@@ -0,0 +1,35 @@
+"""
+Filter
+
+Declares filter entries, documents and the index.
+"""
+
+from typing import Any, TypedDict
+
+from rtbnext.schema.generic import (
+    AgeGroup, FilterSpecial, Gender, Industry, MaritalStatus, MetaData
+)
+
+FilterItem = TypedDict( "FilterItem", {
+    "uri": str,
+    "name": str,
+    "value": Any
+} )
+
+Filter = TypedDict( "Filter", {
+    "$metadata": MetaData,
+    "count": int,
+    "items": list[ FilterItem ]
+} )
+
+FilterIndex = TypedDict( "FilterIndex", {
+    "$metadata": MetaData,
+    "industry": list[ Industry ],
+    "citizenship": list[ str ],
+    "country": list[ str ],
+    "state": list[ str ],
+    "gender": list[ Gender ],
+    "age": list[ AgeGroup ],
+    "maritalStatus": list[ MaritalStatus ],
+    "special": list[ FilterSpecial ]
+} )

rtbnext/schema/generic.py

@@ -0,0 +1,105 @@
+"""
+Literals & Generics
+
+Declares literals and generic types.
+"""
+
+from typing import Literal, NotRequired, TypedDict
+
+type Industry = Literal[
+    "automotive", "diversified", "energy", "engineering", "finance", "foodstuff",
+    "gambling", "healthcare", "logistics", "manufacturing", "media", "mining",
+    "property", "retail", "service", "sports", "technology", "telecom"
+]
+
+type AgeGroup = Literal[ "30", "40", "50", "60", "70", "80", "90" ]
+type Gender = Literal[ "m", "f", "d" ]
+type MaritalStatus = Literal[
+    "single", "relationship", "married", "remarried", "engaged", "separated",
+    "divorced", "widowed"
+]
+
+type SelfMadeRank = Literal[ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10" ]
+
+type RelationType = Literal[ "person", "organization", "place", "unknown" ]
+type AssetType = Literal[ "public", "private", "misc" ]
+type ChangeFlag = Literal[ "up", "down", "unchanged", "new", "returned", "dropoff", "unknown" ]
+
+type ChildrenGroup = Literal[ "none", "one", "two", "three", "four", "5-to-10", "over-10" ]
+type Percentile = Literal[ "10th", "25th", "50th", "75th", "90th", "95th", "99th" ]
+type WealthSpread = Literal[ "1", "2", "5", "10", "20", "50", "100", "200", "500", "1000" ]
+
+type FilterSpecial = Literal[ "deceased", "dropOff", "family", "selfMade" ]
+type FilterGroup = Literal[
+    "industry", "citizenship", "country", "state", "gender", "age", "maritalStatus",
+    "special"
+]
+
+type Service = Literal[ "profile", "list", "mover", "filter", "stats", "system" ]
+type StatusFlag = Literal[ "healthy", "degraded", "maintenance", "outage", "unknown" ]
+type ProfileStatusFlag = Literal[ "healthy", "invalid", "missing", "unknown" ]
+
+MetaData = TypedDict( "MetaData", {
+    "schemaVersion": Literal[ "2" ],
+    "generator": str,
+    "lastModified": str
+} )
+
+DateIndex = TypedDict( "DateIndex", {
+    "$metadata": MetaData,
+    "dates": list[ str ],
+    "latest": NotRequired[ str ]
+} )
+
+Location = TypedDict( "Location", {
+    "country": str,
+    "state": NotRequired[ str ],
+    "city": NotRequired[ str ]
+} )
+
+Education = TypedDict( "Education", {
+    "school": str,
+    "degree": NotRequired[ str ]
+} )
+
+Organization = TypedDict( "Organization", {
+    "name": str,
+    "title": NotRequired[ str ]
+} )
+
+SelfMade = TypedDict( "SelfMade", {
+    "type": NotRequired[ str ],
+    "is": bool,
+    "rank": NotRequired[ SelfMadeRank ]
+} )
+
+Relation = TypedDict( "Relation", {
+    "type": RelationType,
+    "name": str,
+    "relation": NotRequired[ str ],
+    "uri": NotRequired[ str ]
+} )
+
+Image = TypedDict( "Image", {
+    "url": str,
+    "credits": str,
+    "file": str,
+    "thumb": NotRequired[ str ],
+    "caption": NotRequired[ str ],
+    "desc": NotRequired[ str ],
+    "date": NotRequired[ str ]
+} )
+
+Wiki = TypedDict( "Wiki", {
+    "uri": str,
+    "pageId": int,
+    "refId": int,
+    "confidence": float,
+    "name": str,
+    "lastModified": str,
+    "summary": list[ str ],
+    "sortKey": NotRequired[ str ],
+    "wikidata": NotRequired[ str ],
+    "desc": NotRequired[ str ],
+    "image": NotRequired[ Image ]
+} )

rtbnext/schema/list.py

@@ -0,0 +1,64 @@
+"""
+List
+
+Declares types for ranking lists and snapshots.
+"""
+
+from typing import NotRequired, TypedDict
+
+from rtbnext.schema.assets import ChangeItem
+from rtbnext.schema.generic import ChangeFlag, Gender, Industry, MetaData, SelfMadeRank
+
+ListIndexItem = TypedDict( "ListIndexItem", {
+    "uri": str,
+    "name": str,
+    "text": str,
+    "shortName": str,
+    "desc": str,
+    "columns": list[ str ],
+    "filters": list[ str ]
+} )
+
+ListIndex = TypedDict( "ListIndex", {
+    "$metadata": MetaData,
+    "count": int,
+    "items": list[ ListIndexItem ]
+} )
+
+ListItem = TypedDict( "ListItem", {
+    "uri": str,
+    "sourceUri": str,
+    "name": str,
+    "rank": int,
+    "networth": NotRequired[ float ],
+    "industry": NotRequired[ Industry ],
+    "source": NotRequired[ list[ str ] ],
+    "gender": NotRequired[ Gender ],
+    "age": NotRequired[ int ],
+    "citizenship": NotRequired[ str ],
+    "flag": NotRequired[ ChangeFlag ],
+    "rankDiff": NotRequired[ int ],
+    "selfMadeRank": NotRequired[ SelfMadeRank ],
+    "philanthropyScore": NotRequired[ int ],
+    "today": NotRequired[ ChangeItem ],
+    "ytd": NotRequired[ ChangeItem ]
+} )
+
+ListStats = TypedDict( "ListStats", {
+    "date": str,
+    "count": int,
+    "total": float,
+    "woman": int,
+    "quota": float,
+    "today": NotRequired[ ChangeItem ],
+    "ytd": NotRequired[ ChangeItem ]
+} )
+
+List = TypedDict( "List", {
+    "$metadata": MetaData,
+    "uri": str,
+    "date": str,
+    "count": int,
+    "items": list[ ListItem ],
+    "stats": ListStats
+} )