rtbnext 1.0.0__py3-none-any.whl

rtbnext/schema/mover.py

@@ -0,0 +1,40 @@
+"""
+Mover
+
+Declares movers as the largest gains and losses over predefined time periods.
+"""
+
+from typing import TypedDict
+
+from rtbnext.schema.assets import ChangeItem
+from rtbnext.schema.generic import MetaData
+
+MoverItem = TypedDict( "MoverItem", {
+    "uri": str,
+    "name": str,
+    "value": float
+} )
+
+MoverEntry = TypedDict( "MoverEntry", {
+    "winner": list[ MoverItem ],
+    "loser": list[ MoverItem ]
+} )
+
+MoverBucket = TypedDict( "MoverBucket", {
+    "total": ChangeItem,
+    "networth": MoverEntry,
+    "percent": MoverEntry
+} )
+
+MoverData = TypedDict( "MoverData", {
+    "date": str,
+    "today": MoverBucket,
+    "ytd": MoverBucket
+} )
+
+Mover = TypedDict( "Mover", {
+    "$metadata": MetaData,
+    "date": str,
+    "today": MoverBucket,
+    "ytd": MoverBucket
+} )

rtbnext/schema/profile.py

@@ -0,0 +1,137 @@
+"""
+Profile
+
+Declares profile records representing individuals, including personal
+information, financial data, relationships, media, and historical statistics.
+"""
+
+from typing import Literal, NotRequired, TypedDict
+
+from rtbnext.schema.assets import Annual, Asset, Performance, Ranking, Realtime
+from rtbnext.schema.generic import (
+    Education, Gender, Image, Industry, Location, MaritalStatus, MetaData, Organization,
+    ProfileStatusFlag, Relation, SelfMade, SelfMadeRank, Wiki
+)
+
+ProfileIndexItem = TypedDict( "ProfileIndexItem", {
+    "uri": str,
+    "name": str,
+    "text": str,
+    "aliases": list[ str ],
+    "desc": NotRequired[ str ],
+    "image": NotRequired[ str ]
+} )
+
+ProfileIndex = TypedDict( "ProfileIndex", {
+    "$metadata": MetaData,
+    "count": int,
+    "items": list[ ProfileIndexItem ]
+} )
+
+SearchIndexItem = TypedDict( "SearchIndexItem", {
+    "id": str,
+    "uri": str,
+    "deceased": bool,
+    "family": bool,
+    "dropOff": bool,
+    "embargo": bool,
+    "searchName": str,
+    "fullName": str,
+    "lastName": str,
+    "gender": NotRequired[ Gender ],
+    "birthDate": NotRequired[ str ],
+    "age": NotRequired[ int ],
+    "birthCountry": NotRequired[ str ],
+    "residenceCountry": NotRequired[ str ],
+    "citizenship": NotRequired[ str ],
+    "industry": NotRequired[ Industry ],
+    "source": NotRequired[ list[ str ] ],
+    "networth": NotRequired[ float ],
+    "rank": NotRequired[ int ],
+    "organization": NotRequired[ str ],
+    "maritalStatus": NotRequired[ MaritalStatus ],
+    "children": NotRequired[ int ],
+    "philanthropyScore": NotRequired[ int ],
+    "selfMade": NotRequired[ bool ],
+    "selfMadeRank": NotRequired[ SelfMadeRank ],
+    "wikidata": NotRequired[ str ],
+    "status": NotRequired[ ProfileStatusFlag ],
+    "score": NotRequired[ float ],
+    "timestamp": str
+} )
+
+SearchIndex = TypedDict( "SearchIndex", {
+    "$metadata": MetaData,
+    "count": int,
+    "items": list[ SearchIndexItem ]
+} )
+
+ProfileStatus = TypedDict( "ProfileStatus", {
+    "status": ProfileStatusFlag,
+    "score": float,
+    "flags": NotRequired[ list[ str ] ]
+} )
+
+ProfileMeta = TypedDict( "ProfileMeta", {
+    "schemaVersion": Literal[ "2" ],
+    "generator": str,
+    "lastModified": str,
+    "lastLookup": NotRequired[ str ],
+    "status": NotRequired[ ProfileStatus ]
+} )
+
+type ProfileHistoryItem = tuple[ str, int, float, float, float ]
+type ProfileHistory = list[ ProfileHistoryItem ]
+
+ProfileFlags = TypedDict( "ProfileFlags", {
+    "deceased": NotRequired[ bool ],
+    "family": NotRequired[ bool ],
+    "dropOff": NotRequired[ bool ],
+    "embargo": NotRequired[ bool ]
+} )
+
+ProfileName = TypedDict( "ProfileName", {
+    "fullName": str,
+    "shortName": str,
+    "lastName": str,
+    "firstName": str
+} )
+
+ProfileInfo = TypedDict( "ProfileInfo", {
+    "flags": ProfileFlags,
+    "name": ProfileName,
+    "gender": Gender,
+    "birthDate": NotRequired[ str ],
+    "birthPlace": NotRequired[ Location ],
+    "citizenship": NotRequired[ str ],
+    "residence": NotRequired[ Location ],
+    "maritalStatus": NotRequired[ MaritalStatus ],
+    "children": NotRequired[ int ],
+    "education": NotRequired[ list[ Education ] ],
+    "industry": Industry,
+    "source": list[ str ],
+    "selfMade": NotRequired[ SelfMade ],
+    "philanthropyScore": NotRequired[ int ],
+    "organization": NotRequired[ Organization ]
+} )
+
+ProfileBio = TypedDict( "ProfileBio", {
+    "cv": list[ str ],
+    "quotes": list[ str ],
+    "facts": list[ str ]
+} )
+
+ProfileData = TypedDict( "ProfileData", {
+    "id": str,
+    "uri": str,
+    "info": ProfileInfo,
+    "bio": ProfileBio,
+    "related": list[ Relation ],
+    "media": list[ Image ],
+    "realtime": NotRequired[ Realtime ],
+    "performance": NotRequired[ Performance ],
+    "ranking": list[ Ranking ],
+    "annual": list[ Annual ],
+    "assets": list[ Asset ],
+    "wiki": NotRequired[ Wiki ]
+} )

rtbnext/schema/stats.py

@@ -0,0 +1,133 @@
+"""
+Stats
+
+Declares statistical data, grouped statistics, historical trends,
+demographic distributions, and wealth analysis.
+"""
+
+from typing import NotRequired, TypedDict
+
+from rtbnext.schema.assets import ChangeItem
+from rtbnext.schema.generic import (
+    AgeGroup, ChangeFlag, ChildrenGroup, Gender, Industry, MaritalStatus, MetaData, Percentile,
+    SelfMadeRank, WealthSpread
+)
+
+StatsData = TypedDict( "StatsData", {
+    "profiles": int,
+    "days": int
+} )
+
+GlobalStats = TypedDict( "GlobalStats", {
+    "$metadata": MetaData,
+    "stats": StatsData,
+    "date": str,
+    "count": int,
+    "total": float,
+    "woman": int,
+    "quota": float,
+    "today": NotRequired[ ChangeItem ],
+    "ytd": NotRequired[ ChangeItem ]
+} )
+
+DBStats = TypedDict( "DBStats", {
+    "$metadata": MetaData,
+    "files": int,
+    "size": int
+} )
+
+type HistoryItem = tuple[ str, int, float, int, float, float, float ]
+type History = list[ HistoryItem ]
+
+AgePyramidGroup = TypedDict( "AgePyramidGroup", {
+    "count": int,
+    "decades": dict[ AgeGroup, int ],
+    "max": int,
+    "min": int,
+    "mean": int
+} )
+
+ChildrenStats = TypedDict( "ChildrenStats", {
+    "full": dict[ str, int ],
+    "short": dict[ ChildrenGroup, int ]
+} )
+
+ProfileStats = TypedDict( "ProfileStats", {
+    "$metadata": MetaData,
+    "gender": dict[ Gender, int ],
+    "maritalStatus": dict[ MaritalStatus, int ],
+    "agePyramid": dict[ Gender, AgePyramidGroup ],
+    "children": ChildrenStats,
+    "selfMade": dict[ SelfMadeRank, int ],
+    "philanthropyScore": dict[ str, int ]
+} )
+
+ScatterItem = TypedDict( "ScatterItem", {
+    "uri": str,
+    "name": str,
+    "gender": Gender,
+    "age": int,
+    "networth": float
+} )
+
+Scatter = TypedDict( "Scatter", {
+    "$metadata": MetaData,
+    "count": int,
+    "items": list[ ScatterItem ]
+} )
+
+WealthStats = TypedDict( "WealthStats", {
+    "$metadata": MetaData,
+    "decades": dict[ AgeGroup, float ],
+    "gender": dict[ Gender, float ],
+    "percentiles": dict[ Percentile, float ],
+    "quartiles": tuple[ float, float, float ],
+    "spread": dict[ WealthSpread, float ],
+    "total": float,
+    "max": float,
+    "min": float,
+    "mean": float,
+    "median": float,
+    "stdDev": float
+} )
+
+Top10Item = TypedDict( "Top10Item", {
+    "uri": str,
+    "name": str,
+    "rank": int,
+    "networth": float,
+    "flag": ChangeFlag
+} )
+
+Top10 = TypedDict( "Top10", {
+    "$metadata": MetaData,
+    "entries": dict[ str, list[ Top10Item ] ]
+} )
+
+StatsIndexFirst = TypedDict( "StatsIndexFirst", {
+    "uri": str,
+    "name": str,
+    "rank": int,
+    "networth": float
+} )
+
+StatsIndexItem = TypedDict( "StatsIndexItem", {
+    "date": str,
+    "count": int,
+    "total": float,
+    "woman": int,
+    "quota": float,
+    "today": NotRequired[ ChangeItem ],
+    "ytd": NotRequired[ ChangeItem ],
+    "first": StatsIndexFirst
+} )
+
+IndustryStatsIndex = TypedDict( "IndustryStatsIndex", {
+    "$metadata": MetaData,
+    "items": dict[ Industry, StatsIndexItem ]
+} )
+
+CitizenshipStatsIndex = TypedDict( "CitizenshipStatsIndex", {
+    "$metadata": MetaData,
+    "items": dict[ str, StatsIndexItem ]
+} )

rtbnext/schema/system.py

@@ -0,0 +1,15 @@
+"""
+System
+
+Declares the system status endpoint type.
+"""
+
+from typing import TypedDict
+
+from rtbnext.schema.generic import MetaData, Service, StatusFlag
+
+SystemStatus = TypedDict( "SystemStatus", {
+    "$metadata": MetaData,
+    "status": StatusFlag,
+    "services": dict[ Service, StatusFlag ]
+} )

rtbnext/utils.py

@@ -0,0 +1,36 @@
+"""
+Utils
+
+Implements internal used utility methods.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+
+
+def sanitize( value: object, delimiter: str = "-" ) -> str:
+    """Sanitize a value for use as a normalized identifier."""
+
+    result = str( value ).strip().lower()
+    result = re.sub( r"[^a-z0-9]+", delimiter, result )
+    result = re.sub( rf"[{ re.escape( delimiter ) }]{{2,}}", delimiter, result )
+
+    return result
+
+
+def ymd( value: object ) -> str:
+    """Convert a value to a UTC date string `YYYY-MM-DD`."""
+
+    text = str( value )
+
+    try:
+        dt = datetime.fromisoformat( text.replace( "Z", "+00:00" ) )
+    except ValueError:
+        dt = datetime.strptime( text, "%Y-%m-%d" )
+
+    if not dt.tzinfo:
+        dt = dt.replace( tzinfo= timezone.utc )
+
+    return dt.astimezone( timezone.utc ).strftime( "%Y-%m-%d" )

rtbnext-1.0.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: rtbnext
+Version: 1.0.0
+Summary: Official Python SDK for the RTBNext API.
+Project-URL: Homepage, https://rtbnext.de
+Project-URL: Documentation, https://sdk.rtbnext.de
+Project-URL: Repository, https://github.com/rtbnext/sdk-python
+Project-URL: Bug Tracker, https://github.com/rtbnext/sdk-python/issues
+Author-email: "Paul Köhler (komed3)" <webmaster@komed3.de>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,billionaires,rtbnext,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Provides-Extra: dev
+Requires-Dist: build>=1.5; extra == 'dev'
+Requires-Dist: hatchling>=1.27; extra == 'dev'
+Requires-Dist: isort>=8.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.6; extra == 'dev'
+Requires-Dist: pylint>=4.0; extra == 'dev'
+Requires-Dist: twine>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# rtbnext
+
+**Official Python SDK for the RTBNext API.**
+
+The RTBNext SDK provides a typed, asynchronous interface for accessing billionaire profiles, lists, filters, statistics, historical data and system information from the [RTBNext API](https://api.rtbnext.de).
+
+The SDK follows a consistent resource-oriented design: resources are loaded lazily, cached according to the configured cache mode, and expose typed helper methods for collections, time series and indexed data.
+
+The package includes Python type information and is compatible with static type checkers such as Pyright, Pylance and mypy.
+
+To find a list of all available API endpoints, please refer to the [API Documentation](https://docs.rtbnext.de). Also visit the [API endpoint](https://api.rtbnext.de) or review the [SDK Documentation](https://sdk.rtbnext.de) for additional details. For updates on current issues or maintenance, please refer to the [System Status](https://status.rtbnext.de).
+
+## Installation
+
+Install the package using pip:
+
+```bash
+pip install rtbnext
+```
+
+## First usage
+
+Every client application **must identify** itself when creating an SDK instance. This information is sent with API requests and helps to provide transparency about API consumers.
+
+```py
+import asyncio
+
+from rtbnext import ClientIdentity, rtbnext
+
+
+async def main() -> None:
+    async with rtbnext(
+        client= ClientIdentity(
+            name= "my-application",
+            version= "1.0.0",
+            contact= "https://example.com/contact"
+        )
+    ) as client:
+
+        stats = await client.stats.global_.data()
+        print( stats["count"] )
+
+
+asyncio.run( main() )
+```
+
+The client identity consists of:
+
+- `name` — application or project name
+- `version` — application version
+- `contact` — optional contact URL
+- `email` — optional contact email address
+
+## Core concepts
+
+### Lazy resources
+
+Resources are not downloaded when they are created. Data is loaded only when it is requested.
+
+```py
+profile = client.profile.get( "bill-gates" )
+
+# No request has been made yet.
+
+data = await profile.meta.data()
+```
+
+### Collections
+
+Collection resources provide filtering, searching, sorting and paging helpers.
+
+```py
+profiles = await client.profile.index.collection()
+
+for profile in profiles.search( "bill" ).order_by( "networth", descending= True ).take( 5 ):
+    print( item.raw["name"], item.raw["uri"] )
+```
+
+### Time series
+
+Historical data can be accessed through typed time-series resources.
+
+```py
+history = await client.profile.get( "bill-gates" ).history.series()
+print( history.latest )
+```
+
+Time series collections support date-based navigation and cursor operations:
+
+```py
+history.seek( "2026-01-01" )
+
+while ( point := history.next ) is not None:
+    print( point["date"], point["networth"] )
+```
+
+## Cache behavior
+
+The SDK includes a configurable resource cache layer that follows HTTP cache semantics. Resources are cached according to the selected cache mode and server-provided cache headers.
+
+Supported cache modes:
+
+- `ttl` — uses the server-defined cache lifetime (`Cache-Control`)
+- `revalidate` — performs conditional requests using validators such as `ETag` and `Last-Modified`
+- `session` — keeps resources during the lifetime of the SDK instance
+
+The SDK does not bypass HTTP cache validation. Expired resources are refreshed according to the configured mode to prevent serving outdated data indefinitely.
+
+A custom cache implementation can be provided by implementing the `Cache` protocol. This allows applications to integrate their own storage solutions, such as databases, filesystem caches or distributed cache systems.
+
+The cache interface requires the following operations:
+
+- retrieve a cached resource state
+- store a resource state
+- delete a resource
+- clear the cache
+- report the current cache size
+
+## Requirements
+
+- Python 3.12+
+- httpx 0.28+
+
+## License
+
+**Copyright © 2026 RTBNext**  
+Created and maintained by [Paul Köhler](https://komed3.de) (komed3).  
+Licensed under the [MIT License](./LICENSE).

rtbnext-1.0.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+rtbnext/__init__.py,sha256=TNXYvCobmVdPAdJbEv7sg7s4F634z_SQi6vXPsAnBp8,685
+rtbnext/_version.py,sha256=KNcBstbtD78JJl8q3nWrUj9jMVJzkBzbN6TgtGK0Krs,88
+rtbnext/defaults.py,sha256=FNGTfDoqszDhtHqKVNJe3992Kx-LjYZry_-K1IUL_w0,586
+rtbnext/rtbnext.py,sha256=iKuTE0YRK04ss_l7toT-P_XocddBW6lDXGdJmEZsOvI,3370
+rtbnext/utils.py,sha256=1QQ0riYcRU34AuppLVsHdVgqulG0GxSTR_pL6UwyoaU,914
+rtbnext/core/cache.py,sha256=mNjGnRuY8l2BSEGL9ELFwMxuf_58u0egKB0Oser0fa4,2749
+rtbnext/core/http_client.py,sha256=SVMjujU4DsR8lx2CkK26L2FxFkM79yBxb9FIZe3o7ok,4740
+rtbnext/core/loader.py,sha256=Qtp3I-cu0eiNZH3XGIYWYemCsFHkn-D4l53WPuruMKA,5891
+rtbnext/core/parser.py,sha256=Q2eqCJSkvtf3MOet-k829Oowvq5YtCNSmq5T4aBsL6E,2501
+rtbnext/core/rate_limiter.py,sha256=CIc-HRb9FxWE32R68CI8dI3yahD1iFp4oQM33VyXE-w,2536
+rtbnext/endpoint/base.py,sha256=cWyVRxjGKwzxYpQjTbjODkGrN-0aCevTlocX30l6NBk,2676
+rtbnext/endpoint/filter.py,sha256=hqdU3qg-VoA946NWhgOTI2htUJB_PwrQ531JMT22jwo,4132
+rtbnext/endpoint/list.py,sha256=QrI9ImPqwyiiGszikTHSY09O9PhMYg5GaeevvH2W5dU,2714
+rtbnext/endpoint/mover.py,sha256=Rd2CQCZT8LcUvp_yB7ITYVvtGE8Ey1BkNn3hFkhne-4,992
+rtbnext/endpoint/profile.py,sha256=eBM5PgpLjQVwxOtkp7jbshzOAnZHALH31nSbPYYKJyE,5135
+rtbnext/endpoint/stats.py,sha256=Of67GFCS9Ko16GgsCQOvyhmq5y_s0yGs-4aet1zzPQs,5129
+rtbnext/endpoint/system.py,sha256=WnFr_MQcGIPpPYisj5GR9HxmPnnIeVvqlPnLQsWixnc,610
+rtbnext/resource/base.py,sha256=bKLu-zcyWmKBnS7fMbEEg2S0ArvbdYuSVLxtEn1JUo4,6321
+rtbnext/resource/collectable.py,sha256=PQExoPRXVxHhIs4FqWIBKVxqxQPfKj6fRV6YCSq9lak,6697
+rtbnext/resource/collection.py,sha256=VF8F4_gmAg0s1B6jn8ozqhxCOW992dZMvbQhb8hNqUg,9404
+rtbnext/resource/dateable.py,sha256=yk8Wh6G6MEuknnO3DLHnUWB3MCc1ahwMSQxFzQRbT_M,1932
+rtbnext/resource/indexable.py,sha256=u7SUQn2FbSv60fuNYhp-NU62WhJkFAbXnlR9wtnkzC0,2872
+rtbnext/resource/series.py,sha256=etCJL0h-A320LIBErdcHVQ5TON6oLDMfVY876etrnsU,8563
+rtbnext/schema/assets.py,sha256=bcyGYut2waodFmG96nwJQU1w_Khe16N9VJDz58Fax9M,2439
+rtbnext/schema/filter.py,sha256=ERXruDd5zr0vPx4lcMHzcF6cszz3kYJ4i9fEoWmEA1Y,790
+rtbnext/schema/generic.py,sha256=y9rV3OnkPD7kkHGl2LeN1To8ajB0_xIG7ERVEsf3A3U,3149
+rtbnext/schema/list.py,sha256=8AFcjmIVoAKOJir8OoTeMQuGS6Roi8vRbGWpyO5WWZs,1586
+rtbnext/schema/mover.py,sha256=qwi17KqFxst5S429THM5hyPNm0qsr6g_QU2myxqNupc,820
+rtbnext/schema/profile.py,sha256=O-lwGCRBjjHaUXzCjfP1167lJUhJQ7e0SahqO_G_Q4U,4019
+rtbnext/schema/stats.py,sha256=6EdtHzTfycbhAniKm6O4bj5-nnm47sRoQ7fHcH1-Ipg,3234
+rtbnext/schema/system.py,sha256=3k7mXHLWGJZbdwO5XUbNwedmq6ORiBSrmaOaQmwpnpw,315
+rtbnext/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rtbnext-1.0.0.dist-info/METADATA,sha256=tkofrQnAZgnxCd7l09HGVN6am33543MnklSgxYDvIpM,5369
+rtbnext-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+rtbnext-1.0.0.dist-info/licenses/LICENSE,sha256=SifktjgxUZpaTEt1-2sH2TWqRQk0n0ZJST47kDI6oAU,1110
+rtbnext-1.0.0.dist-info/RECORD,,

rtbnext-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

rtbnext-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RTBNext by Paul Köhler (komed3)
+
+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.