rtbnext 1.0.0__tar.gz

rtbnext-1.0.0/.gitignore

@@ -0,0 +1,3 @@
+.venv/
+__pycache__/
+dist/

rtbnext-1.0.0/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.

rtbnext-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,128 @@
+# 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/pyproject.toml

@@ -0,0 +1,103 @@
+[build-system]
+build-backend = "hatchling.build"
+requires = [
+    "hatchling >= 1.27"
+]
+
+[project]
+name = "rtbnext"
+version = "1.0.0"
+description = "Official Python SDK for the RTBNext API."
+readme = "README.md"
+license = "MIT"
+requires-python = ">= 3.12"
+
+authors = [
+    { name = "Paul Köhler (komed3)", email = "webmaster@komed3.de" }
+]
+
+keywords = [
+    "rtbnext",
+    "billionaires",
+    "api",
+    "sdk"
+]
+
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Typing :: Typed"
+]
+
+dependencies = [
+    "httpx >= 0.28"
+]
+
+[project.urls]
+Homepage = "https://rtbnext.de"
+Documentation = "https://sdk.rtbnext.de"
+Repository = "https://github.com/rtbnext/sdk-python"
+"Bug Tracker" = "https://github.com/rtbnext/sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "build >= 1.5",
+    "hatchling >= 1.27",
+    "twine >= 7.0",
+    "pylint >= 4.0",
+    "isort >= 8.0",
+    "pre-commit >= 4.6"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/rtbnext"
+]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/rtbnext",
+    "LICENSE",
+    "README.md"
+]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/rtbnext/py.typed" = "rtbnext/py.typed"
+
+[tool.pylint]
+ignore = [
+    "examples",
+    ".venv",
+    "node_modules",
+    "__pycache__"
+]
+
+[tool.pylint.design]
+min-public-methods = 0
+max-attributes = 12
+max-args = 12
+
+[tool.pylint.messages_control]
+disable = [
+    "duplicate-code",
+    "unnecessary-ellipsis"
+]
+
+[tool.isort]
+profile = "black"
+multi_line_output = 5
+include_trailing_comma = false
+line_length = 100
+skip = [
+    "examples",
+    ".venv",
+    "node_modules",
+    "__pycache__"
+]

rtbnext-1.0.0/src/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-1.0.0/src/rtbnext/_version.py

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

rtbnext-1.0.0/src/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()