rtbnext 1.0.0__py3-none-any.whl

rtbnext/endpoint/base.py

@@ -0,0 +1,80 @@
+"""
+Base Endpoint
+
+Implements the base endpoint class.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from rtbnext.core.loader import ResourceStateLoader
+from rtbnext.core.parser import Parser, ParserFn, ParserMode, parser
+from rtbnext.resource.base import Resource, ResourcePool
+from rtbnext.resource.collectable import CollectableResource, EntityFn, FindFn, SearchFn
+from rtbnext.resource.dateable import DateableResource, DateFn
+from rtbnext.resource.indexable import IndexableResource, IndexFn, KeysFn
+from rtbnext.resource.series import PointFn, TimeSeriesResource, TimeSeriesRow
+
+if TYPE_CHECKING:
+    from rtbnext.rtbnext import Endpoints
+
+
+class EndpointBase:
+    """
+    Base class for all API endpoints.
+
+    Provides shared resource factory helpers for basic, collectable,
+    indexable, time series, and dateable resources.
+    """
+
+    def __init__(
+        self,
+        loader: ResourceStateLoader,
+        pool: ResourcePool,
+        endpoints: Endpoints
+    ) -> None:
+        self._loader, self._pool, self._endpoints = loader, pool, endpoints
+
+    def _resource( self, path: str, mode: ParserMode = "json" ) -> Resource:
+        """Returns a basic resource."""
+
+        return self._pool.get( path, lambda: Resource( path, self._loader, parser( mode ) ) )
+
+    def _collectable(
+        self, path: str, *,
+        entity: EntityFn,
+        find: FindFn | None = None,
+        search: SearchFn | None = None
+    ) -> CollectableResource:
+        """Returns a collectable resource."""
+
+        return self._pool.get( path, lambda: CollectableResource(
+            path, self._loader, Parser.json, entity= entity, find= find, search= search
+        ) )
+
+    def _dateable( self, path: str, *, date: DateFn ) -> DateableResource:
+        """Returns a dateable resource."""
+
+        return self._pool.get( path, lambda: DateableResource(
+            path, self._loader, Parser.json, date= date
+        ) )
+
+    def _indexable(
+        self, path: str, *,
+        index: IndexFn,
+        keys: KeysFn | None = None
+    ) -> IndexableResource:
+        """Returns a indexable resource."""
+
+        return self._pool.get( path, lambda: IndexableResource(
+            path, self._loader, Parser.json, index= index, keys= keys
+        ) )
+
+    def _series( self, path: str, *, point: PointFn ) -> TimeSeriesResource:
+        """Returns a time series resource."""
+
+        return self._pool.get( path, lambda: TimeSeriesResource(
+            path, self._loader, cast( ParserFn[ list[ TimeSeriesRow ] ], Parser.csv ),
+            point= point
+        ) )

rtbnext/endpoint/filter.py

@@ -0,0 +1,112 @@
+"""
+Filter Endpoint
+
+Provides access to filter collections for special categories,
+demographics, and indices.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.endpoint.profile import ProfileEntity
+from rtbnext.resource.collectable import CollectableResource
+from rtbnext.resource.indexable import IndexableResource
+from rtbnext.schema.filter import Filter, FilterIndex, FilterItem
+from rtbnext.schema.generic import AgeGroup, Gender, Industry, MaritalStatus
+from rtbnext.utils import sanitize
+
+type FilterCollection = CollectableResource[ Filter, FilterItem, ProfileEntity[ FilterItem ] ]
+
+FilterIndexTree = TypedDict( "FilterIndexTree", {
+    "industry": dict[ Industry, FilterCollection ],
+    "citizenship": dict[ str, FilterCollection ],
+    "country": dict[ str, FilterCollection ],
+    "state": dict[ str, FilterCollection ],
+    "gender": dict[ Gender, FilterCollection ],
+    "age": dict[ AgeGroup, FilterCollection ],
+    "maritalStatus": dict[ MaritalStatus, FilterCollection ],
+    "special": dict[ str, FilterCollection ]
+} )
+
+
+class FilterEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for filter resources.
+
+    Provides access to filter collections for special categories,
+    demographics, and indices.
+    """
+
+    def _filter( self, path: str ) -> FilterCollection:
+        """Creates a filter collection using the profile endpoint's collection builder."""
+
+        return self._endpoints.profile.collect( path )
+
+    @property
+    def deceased( self ) -> FilterCollection:
+        """Returns the filter collection for deceased profiles."""
+
+        return self._filter( "v2/filter/special/deceased.json" )
+
+    @property
+    def drop_off( self ) -> FilterCollection:
+        """Returns the filter collection for dropped off profiles."""
+
+        return self._filter( "v2/filter/special/dropOff.json" )
+
+    @property
+    def family( self ) -> FilterCollection:
+        """Returns the filter collection for family profiles."""
+
+        return self._filter( "v2/filter/special/family.json" )
+
+    @property
+    def self_made( self ) -> FilterCollection:
+        """Returns the filter collection for self-made profiles."""
+
+        return self._filter( "v2/filter/special/selfMade.json" )
+
+    def industry( self, key: Industry ) -> FilterCollection:
+        """Returns the filter collection by industry."""
+
+        return self._filter( f"v2/filter/industry/{ sanitize( key ) }.json" )
+
+    def age( self, key: AgeGroup ) -> FilterCollection:
+        """Returns the filter collection by age group."""
+
+        return self._filter( f"v2/filter/age/{ key }.json" )
+
+    def gender( self, key: Gender ) -> FilterCollection:
+        """Returns the filter collection by gender."""
+
+        return self._filter( f"v2/filter/gender/{ sanitize( key ) }.json" )
+
+    def marital_status( self, key: MaritalStatus ) -> FilterCollection:
+        """Returns the filter collection by marital status."""
+
+        return self._filter( f"v2/filter/maritalStatus/{ sanitize( key ) }.json" )
+
+    def citizenship( self, key: str ) -> FilterCollection:
+        """Returns the filter collection by citizenship, indexed by ISO code."""
+
+        return self._filter( f"v2/filter/citizenship/{ key.upper() }.json" )
+
+    def country( self, key: str ) -> FilterCollection:
+        """Returns the filter collection by country, indexed by ISO code."""
+
+        return self._filter( f"v2/filter/country/{ key.upper() }.json" )
+
+    def state( self, key: str ) -> FilterCollection:
+        """Returns the filter collection by U.S. state, indexed by USPS code."""
+
+        return self._filter( f"v2/filter/state/{ key.upper() }.json" )
+
+    @property
+    def index( self ) -> IndexableResource[ FilterIndex, FilterIndexTree ]:
+        """Provides the root filter index resource."""
+
+        return self._indexable( "v2/filter/index.json",
+            index= lambda path: self._filter( f"v2/filter/{ "/".join( path ) }.json" )
+        )

rtbnext/endpoint/list.py

@@ -0,0 +1,85 @@
+"""
+List Endpoint
+
+Provides access to item snapshots, date-indexed list resources,
+and the index listing all available lists.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.endpoint.profile import ProfileEntity
+from rtbnext.resource.collectable import CollectableResource
+from rtbnext.resource.dateable import DateableResource
+from rtbnext.schema.generic import DateIndex
+from rtbnext.schema.list import List, ListIndex, ListIndexItem, ListItem
+from rtbnext.utils import sanitize, ymd
+
+type ListSnapshot = CollectableResource[ List, ListItem, ProfileEntity[ ListItem ] ]
+type ListDateIndex = DateableResource[ DateIndex, ListSnapshot ]
+
+
+class ListEntity:
+    """Lazy entity for list index items."""
+
+    def __init__( self, endpoint: ListEndpoint, item: ListIndexItem ) -> None:
+        self._endpoint, self._item = endpoint, item
+
+    def __getitem__( self, name: str ) -> object:
+        """Forwards unknown properties to the underlying list item."""
+
+        try:
+            return self._item[ name ]
+        except KeyError:
+            raise AttributeError( name ) from None
+
+    @property
+    def raw( self ) -> ListIndexItem:
+        """Returns the raw list item passed to list entity."""
+
+        return self._item
+
+    @property
+    def uri( self ) -> str:
+        """Returns the list URI."""
+
+        return self._item[ "uri" ]
+
+    @cached_property
+    def dates( self ) -> ListDateIndex:
+        """Returns the lazily loaded list date index resource."""
+
+        return self._endpoint.get( self.uri )
+
+
+class ListEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for list resources.
+
+    Provides access to item snapshots, date-indexed list resources,
+    and the index listing all available lists.
+    """
+
+    def snapshot( self, uri: str, date: str ) -> ListSnapshot:
+        """Returns a snapshot collection for a list URI at a specific date."""
+
+        return self._endpoints.profile.collect(
+            f"v2/list/{ sanitize( uri ) }/{ ymd( date ) }.json"
+        )
+
+    def get( self, uri: str ) -> ListDateIndex:
+        """Returns a date-indexed list resource for a list URI."""
+
+        return self._dateable( f"v2/list/{ sanitize( uri ) }/index.json",
+            date= lambda date: self.snapshot( uri, date )
+        )
+
+    @property
+    def index( self ) -> CollectableResource[ ListIndex, ListIndexItem, ListEntity ]:
+        """Returns the root list index resource."""
+
+        return self._collectable( "v2/list/index.json",
+            entity= lambda item: ListEntity( self, item )
+        )

rtbnext/endpoint/mover.py

@@ -0,0 +1,33 @@
+"""
+Mover Endpoint
+
+Provides access to mover snapshots and mover index resources.
+"""
+
+from __future__ import annotations
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.resource.base import Resource
+from rtbnext.resource.dateable import DateableResource
+from rtbnext.schema.generic import DateIndex
+from rtbnext.schema.mover import Mover
+from rtbnext.utils import ymd
+
+
+class MoverEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for mover resources.
+
+    Provides access to mover snapshots and mover index resources.
+    """
+
+    def snapshot( self, date: object ) -> Resource[ Mover ]:
+        """Returns a mover snapshot for a given date."""
+
+        return self._resource( f"v2/mover/{ ymd( date ) }.json" )
+
+    @property
+    def index( self ) -> DateableResource[ DateIndex, Resource[ Mover ] ]:
+        """Returns the root mover index resource."""
+
+        return self._dateable( "v2/mover/index.json", date= self.snapshot )

rtbnext/endpoint/profile.py

@@ -0,0 +1,158 @@
+"""
+Profile Endpoint
+
+Provides access to profile metadata, details, history, index,
+and search index.
+"""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Generic, TypedDict
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.resource.base import Resource
+from rtbnext.resource.collectable import CollectableResource, CollectItem, FindFn, I, SearchFn
+from rtbnext.resource.series import AggregateRange, AggregateValue, TimeSeriesResource
+from rtbnext.schema.profile import (
+    ProfileData, ProfileHistory, ProfileHistoryItem, ProfileIndex, ProfileIndexItem, ProfileMeta,
+    SearchIndex, SearchIndexItem
+)
+from rtbnext.utils import sanitize
+
+ProfileHistoryPoint = TypedDict( "ProfileHistoryPoint", {
+    "date": str,
+    "rank": int,
+    "networth": float,
+    "change": float,
+    "percent": float
+} )
+
+ProfileHistoryAggregatePoint = TypedDict( "ProfileHistoryAggregatePoint", {
+    "date": str,
+    "label": str,
+    "range": AggregateRange,
+    "rank": AggregateValue,
+    "networth": AggregateValue,
+    "change": AggregateValue,
+    "percent": AggregateValue
+} )
+
+type ProfileHistorySeries = TimeSeriesResource[
+    ProfileHistory, ProfileHistoryPoint, ProfileHistoryAggregatePoint
+]
+
+
+class ProfileEntity( Generic[ I ] ):
+    """
+    Lazy profile entity exposing related profile resources.
+
+    Wraps a raw profile item and provides lazy access to its
+    associated metadata, profile data, and history resources.
+    """
+
+    def __init__( self, endpoint: ProfileEndpoint, item: I ) -> None:
+        self._endpoint, self._item = endpoint, item
+
+    def __getitem__( self, name: str ) -> object:
+        """Forwards unknown properties to the underlying profile item."""
+
+        try:
+            return self._item[ name ]
+        except KeyError:
+            raise AttributeError( name ) from None
+
+    @property
+    def raw( self ) -> I:
+        """Returns the raw item passed to profile entity."""
+
+        return self._item
+
+    @property
+    def uri( self ) -> str:
+        """Returns the profile URI."""
+
+        return self._item[ "uri" ]
+
+    @cached_property
+    def meta( self ) -> Resource[ ProfileMeta ]:
+        """Returns the lazily loaded profile metadata resource."""
+
+        return self._endpoint.meta( self.uri )
+
+    @cached_property
+    def data( self ) -> Resource[ ProfileData ]:
+        """Returns the lazily loaded profile data resource."""
+
+        return self._endpoint.data( self.uri )
+
+    @cached_property
+    def history( self ) -> ProfileHistorySeries:
+        """Returns the lazily loaded profile history resource."""
+
+        return self._endpoint.history( self.uri )
+
+
+class ProfileEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for profile resources.
+
+    Provides access to profile metadata, details, history,
+    index, and search index.
+    """
+
+    def _point( self, point: ProfileHistoryItem ) -> ProfileHistoryPoint:
+        """Converts a raw profile history row into a typed history point."""
+
+        date, rank, ntw, change, pct = point
+        return { "date": date, "rank": rank, "networth": ntw, "change": change, "percent": pct }
+
+    def _entity( self, item: I ) -> ProfileEntity[ I ]:
+        """Creates a profile entity with lazy-loaded related resources."""
+
+        return ProfileEntity( self, item )
+
+    def collect(
+        self, path: str, *,
+        find: FindFn[ I ] | None = None,
+        search: SearchFn[ I ] | None = None
+    ) -> CollectableResource:
+        """Returns a profile collection resource from a JSON endpoint."""
+
+        return self._collectable( path, entity= self._entity, find= find, search= search )
+
+    def meta( self, uri: str ) -> Resource[ ProfileMeta ]:
+        """Returns profile metadata for the given URI."""
+
+        return self._resource( f"v2/profile/{ sanitize( uri ) }/meta.json" )
+
+    def data( self, uri: str ) -> Resource[ ProfileData ]:
+        """Returns profile data for the given URI."""
+
+        return self._resource( f"v2/profile/{ sanitize( uri ) }/profile.json" )
+
+    def history( self, uri: str ) -> ProfileHistorySeries:
+        """Returns profile history time-series data for the given URI."""
+
+        return self._series( f"v2/profile/{ sanitize( uri ) }/history.csv", point= self._point )
+
+    def get( self, uri: str ) -> ProfileEntity[ CollectItem ]:
+        """Returns the profile entity for a URI."""
+
+        return self._entity( CollectItem( uri= sanitize( uri ) ) )
+
+    @property
+    def index( self ) -> CollectableResource[
+        ProfileIndex, ProfileIndexItem, ProfileEntity[ ProfileIndexItem ]
+    ]:
+        """Returns the profile index collection."""
+
+        return self.collect( "v2/profile/index.json" )
+
+    @property
+    def search_index( self ) -> CollectableResource[
+        SearchIndex, SearchIndexItem, ProfileEntity[ SearchIndexItem ]
+    ]:
+        """Returns the profile search index collection."""
+
+        return self.collect( "v2/profile/search.json" )

rtbnext/endpoint/stats.py

@@ -0,0 +1,156 @@
+"""
+Stats Endpoint
+
+Provides access to stats resources, scatter collections, historic
+data, and grouped indices.
+"""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.endpoint.profile import ProfileEntity
+from rtbnext.resource.base import Resource
+from rtbnext.resource.collectable import CollectableResource
+from rtbnext.resource.indexable import IndexableResource
+from rtbnext.resource.series import AggregateRange, AggregateValue, TimeSeriesResource
+from rtbnext.schema.generic import Industry
+from rtbnext.schema.stats import (
+    CitizenshipStatsIndex, DBStats, GlobalStats, History, HistoryItem, IndustryStatsIndex,
+    ProfileStats, Scatter, ScatterItem, Top10, WealthStats
+)
+from rtbnext.utils import sanitize
+
+HistoryPoint = TypedDict( "HistoryPoint", {
+    "date": str,
+    "count": int,
+    "total": float,
+    "woman": int,
+    "quota": float,
+    "change": float,
+    "percent": float
+} )
+
+HistoryAggregatePoint = TypedDict( "HistoryAggregatePoint", {
+    "date": str,
+    "label": str,
+    "range": AggregateRange,
+    "count": AggregateValue,
+    "total": AggregateValue,
+    "woman": AggregateValue,
+    "quota": AggregateValue,
+    "change": AggregateValue,
+    "percent": AggregateValue
+} )
+
+type HistorySeries = TimeSeriesResource[ History, HistoryPoint, HistoryAggregatePoint ]
+type CitizenshipIndexTree = dict[ str, HistorySeries ]
+type IndustryIndexTree = dict[ Industry, HistorySeries ]
+
+
+class StatsEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for stats resources.
+
+    Provides access to stats resources, scatter collections,
+    historic data, and grouped indices.
+    """
+
+    def _point( self, point: HistoryItem ) -> HistoryPoint:
+        """Converts a raw history row into a typed history point."""
+
+        date, count, total, woman, quota, change, percent = point
+
+        return {
+            "date": date, "count": count, "total": total, "woman": woman,
+            "quota": quota, "change": change, "percent": percent
+        }
+
+    def _keys( self, value: object ) -> list[ str ] | None:
+        """Returns available index keys."""
+
+        if not isinstance( value, dict ):
+            return None
+
+        if isinstance( items := value.get( "items" ), dict ):
+            value.clear()
+            value.update( items )
+
+        return [] if "date" in value else list( value.keys() )
+
+    def _group( self, group: Literal[ "industry", "citizenship" ] ) -> IndexableResource:
+        """Builds an industry or citizenship index."""
+
+        return self._indexable( f"v2/stats/{ group }/index.json",
+            index= lambda path: getattr( self, group )( path[ -1 ] ),
+            keys= self._keys
+        )
+
+    @property
+    def db( self ) -> Resource[ DBStats ]:
+        """Returns the database statistics resource."""
+
+        return self._resource( "v2/stats/db.json" )
+
+    @property
+    def global_( self ) -> Resource[ GlobalStats ]:
+        """Returns the global statistics resource."""
+
+        return self._resource( "v2/stats/global.json" )
+
+    @property
+    def profile( self ) -> Resource[ ProfileStats ]:
+        """Returns the profile statistics resource."""
+
+        return self._resource( "v2/stats/profile.json" )
+
+    @property
+    def scatter( self ) -> CollectableResource[
+        Scatter, ScatterItem, ProfileEntity[ ScatterItem ]
+    ]:
+        """Returns the profile scatter stats collection resource."""
+
+        return self._endpoints.profile.collect( "v2/stats/scatter.json" )
+
+    @property
+    def wealth( self ) -> Resource[ WealthStats ]:
+        """Returns the wealth statistics resource."""
+
+        return self._resource( "v2/stats/wealth.json" )
+
+    @property
+    def history( self ) -> HistorySeries:
+        """Returns the historical stats time series resource."""
+
+        return self._series( "v2/stats/history.csv", point= self._point )
+
+    @property
+    def top10( self ) -> Resource[ Top10 ]:
+        """Returns the top 10 billionaires list resource."""
+
+        return self._resource( "v2/stats/top10.json" )
+
+    def industry( self, key: Industry ) -> HistorySeries:
+        """Returns time series for a specific industry."""
+
+        return self._series( f"v2/stats/industry/{ sanitize( key ) }.csv", point= self._point )
+
+    def citizenship( self, key: str ) -> HistorySeries:
+        """Returns time series for a specific citizenship, indexed by ISO code."""
+
+        return self._series( f"v2/stats/citizenship/{ key.upper() }.csv", point= self._point )
+
+    @property
+    def industry_index( self ) -> IndexableResource[ IndustryStatsIndex, IndustryIndexTree ]:
+        """Returns the industry stats index."""
+
+        return self._group( "industry" )
+
+    @property
+    def citizenship_index( self ) -> IndexableResource[
+        CitizenshipStatsIndex, CitizenshipIndexTree
+    ]:
+        """Returns the citizenship stats index."""
+
+        return self._group( "citizenship" )

rtbnext/endpoint/system.py

@@ -0,0 +1,25 @@
+"""
+System Endpoint
+
+Provides access to system status information.
+"""
+
+from __future__ import annotations
+
+from rtbnext.endpoint.base import EndpointBase
+from rtbnext.resource.base import Resource
+from rtbnext.schema.system import SystemStatus
+
+
+class SystemEndpoint( EndpointBase ):
+    """
+    Endpoint implementation for system resources.
+
+    Provides access to system status information.
+    """
+
+    @property
+    def status( self ) -> Resource[ SystemStatus ]:
+        """Returns the current system status resource."""
+
+        return self._resource( "v2/system/status.json" )