rtbnext 1.0.0__py3-none-any.whl

rtbnext/resource/base.py

@@ -0,0 +1,206 @@
+"""
+Base Resource
+
+Implements the base resource wrapper for HTTP responses.
+Resource instance pooling is intended to optimize memory allocation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Awaitable, Callable, Generic, Self, TypeVar
+
+from rtbnext.core.http_client import HttpHeader
+from rtbnext.core.loader import ResourceState, ResourceStateLoader
+from rtbnext.core.parser import ParserFn
+from rtbnext.core.rate_limiter import RateLimitMode
+from rtbnext.defaults import DEFAULT_RATE_LIMIT_MODE
+
+D = TypeVar( "D" )
+R = TypeVar( "R", bound= "Resource[ Any ]" )
+
+type TransformFn[ D ] = Callable[ [ D ], Awaitable[ Any ] | Any ]
+
+_EMPTY_HOOKS: frozenset = frozenset()
+
+
+class Resource( Generic[ D ] ):
+    """
+    Base resource wrapper for lazy loading, parsing and cache state management.
+
+    Resources are loaded only when data is requested. Loaded responses are kept
+    as resource state while parsed values are cached separately.
+    """
+
+    def __init__( self, path: str, loader: ResourceStateLoader, parser: ParserFn[ D ] ) -> None:
+        self._path, self._loader, self._parser = path, loader, parser
+
+        self._hooks: dict[ str, set[ Callable[ [ Self ], None ] ] ] = {}
+
+        self._state: ResourceState | None = None
+        self._loading: asyncio.Task[ None ] | None = None
+        self._loaded = False
+
+        self._parsed = False
+        self._value: D | None = None
+
+        self._transformed: Any | Awaitable[ Any ] | None = None
+
+    def _emit( self, *events: str ) -> None:
+        """Emits lifecycle events."""
+
+        for event in events:
+            for handler in self._hooks.get( event, _EMPTY_HOOKS ):
+                handler( self )
+
+    def _reset( self ) -> None:
+        """Resets parsed values after loading or refreshing."""
+
+        self._parsed = False
+        self._value = None
+        self._transformed = None
+
+    def _parse( self ) -> D:
+        """Parses the loaded HTTP response."""
+
+        if self._state is None:
+            raise RuntimeError( "Resource has not been loaded." )
+
+        self._value = self._parser( self._state.response )
+        self._parsed = True
+        self._emit( "parse" )
+
+        return self._value
+
+    async def _transform( self, fn: TransformFn[ D ] ) -> Any:
+        """Transforms parsed resource data and cache the result."""
+
+        if self._transformed is None:
+            async def execute () -> Any:
+                value = fn( await self.data() )
+
+                if asyncio.iscoroutine( value ):
+                    value = await value
+
+                self._transformed = value
+                self._emit( "transform" )
+
+                return value
+
+            self._transformed = asyncio.create_task( execute() )
+
+        return await self._transformed
+
+    def _value_or_raise( self ) -> D:
+        """Returns the parsed resource value or raise an error if unavailable."""
+
+        if self._value is None:
+            raise RuntimeError( "Resource value unavailable." )
+
+        return self._value
+
+    def on( self, event: str, handler: Callable[ [ Self ], None ] ) -> Self:
+        """Registers an event handler."""
+
+        self._hooks.setdefault( event, set() ).add( handler )
+        return self
+
+    def off( self, event: str, handler: Callable[ [ Self ], None ] ) -> Self:
+        """Removes an event handler."""
+
+        self._hooks.get( event, set() ).discard( handler )
+        return self
+
+    @property
+    def valid( self ) -> bool:
+        """Returns whether the current resource state is still valid."""
+
+        return not self._loaded or self._state is None or self._loader.valid( self._state )
+
+    async def load(
+        self, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> None:
+        """Loads the resource if it has not already been loaded."""
+
+        if self._loaded:
+            return
+
+        if self._loading is None:
+            async def execute() -> None:
+                try:
+                    self._state = await self._loader.load(
+                        self._path, headers= headers, mode= mode, timeout= timeout
+                    )
+
+                    self._loaded = True
+                    self._reset()
+                    self._emit( "load", "update" )
+
+                finally:
+                    self._loading = None
+
+            self._loading = asyncio.create_task( execute() )
+
+        await self._loading
+
+    async def refresh(
+        self, *,
+        headers: HttpHeader = None,
+        mode: RateLimitMode = DEFAULT_RATE_LIMIT_MODE,
+        timeout: float | None = None
+    ) -> None:
+        """Refreshes the resource from the network."""
+
+        self._state = await self._loader.refresh(
+            self._path, headers= headers, mode= mode, timeout= timeout
+        )
+
+        self._loaded = True
+        self._reset()
+        self._emit( "refresh", "update" )
+
+    async def data( self ) -> D:
+        """Returns parsed resource data."""
+
+        await self.load()
+        return self._parse() if not self._parsed else self._value_or_raise()
+
+
+class ResourcePool( Generic[ R ] ):
+    """
+    Stores and reuses resource instances by their resource path.
+
+    Valid resources are reused, while invalid resources are replaced with
+    newly created instances.
+    """
+
+    def __init__( self ) -> None:
+        self._resources: dict[ str, R ] = {}
+
+    def get( self, path: str, factory: Callable[ [], R ] ) -> R:
+        """Returns an existing valid resource or create a new one."""
+
+        if ( res := self._resources.get( path ) ) and res.valid:
+            return res
+
+        self._resources[ path ] = res = factory()
+        return res
+
+    @property
+    def size( self ) -> int:
+        """Returns the number of pooled resources."""
+
+        return len( self._resources )
+
+    def delete( self, path: str ) -> None:
+        """Deletes a resource from the cache by path."""
+
+        self._resources.pop( path, None )
+
+    def clear( self ) -> None:
+        """Removes all pooled resources."""
+
+        self._resources.clear()

rtbnext/resource/collectable.py

@@ -0,0 +1,201 @@
+"""
+Collectable Resource
+
+Implements the resource wrapper for collectable endpoints.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Callable, Generic, Self, TypedDict, TypeVar
+
+from rtbnext.core.loader import ResourceStateLoader
+from rtbnext.core.parser import ParserFn
+from rtbnext.resource.base import Resource
+from rtbnext.resource.collection import CursorCollectionBase, ItemFactory
+from rtbnext.utils import sanitize
+
+CollectItem = TypedDict( "CollectItem", { "uri": str } )
+
+class CollectData[ T: CollectItem ]( TypedDict ):
+    """Ensure `items` is a list of collect items."""
+    items: list[ T ]
+
+
+D = TypeVar( "D", bound= CollectData )
+I = TypeVar( "I", bound= CollectItem )
+E = TypeVar( "E" )
+K = TypeVar( "K" )
+
+type EntityFn[ I, E ] = ItemFactory[ I, E ]
+type FindFn[ I ] = Callable[ [ list[ I ], str ], I | None ]
+type SearchFn[ I ] = Callable[ [ I, str, list[ str ] ], bool ]
+
+
+class CollectCollection( CursorCollectionBase[ I, E ], Generic[ I, E ] ):
+    """
+    Collection wrapper for entity-based resources.
+
+    This class extends the cursor-based collection with searching,
+    filtering, grouping, sorting and set operations.
+    """
+
+    def __init__(
+        self, items: list[ I ], *,
+        factory: EntityFn[ I, E ],
+        total: int | None = None,
+        find: FindFn[ I ] | None = None,
+        search: SearchFn[ I ] | None = None
+    ) -> None:
+        super().__init__( items, factory= factory, total= total )
+
+        self._find = find or self._default_find
+        self._search = search or self._default_search
+
+    @staticmethod
+    def _default_find( items: list[ I ], uri_like: str ) -> I | None:
+        """Returns the first item matching a URI-like string."""
+
+        uri = sanitize( uri_like )
+        return next( ( item for item in items if item[ "uri" ] == uri ), None )
+
+    @staticmethod
+    def _default_search( item: I, query: str, terms: list[ str ] ) -> bool:
+        """Returns whether an item matches a search query."""
+
+        name = item.get( "searchName" ) or sanitize( item.get( "name", "" ) )
+        text = item.get( "text", "" )
+
+        return (
+            query in name or query in text
+            or all( term in name or term in text for term in terms )
+        )
+
+    def _clone( self, items: list[ I ] ) -> Self:
+        """Creates a new collection preserving configuration."""
+
+        return self.__class__(
+            items, factory= self._factory, total= self._total,
+            find= self._find, search= self._search
+        )
+
+    def get( self, uri: str ) -> E | None:
+        """Returns an item by its exact URI."""
+
+        return next( (
+            self._factory( item ) for item in self._items if item[ "uri" ] == uri
+        ), None )
+
+    def filter( self, predicate: Callable[ [ I ], bool ] ) -> Self:
+        """Returns items matching a predicate."""
+
+        return self._clone( [ item for item in self._items if predicate( item ) ] )
+
+    def find( self, uri_like: str ) -> E | None:
+        """Returns the first matching URI-like item."""
+
+        if item := self._find( self._items, uri_like ):
+            return self._factory( item )
+
+        return None
+
+
+    def search( self, query: str ) -> Self:
+        """Returns items matching a search query."""
+
+        query, terms = sanitize( query ), query.split()
+
+        return self._clone( [
+            item for item in self._items
+            if self._search( item, query, terms )
+        ] )
+
+    def intersect( self, other: Self ) -> Self:
+        """Returns items also contained in another collection."""
+
+        uris = { item[ "uri" ] for item in other.items }
+        return self._clone( [ item for item in self._items if item[ "uri" ] in uris ] )
+
+    def exclude( self, other: Self ) -> Self:
+        """Returns items not contained in another collection."""
+
+        uris = { item[ "uri" ] for item in other.items }
+        return self._clone( [ item for item in self._items if item[ "uri" ] not in uris ] )
+
+    def union( self, other: Self ) -> Self:
+        """Returns the union of two collections."""
+
+        seen: set[ str ] = set()
+        merged: list[ I ] = []
+
+        for item in [ *self._items, *other.items ]:
+            if item[ "uri" ] not in seen:
+                seen.add( item[ "uri" ] )
+                merged.append( item )
+
+        return self._clone( merged )
+
+    def group_by( self, callback: Callable[ [ I ], K ] ) -> dict[ K, Self ]:
+        """Groups items using a callback."""
+
+        groups: defaultdict[ K, list[ I ] ] = defaultdict( list )
+
+        for item in self._items:
+            groups[ callback( item ) ].append( item )
+
+        return {
+            key: self._clone( values )
+            for key, values in groups.items()
+        }
+
+    def order_by( self, key: str, descending: bool = False ) -> Self:
+        """Returns items ordered by a dictionary key."""
+
+        return self._clone( sorted(
+            self._items,
+            key= lambda item: ( item.get( key ) is None, item.get( key ) ),
+            reverse= descending
+        ) )
+
+    def sort(
+        self, *,
+        key: Callable[ [ I ], str | int | float | bool ],
+        reverse: bool = False
+    ) -> Self:
+        """Returns items sorted using a custom key."""
+
+        return self._clone( sorted( self._items, key= key, reverse= reverse ) )
+
+
+class CollectableResource( Resource[ D ], Generic[ D, I, E ] ):
+    """
+    Resource wrapper for collection-oriented endpoints.
+
+    This class converts raw API items into entity objects and exposes them
+    through a lazily created collection supporting filtering, searching,
+    sorting and paging operations.
+    """
+
+    def __init__(
+        self, path: str, loader: ResourceStateLoader, parser: ParserFn[ D ], *,
+        entity: EntityFn[ I, E ],
+        find: FindFn[ I ] | None = None,
+        search: SearchFn[ I ] | None = None
+    ) -> None:
+        super().__init__( path, loader, parser )
+
+        self._entity = entity
+        self._find = find
+        self._search = search
+
+    def _collect( self, items: list[ I ] ) -> CollectCollection[ I, E ]:
+        """Creates a collection from collectable items."""
+
+        return CollectCollection(
+            items, factory= self._entity, find= self._find, search= self._search
+        )
+
+    async def collection( self ) -> CollectCollection[ I, E ]:
+        """Returns the collection."""
+
+        return await self._transform( lambda data: self._collect( data[ "items" ] ) )