rtbnext 1.0.0__py3-none-any.whl

rtbnext/resource/collection.py

@@ -0,0 +1,313 @@
+"""
+Base Collections
+
+Implements the base collections shared by resource collections.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Generic, Iterator, Self, TypeVar, cast
+
+from rtbnext.defaults import DEFAULT_PER_PAGE
+from rtbnext.utils import ymd
+
+R = TypeVar( "R" )
+T = TypeVar( "T" )
+U = TypeVar( "U" )
+
+type ItemFactory[ T, R ] = Callable[ [ T ], R ]
+type DateResolver[ T ] = Callable[ [ T ], str ]
+
+
+class CollectionBase( Generic[ T, R ] ):
+    """
+    Provides common immutable collection operations.
+
+    This class serves as a base for resource collections, providing methods to
+    manipulate and access the underlying items while maintaining immutability.
+    """
+
+    def __init__(
+        self, items: list[ T ], *,
+        factory: ItemFactory[ T, R ] = lambda item: cast( R, item ),
+        total: int | None = None
+    ) -> None:
+        self._items, self._factory = items, factory
+        self._total = len( items ) if total is None else total
+
+    def _clone( self, items: list[ T ] ) -> Self:
+        """Creates a new collection instance with replaced items."""
+
+        return self.__class__( items, factory= self._factory, total= self._total )
+
+    def __getitem__( self, index: int ) -> Self | R:
+        return (
+            self._clone( self._items[ index ] )
+            if isinstance( index, slice )
+            else self._factory( self._items[ index ] )
+        )
+
+    def __contains__( self, item: object ) -> bool:
+        return item in self._items
+
+    def __len__( self ) -> int:
+        return self.count
+
+    def __iter__( self ) -> Iterator[ R ]:
+        return map( self._factory, self._items )
+
+    def __reversed__( self ) -> Iterator[ R ]:
+        return map( self._factory, self._items[ ::-1 ] )
+
+    @property
+    def items( self ) -> list[ T ]:
+        """Returns the raw items."""
+
+        return self._items.copy()
+
+    @property
+    def total( self ) -> int:
+        """Returns the total number of available items."""
+
+        return self._total
+
+    @property
+    def count( self ) -> int:
+        """Returns the number of items currently contained."""
+
+        return len( self._items )
+
+    @property
+    def first( self ) -> R | None:
+        """Returns the first item."""
+
+        return None if not self._items else self._factory( self._items[ 0 ] )
+
+    @property
+    def last( self ) -> R | None:
+        """Returns the last item."""
+
+        return None if not self._items else self._factory( self._items[ -1 ] )
+
+    def to_array( self ) -> list[ R ]:
+        """Returns all resolved items as list."""
+
+        return [ self._factory( item ) for item in self._items ]
+
+    def map( self, callback: Callable[ [ R, int ], U ] ) -> list[ U ]:
+        """Maps resolved items."""
+
+        return [ callback( item, index ) for index, item in enumerate( self ) ]
+
+    def reversed( self ) -> Self:
+        """Returns a collection containing reversed items."""
+
+        return self._clone( self._items[ ::-1 ] )
+
+    def take( self, count: int ) -> Self:
+        """Returns a collection containing the first items."""
+
+        return self._clone( self._items[ : count ] )
+
+    def skip( self, count: int ) -> Self:
+        """Returns a collection without the first items."""
+
+        return self._clone( self._items[ count : ] )
+
+    def slice( self, start: int | None = None, end: int | None = None ) -> Self:
+        """Returns a collection containing a sliced range of items."""
+
+        return self._clone( self._items[ start : end ] )
+
+
+class CursorCollectionBase( CollectionBase[ T, R ], Generic[ T, R ] ):
+    """
+    Provides cursor-related immutable collection operations.
+
+    This class extends the base collection adding methods to handle cursor
+    operations for items.
+    """
+
+    def __init__(
+        self, items: list[ T ], *,
+        factory: ItemFactory[ T, R ] = lambda item: cast( R, item ),
+        total: int | None = None
+    ) -> None:
+        super().__init__( items, factory= factory, total= total )
+        self._cursor: int = -1
+
+    @property
+    def position( self ) -> int:
+        """Returns the current cursor position."""
+
+        return self._cursor
+
+    @property
+    def current( self ) -> R | None:
+        """Returns the current resolved item."""
+
+        return self.at( self._cursor )
+
+    @property
+    def next( self ) -> R | None:
+        """Returns the next resolved item."""
+
+        self._cursor += 1
+        return self.at( self._cursor )
+
+    @property
+    def prev( self ) -> R | None:
+        """Returns the previous resolved item."""
+
+        self._cursor -= 1
+        return self.at( self._cursor )
+
+    @property
+    def has_next( self ) -> bool:
+        """Returns whether a next item exists."""
+
+        return self._cursor + 1 < self.count
+
+    @property
+    def has_prev( self ) -> bool:
+        """Returns whether a previous item exists."""
+
+        return self._cursor > 0
+
+    def reset( self ) -> Self:
+        """Resets the cursor."""
+
+        self._cursor = -1
+        return self
+
+    def seek( self, pos: int ) -> Self:
+        """Moves the cursor to a specific index."""
+
+        self._cursor = pos
+        return self
+
+    def at( self, index: int ) -> R | None:
+        """Returns the resolved item at the given index."""
+
+        return self._factory( self._items[ index ] ) if 0 <= index < self.count else None
+
+    def page( self, page: int, per_page: int = DEFAULT_PER_PAGE ) -> Self:
+        """Returns a collection containing one page."""
+
+        start = max( page - 1, 0 ) * per_page
+        return self._clone( self._items[ start : start + per_page ] )
+
+    def pages( self, per_page: int = DEFAULT_PER_PAGE ) -> list[ Self ]:
+        """Returns all pages."""
+
+        return [
+            self._clone( self._items[ i : i + per_page ] )
+            for i in range( 0, self.count, per_page )
+        ]
+
+
+class DateCollectionBase( CursorCollectionBase[ T, R ], Generic[ T, R ] ):
+    """
+    Provides date-related immutable collection operations.
+
+    This class extends the base collection adding special methods dealing with
+    dates, like `year`, `month`, or `between`.
+    """
+
+    def __init__(
+        self, items: list[ T ], *,
+        factory: ItemFactory[ T, R ] = lambda item: cast( R, item ),
+        date: DateResolver[ T ] = lambda item: cast( str, item ),
+        total: int | None = None
+    ) -> None:
+        super().__init__( items, factory= factory, total= total )
+        self._date = date or ( lambda item: item )
+
+    @property
+    def dates( self ) -> list[ str ]:
+        """Returns the resolved date values."""
+
+        return [ self._date( item ) for item in self._items ]
+
+    @property
+    def latest( self ) -> R | None:
+        """Returns the latest dated item."""
+
+        return self.first
+
+    @property
+    def oldest( self ) -> R | None:
+        """Returns the oldest dated item."""
+
+        return self.last
+
+    def seek( self, pos: str ) -> Self:
+        """Moves the cursor to a specific date."""
+
+        target = ymd( pos )
+        self._cursor = next( (
+            index for index, item in enumerate( self._items )
+            if self._date( item ) == target
+        ), -1 )
+
+        return self
+
+    def find( self, date: str ) -> R | None:
+        """Gets the item by exact date."""
+
+        target = ymd( date )
+
+        return next( (
+            self._factory( item ) for item in self._items
+            if self._date( item ) == target
+        ), None )
+
+    def year( self, year: int ) -> Self:
+        """Filters resources by year."""
+
+        prefix = f"{ year }-"
+
+        return self._clone( [
+            item for item in self._items
+            if self._date( item ).startswith( prefix )
+        ] )
+
+    def month( self, year: int, month: int ) -> Self:
+        """Filters resources by month."""
+
+        prefix = f"{ year }-{month:02d}-"
+
+        return self._clone( [
+            item for item in self._items
+            if self._date( item ).startswith( prefix )
+        ] )
+
+    def before( self, date: str ) -> Self:
+        """Returns resources before a date."""
+
+        target = ymd( date )
+        return self._clone( [ item for item in self._items if self._date( item ) < target ] )
+
+    def after( self, date: str ) -> Self:
+        """Returns resources after a date."""
+
+        target = ymd( date )
+        return self._clone( [ item for item in self._items if self._date( item ) > target ] )
+
+    def since( self, date: str ) -> Self:
+        """Returns resources from a date onward."""
+
+        target = ymd( date )
+        return self._clone( [ item for item in self._items if self._date( item ) >= target ] )
+
+    def until( self, date: str ) -> Self:
+        """Returns resources up to a date."""
+
+        target = ymd( date )
+        return self._clone( [ item for item in self._items if self._date( item ) <= target ] )
+
+    def between( self, start: str, end: str ) -> Self:
+        """Returns resources inside a date range."""
+
+        s, e = ymd( start ), ymd( end )
+        return self._clone( [ item for item in self._items if s <= self._date( item ) <= e ] )

rtbnext/resource/dateable.py

@@ -0,0 +1,59 @@
+"""
+Dateable Resource
+
+Implements the resource wrapper for date-indexed endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Generic, 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 DateCollectionBase
+
+DateData = TypedDict( "DateData", { "dates": list[ str ] } )
+
+D = TypeVar( "D", bound= DateData )
+R = TypeVar( "R" )
+
+type DateFn[ R ] = Callable[ [ str ], R ]
+
+
+class DateCollection( DateCollectionBase[ str, R ], Generic[ R ] ):
+    """
+    Collection wrapper for date-indexed resources.
+
+    This class provides convenient filtering and mapping operations for resources
+    that are indexed by date values. It allows for lazy resolution of resources
+    based on their date keys, while maintaining the underlying collection of date
+    strings.
+    """
+
+
+class DateableResource( Resource[ D ], Generic[ D, R ] ):
+    """
+    Resource wrapper for date-indexed endpoints.
+
+    This class provides lazy traversal over API endpoints that are indexed by
+    date values. It allows for convenient access to resources based on their
+    date keys, while maintaining the underlying resource data.
+    """
+
+    def __init__(
+        self, path: str, loader: ResourceStateLoader, parser: ParserFn[ D ], *,
+        date: DateFn[ R ]
+    ) -> None:
+        super().__init__( path, loader, parser )
+        self._date = date
+
+    def _collect_dates( self, dates: list[ str ] ) -> DateCollection[ R ]:
+        """Creates a date collection."""
+
+        return DateCollection( dates, factory= self._date )
+
+    async def get( self ) -> DateCollection[ R ]:
+        """Returns the indexed date collection."""
+
+        return await self._transform( lambda data: self._collect_dates( data[ "dates" ][ ::-1 ] ) )

rtbnext/resource/indexable.py

@@ -0,0 +1,91 @@
+"""
+Indexable Resource
+
+Implement the resource wrapper for nested indexable endpoints.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Generic, TypeVar
+
+from rtbnext.core.loader import ResourceStateLoader
+from rtbnext.core.parser import ParserFn
+from rtbnext.resource.base import Resource
+
+D = TypeVar( "D" )
+R = TypeVar( "R" )
+
+type Path = tuple[ str, ... ]
+type IndexFn[ R ] = Callable[ [ Path ], R ]
+type KeysFn = Callable[ [ object ], list[ str ] | None ]
+
+
+class _IndexAccessor( Generic[ R ] ):
+    """Lazy accessor object for index traversal."""
+
+    def __init__( self, factory: IndexFn[ R ], keys: KeysFn, path: Path, value: object ) -> None:
+        self._factory, self._keys, self._path, self._value = factory, keys, path, value
+
+    def __getitem__( self, key: str ) -> R | _IndexAccessor[ R ]:
+        """Resolves a nested index key."""
+
+        available = self._keys( self._value )
+
+        if available is None or key not in available:
+            raise AttributeError( f"Unknown index key: { key }" )
+
+        path = ( *self._path, key )
+
+        if isinstance( self._value, dict ) and self._keys( child := self._value[ key ] ):
+            return _IndexAccessor( self._factory, self._keys, path, child )
+
+        return self._factory( path )
+
+    def __dir__( self ) -> list[ str ]:
+        """Returns available index keys."""
+
+        return sorted( [ *super().__dir__(), *( self._keys( self._value ) or [] ) ] )
+
+
+class IndexableResource( Resource[ D ], Generic[ D, R ] ):
+    """
+    Resource wrapper for nested indexable endpoints.
+
+    This class provides lazy traversal over API indexes by exposing generated
+    accessors for nested keys.
+
+    The underlying resource data is loaded only once and transformed into a
+    reusable accessor tree.
+    """
+
+    def __init__(
+        self, path: str, loader: ResourceStateLoader, parser: ParserFn[ D ], *,
+        index: IndexFn[ R ],
+        keys: KeysFn | None = None
+    ) -> None:
+        super().__init__( path, loader, parser )
+
+        self._factory = index
+        self._keys = keys or self._default_keys
+
+    @staticmethod
+    def _default_keys( value: object ) -> list[ str ] | None:
+        """Extracts keys from common index structures."""
+
+        if isinstance( value, dict ):
+            return list( value.keys() )
+
+        if isinstance( value, list ):
+            return [ str( item ) for item in value ]
+
+        return None
+
+    def _traverse( self, value: object, path: Path = () ) -> _IndexAccessor[ R ]:
+        """Creates the lazy accessor tree."""
+
+        return _IndexAccessor( self._factory, self._keys, path, value )
+
+    async def get( self ) -> R:
+        """Returns the lazily generated index tree."""
+
+        return await self._transform( self._traverse )