Skip to content

Library Provider API

AniBridge library provider base package.

HistoryEntry dataclass

User history event for a library item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
261
262
263
264
265
266
@dataclass(frozen=True, slots=True)
class HistoryEntry:
    """User history event for a library item."""

    library_key: str
    viewed_at: datetime  # Must be timezone-aware

LibraryEntity dataclass

Bases: ABC

Base class for library entities.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
@dataclass(slots=True, eq=False)
class LibraryEntity[ProviderT: LibraryProvider](ABC):
    """Base class for library entities."""

    _provider: ProviderT = field(repr=False, compare=False)
    _key: str
    _title: str = field(compare=False)
    _media_kind: MediaKind

    @property
    def key(self) -> str:
        """Return the unique key for this entity."""
        return self._key

    @property
    def media_kind(self) -> MediaKind:
        """Return the high-level media kind of this entity."""
        return self._media_kind

    def provider(self) -> ProviderT:
        """Return the provider associated with this entity."""
        return self._provider

    @property
    def title(self) -> str:
        """Return the entity title."""
        return self._title

    def __hash__(self) -> int:
        """Compute a hash based on provider namespace, class name, and key."""
        return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

    def __eq__(self, other: object) -> bool:
        """Compare entities by provider namespace and key."""
        if other.__class__ is not self.__class__:
            return NotImplemented
        other_ent = cast(LibraryEntity, other)
        return (
            getattr(self._provider, "NAMESPACE", None)
            == getattr(other_ent._provider, "NAMESPACE", None)
            and self.key == other_ent.key
        )

    def __repr__(self) -> str:
        """Return a short representation for debugging."""
        return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

title property

Return the entity title.

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

LibraryEntry dataclass

Bases: LibraryEntity[ProviderT], ABC

Base class for library entries.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
class LibraryEntry[ProviderT: LibraryProvider](LibraryEntity[ProviderT], ABC):
    """Base class for library entries."""

    @abstractmethod
    async def history(self) -> Sequence[HistoryEntry]:
        """Return user history entries for this media item (tz-aware timestamps)."""
        ...

    @abstractmethod
    def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
        """Return possible mapping descriptors for the media item.

        The returned descriptors refer to providers in the mapping database. They are
        not related to the library provider of this item (although, they might match).
        """
        ...

    @abstractmethod
    def media(self) -> LibraryMedia[ProviderT]:
        """Return the media item associated with this entry."""
        ...

    @property
    @abstractmethod
    def on_watching(self) -> bool:
        """Whether the item is on the user's current watching list."""
        ...

    @property
    @abstractmethod
    def on_watchlist(self) -> bool:
        """Whether the item is on the user's watchlist."""
        ...

    @property
    @abstractmethod
    async def review(self) -> str | None:
        """Return the user's review text for this item, if any."""
        ...

    @abstractmethod
    def section(self) -> LibrarySection[LibraryProviderT]:
        """Return the parent library section for this media item."""
        ...

    @property
    @abstractmethod
    def user_rating(self) -> int | None:
        """User rating on a 0-100 scale, or None if not rated."""
        ...

    @property
    @abstractmethod
    def view_count(self) -> int:
        """Total view count for the item (including children)."""
        ...

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

on_watching abstractmethod property

Whether the item is on the user's current watching list.

on_watchlist abstractmethod property

Whether the item is on the user's watchlist.

review abstractmethod async property

Return the user's review text for this item, if any.

title property

Return the entity title.

user_rating abstractmethod property

User rating on a 0-100 scale, or None if not rated.

view_count abstractmethod property

Total view count for the item (including children).

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

history() abstractmethod async

Return user history entries for this media item (tz-aware timestamps).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
117
118
119
120
@abstractmethod
async def history(self) -> Sequence[HistoryEntry]:
    """Return user history entries for this media item (tz-aware timestamps)."""
    ...

mapping_descriptors() abstractmethod

Return possible mapping descriptors for the media item.

The returned descriptors refer to providers in the mapping database. They are not related to the library provider of this item (although, they might match).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
122
123
124
125
126
127
128
129
@abstractmethod
def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
    """Return possible mapping descriptors for the media item.

    The returned descriptors refer to providers in the mapping database. They are
    not related to the library provider of this item (although, they might match).
    """
    ...

media() abstractmethod

Return the media item associated with this entry.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
131
132
133
134
@abstractmethod
def media(self) -> LibraryMedia[ProviderT]:
    """Return the media item associated with this entry."""
    ...

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

section() abstractmethod

Return the parent library section for this media item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
154
155
156
157
@abstractmethod
def section(self) -> LibrarySection[LibraryProviderT]:
    """Return the parent library section for this media item."""
    ...

LibraryEpisode dataclass

Bases: LibraryEntry[LibraryProviderT], ABC

Episode item within a season/show.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
class LibraryEpisode(LibraryEntry[LibraryProviderT], ABC):
    """Episode item within a season/show."""

    index: int
    season_index: int

    @abstractmethod
    def season(self) -> LibrarySeason[LibraryProviderT]:
        """Get the parent season of the episode.

        Returns:
            LibrarySeason: The parent season.
        """
        ...

    @abstractmethod
    def show(self) -> LibraryShow[LibraryProviderT]:
        """Get the parent show of the episode.

        Returns:
            LibraryShow: The parent show.
        """
        ...

    def __repr__(self) -> str:
        """Short representation including show title, season and episode indexes."""
        return (
            f"<{self.__class__.__name__}:{self.key}:{self.show().title[:32]}:"
            f"S{self.season_index:02d}E{self.index:02d}>"
        )

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

on_watching abstractmethod property

Whether the item is on the user's current watching list.

on_watchlist abstractmethod property

Whether the item is on the user's watchlist.

review abstractmethod async property

Return the user's review text for this item, if any.

title property

Return the entity title.

user_rating abstractmethod property

User rating on a 0-100 scale, or None if not rated.

view_count abstractmethod property

Total view count for the item (including children).

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Short representation including show title, season and episode indexes.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
253
254
255
256
257
258
def __repr__(self) -> str:
    """Short representation including show title, season and episode indexes."""
    return (
        f"<{self.__class__.__name__}:{self.key}:{self.show().title[:32]}:"
        f"S{self.season_index:02d}E{self.index:02d}>"
    )

history() abstractmethod async

Return user history entries for this media item (tz-aware timestamps).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
117
118
119
120
@abstractmethod
async def history(self) -> Sequence[HistoryEntry]:
    """Return user history entries for this media item (tz-aware timestamps)."""
    ...

mapping_descriptors() abstractmethod

Return possible mapping descriptors for the media item.

The returned descriptors refer to providers in the mapping database. They are not related to the library provider of this item (although, they might match).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
122
123
124
125
126
127
128
129
@abstractmethod
def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
    """Return possible mapping descriptors for the media item.

    The returned descriptors refer to providers in the mapping database. They are
    not related to the library provider of this item (although, they might match).
    """
    ...

media() abstractmethod

Return the media item associated with this entry.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
131
132
133
134
@abstractmethod
def media(self) -> LibraryMedia[ProviderT]:
    """Return the media item associated with this entry."""
    ...

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

season() abstractmethod

Get the parent season of the episode.

Returns:

Name Type Description
LibrarySeason LibrarySeason[LibraryProviderT]

The parent season.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
235
236
237
238
239
240
241
242
@abstractmethod
def season(self) -> LibrarySeason[LibraryProviderT]:
    """Get the parent season of the episode.

    Returns:
        LibrarySeason: The parent season.
    """
    ...

section() abstractmethod

Return the parent library section for this media item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
154
155
156
157
@abstractmethod
def section(self) -> LibrarySection[LibraryProviderT]:
    """Return the parent library section for this media item."""
    ...

show() abstractmethod

Get the parent show of the episode.

Returns:

Name Type Description
LibraryShow LibraryShow[LibraryProviderT]

The parent show.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
244
245
246
247
248
249
250
251
@abstractmethod
def show(self) -> LibraryShow[LibraryProviderT]:
    """Get the parent show of the episode.

    Returns:
        LibraryShow: The parent show.
    """
    ...

LibraryMedia dataclass

Bases: LibraryEntity[LibraryProviderT], ABC

Base class for library media items.

Implementations should provide concrete behaviour for the abstract properties and methods below.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
class LibraryMedia(LibraryEntity[LibraryProviderT], ABC):
    """Base class for library media items.

    Implementations should provide concrete behaviour for the abstract
    properties and methods below.
    """

    @property
    def external_url(self) -> str | None:
        """URL to the provider's media item, if available."""
        return None

    @property
    def poster_image(self) -> str | None:
        """Primary poster or cover image URL, if available."""
        return None

external_url property

URL to the provider's media item, if available.

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

poster_image property

Primary poster or cover image URL, if available.

title property

Return the entity title.

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

LibraryMovie dataclass

Bases: LibraryEntry[LibraryProviderT], ABC

Movie item in a media library.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
172
173
class LibraryMovie(LibraryEntry[LibraryProviderT], ABC):
    """Movie item in a media library."""

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

on_watching abstractmethod property

Whether the item is on the user's current watching list.

on_watchlist abstractmethod property

Whether the item is on the user's watchlist.

review abstractmethod async property

Return the user's review text for this item, if any.

title property

Return the entity title.

user_rating abstractmethod property

User rating on a 0-100 scale, or None if not rated.

view_count abstractmethod property

Total view count for the item (including children).

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

history() abstractmethod async

Return user history entries for this media item (tz-aware timestamps).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
117
118
119
120
@abstractmethod
async def history(self) -> Sequence[HistoryEntry]:
    """Return user history entries for this media item (tz-aware timestamps)."""
    ...

mapping_descriptors() abstractmethod

Return possible mapping descriptors for the media item.

The returned descriptors refer to providers in the mapping database. They are not related to the library provider of this item (although, they might match).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
122
123
124
125
126
127
128
129
@abstractmethod
def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
    """Return possible mapping descriptors for the media item.

    The returned descriptors refer to providers in the mapping database. They are
    not related to the library provider of this item (although, they might match).
    """
    ...

media() abstractmethod

Return the media item associated with this entry.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
131
132
133
134
@abstractmethod
def media(self) -> LibraryMedia[ProviderT]:
    """Return the media item associated with this entry."""
    ...

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

section() abstractmethod

Return the parent library section for this media item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
154
155
156
157
@abstractmethod
def section(self) -> LibrarySection[LibraryProviderT]:
    """Return the parent library section for this media item."""
    ...

LibraryProvider

Bases: ABC

Abstract base provider that exposes a user media library.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
class LibraryProvider(ABC):
    """Abstract base provider that exposes a user media library."""

    NAMESPACE: ClassVar[str]

    def __init__(self, *, logger: ProviderLogger, config: dict | None = None) -> None:
        """Initialize the provider with optional configuration.

        Args:
            logger (ProviderLogger): Application logger injected by AniBridge.
            config (dict | None): Any configuration options that were detected with the
                provider's namespace as a prefix.
        """
        self.log = logger.getChild(f"library.{self.NAMESPACE}")
        self.config: dict = config or {}

    async def initialize(self) -> None:
        """Asynchronous initialization hook.

        Put any async logic that should be run after construction here.
        """
        return None

    async def clear_cache(self) -> None:
        """Clear any cached data held by the provider.

        For more efficient implementations, it is a good idea to cache data
        fetched from the provider to minimize network requests. AniBridge uses
        this method occasionally to clear such caches.
        """
        return None

    async def close(self) -> None:
        """Close the provider and release resources."""
        return None

    @abstractmethod
    async def get_sections(self) -> Sequence[LibrarySection[LibraryProviderT]]:
        """Return available library sections for the provider.

        Returns:
            Sequence[LibrarySection[LibraryProviderT]]: The available library sections.
        """
        ...

    @abstractmethod
    async def list_items(
        self,
        section: LibrarySection[LibraryProviderT],
        *,
        min_last_modified: datetime | None = None,
        require_watched: bool = False,
        keys: Sequence[str] | None = None,
    ) -> Sequence[LibraryEntry[LibraryProviderT]]:
        """List items in a library section with optional filtering.

        Args:
            section (LibrarySection[LibraryProviderT]): The library section to list
                items from.
            min_last_modified (datetime | None): If provided, only include items
                modified after this timezone-aware timestamp.
            require_watched (bool): If True, only include items marked as watched.
            keys (Sequence[str] | None): If provided, only include items whose keys are
                in this sequence.

        Returns:
            Sequence[LibraryEntry[LibraryProviderT]]: The list of library items.
        """
        ...

    async def parse_webhook(self, request: Request) -> tuple[bool, Sequence[str]]:
        """Parse an incoming webhook and return the affected item keys.

        Args:
            request (Request): The incoming HTTP request.

        Returns:
            tuple[bool, Sequence[str]]: A tuple where the first element indicates
                whether the webhook applies to the current provider, and the second
                element is a sequence of affected item keys.
        """
        return False, ()

    @abstractmethod
    def user(self) -> LibraryUser | None:
        """Return the associated user object, if any.

        Returns:
            LibraryUser | None: The associated user object, if any.
        """
        ...

__init__(*, logger, config=None)

Initialize the provider with optional configuration.

Parameters:

Name Type Description Default
logger ProviderLogger

Application logger injected by AniBridge.

 required
config dict | None

Any configuration options that were detected with the provider's namespace as a prefix.

 None
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
286
287
288
289
290
291
292
293
294
295
def __init__(self, *, logger: ProviderLogger, config: dict | None = None) -> None:
    """Initialize the provider with optional configuration.

    Args:
        logger (ProviderLogger): Application logger injected by AniBridge.
        config (dict | None): Any configuration options that were detected with the
            provider's namespace as a prefix.
    """
    self.log = logger.getChild(f"library.{self.NAMESPACE}")
    self.config: dict = config or {}

clear_cache() async

Clear any cached data held by the provider.

For more efficient implementations, it is a good idea to cache data fetched from the provider to minimize network requests. AniBridge uses this method occasionally to clear such caches.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
304
305
306
307
308
309
310
311
async def clear_cache(self) -> None:
    """Clear any cached data held by the provider.

    For more efficient implementations, it is a good idea to cache data
    fetched from the provider to minimize network requests. AniBridge uses
    this method occasionally to clear such caches.
    """
    return None

close() async

Close the provider and release resources.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
313
314
315
async def close(self) -> None:
    """Close the provider and release resources."""
    return None

get_sections() abstractmethod async

Return available library sections for the provider.

Returns:

Type Description
Sequence[LibrarySection[LibraryProviderT]]

Sequence[LibrarySection[LibraryProviderT]]: The available library sections.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
317
318
319
320
321
322
323
324
@abstractmethod
async def get_sections(self) -> Sequence[LibrarySection[LibraryProviderT]]:
    """Return available library sections for the provider.

    Returns:
        Sequence[LibrarySection[LibraryProviderT]]: The available library sections.
    """
    ...

initialize() async

Asynchronous initialization hook.

Put any async logic that should be run after construction here.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
297
298
299
300
301
302
async def initialize(self) -> None:
    """Asynchronous initialization hook.

    Put any async logic that should be run after construction here.
    """
    return None

list_items(section, *, min_last_modified=None, require_watched=False, keys=None) abstractmethod async

List items in a library section with optional filtering.

Parameters:

Name Type Description Default
section LibrarySection[LibraryProviderT]

The library section to list items from.

 required
min_last_modified datetime | None

If provided, only include items modified after this timezone-aware timestamp.

 None
require_watched bool

If True, only include items marked as watched.

 False
keys Sequence[str] | None

If provided, only include items whose keys are in this sequence.

 None

Returns:

Type Description
Sequence[LibraryEntry[LibraryProviderT]]

Sequence[LibraryEntry[LibraryProviderT]]: The list of library items.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
@abstractmethod
async def list_items(
    self,
    section: LibrarySection[LibraryProviderT],
    *,
    min_last_modified: datetime | None = None,
    require_watched: bool = False,
    keys: Sequence[str] | None = None,
) -> Sequence[LibraryEntry[LibraryProviderT]]:
    """List items in a library section with optional filtering.

    Args:
        section (LibrarySection[LibraryProviderT]): The library section to list
            items from.
        min_last_modified (datetime | None): If provided, only include items
            modified after this timezone-aware timestamp.
        require_watched (bool): If True, only include items marked as watched.
        keys (Sequence[str] | None): If provided, only include items whose keys are
            in this sequence.

    Returns:
        Sequence[LibraryEntry[LibraryProviderT]]: The list of library items.
    """
    ...

parse_webhook(request) async

Parse an incoming webhook and return the affected item keys.

Parameters:

Name Type Description Default
request Request

The incoming HTTP request.

 required

Returns:

Type Description
tuple[bool, Sequence[str]]

tuple[bool, Sequence[str]]: A tuple where the first element indicates whether the webhook applies to the current provider, and the second element is a sequence of affected item keys.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
351
352
353
354
355
356
357
358
359
360
361
362
async def parse_webhook(self, request: Request) -> tuple[bool, Sequence[str]]:
    """Parse an incoming webhook and return the affected item keys.

    Args:
        request (Request): The incoming HTTP request.

    Returns:
        tuple[bool, Sequence[str]]: A tuple where the first element indicates
            whether the webhook applies to the current provider, and the second
            element is a sequence of affected item keys.
    """
    return False, ()

user() abstractmethod

Return the associated user object, if any.

Returns:

Type Description
LibraryUser | None

LibraryUser | None: The associated user object, if any.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
364
365
366
367
368
369
370
371
@abstractmethod
def user(self) -> LibraryUser | None:
    """Return the associated user object, if any.

    Returns:
        LibraryUser | None: The associated user object, if any.
    """
    ...

LibrarySeason dataclass

Bases: LibraryEntry[LibraryProviderT], ABC

Season container within a show.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
class LibrarySeason(LibraryEntry[LibraryProviderT], ABC):
    """Season container within a show."""

    index: int

    @abstractmethod
    def episodes(self) -> Sequence[LibraryEpisode[LibraryProviderT]]:
        """Get child episodes belonging to the season.

        Returns:
            Sequence[LibraryEpisode]: Child episodes.
        """
        ...

    @abstractmethod
    def show(self) -> LibraryShow[LibraryProviderT]:
        """Get the parent show of the season.

        Returns:
            LibraryShow: The parent show.
        """
        ...

    def __repr__(self) -> str:
        """Short representation including show title and season index."""
        return (
            f"<{self.__class__.__name__}:{self.key}:{self.show().title[:32]}:"
            f"S{self.index:02d}>"
        )

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

on_watching abstractmethod property

Whether the item is on the user's current watching list.

on_watchlist abstractmethod property

Whether the item is on the user's watchlist.

review abstractmethod async property

Return the user's review text for this item, if any.

title property

Return the entity title.

user_rating abstractmethod property

User rating on a 0-100 scale, or None if not rated.

view_count abstractmethod property

Total view count for the item (including children).

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Short representation including show title and season index.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
221
222
223
224
225
226
def __repr__(self) -> str:
    """Short representation including show title and season index."""
    return (
        f"<{self.__class__.__name__}:{self.key}:{self.show().title[:32]}:"
        f"S{self.index:02d}>"
    )

episodes() abstractmethod

Get child episodes belonging to the season.

Returns:

Type Description
Sequence[LibraryEpisode[LibraryProviderT]]

Sequence[LibraryEpisode]: Child episodes.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
203
204
205
206
207
208
209
210
@abstractmethod
def episodes(self) -> Sequence[LibraryEpisode[LibraryProviderT]]:
    """Get child episodes belonging to the season.

    Returns:
        Sequence[LibraryEpisode]: Child episodes.
    """
    ...

history() abstractmethod async

Return user history entries for this media item (tz-aware timestamps).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
117
118
119
120
@abstractmethod
async def history(self) -> Sequence[HistoryEntry]:
    """Return user history entries for this media item (tz-aware timestamps)."""
    ...

mapping_descriptors() abstractmethod

Return possible mapping descriptors for the media item.

The returned descriptors refer to providers in the mapping database. They are not related to the library provider of this item (although, they might match).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
122
123
124
125
126
127
128
129
@abstractmethod
def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
    """Return possible mapping descriptors for the media item.

    The returned descriptors refer to providers in the mapping database. They are
    not related to the library provider of this item (although, they might match).
    """
    ...

media() abstractmethod

Return the media item associated with this entry.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
131
132
133
134
@abstractmethod
def media(self) -> LibraryMedia[ProviderT]:
    """Return the media item associated with this entry."""
    ...

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

section() abstractmethod

Return the parent library section for this media item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
154
155
156
157
@abstractmethod
def section(self) -> LibrarySection[LibraryProviderT]:
    """Return the parent library section for this media item."""
    ...

show() abstractmethod

Get the parent show of the season.

Returns:

Name Type Description
LibraryShow LibraryShow[LibraryProviderT]

The parent show.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
212
213
214
215
216
217
218
219
@abstractmethod
def show(self) -> LibraryShow[LibraryProviderT]:
    """Get the parent show of the season.

    Returns:
        LibraryShow: The parent show.
    """
    ...

LibrarySection dataclass

Bases: LibraryEntity[LibraryProviderT], ABC

Represents a logical collection/section within the media library.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
92
93
class LibrarySection(LibraryEntity[LibraryProviderT], ABC):
    """Represents a logical collection/section within the media library."""

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

title property

Return the entity title.

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

LibraryShow dataclass

Bases: LibraryEntry[LibraryProviderT], ABC

Episodic show/series in a media library.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
class LibraryShow(LibraryEntry[LibraryProviderT], ABC):
    """Episodic show/series in a media library."""

    @abstractmethod
    def episodes(self) -> Sequence[LibraryEpisode[LibraryProviderT]]:
        """Get child episodes belonging to the show.

        Returns:
            Sequence[LibraryEpisode]: Child episodes.
        """
        ...

    @abstractmethod
    def seasons(self) -> Sequence[LibrarySeason[LibraryProviderT]]:
        """Get child seasons belonging to the show.

        Returns:
            Sequence[LibrarySeason]: Child seasons.
        """
        ...

key property

Return the unique key for this entity.

media_kind property

Return the high-level media kind of this entity.

on_watching abstractmethod property

Whether the item is on the user's current watching list.

on_watchlist abstractmethod property

Whether the item is on the user's watchlist.

review abstractmethod async property

Return the user's review text for this item, if any.

title property

Return the entity title.

user_rating abstractmethod property

User rating on a 0-100 scale, or None if not rated.

view_count abstractmethod property

Total view count for the item (including children).

__eq__(other)

Compare entities by provider namespace and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
76
77
78
79
80
81
82
83
84
85
def __eq__(self, other: object) -> bool:
    """Compare entities by provider namespace and key."""
    if other.__class__ is not self.__class__:
        return NotImplemented
    other_ent = cast(LibraryEntity, other)
    return (
        getattr(self._provider, "NAMESPACE", None)
        == getattr(other_ent._provider, "NAMESPACE", None)
        and self.key == other_ent.key
    )

__hash__()

Compute a hash based on provider namespace, class name, and key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
72
73
74
def __hash__(self) -> int:
    """Compute a hash based on provider namespace, class name, and key."""
    return hash((self._provider.NAMESPACE, self.__class__.__name__, self.key))

__repr__()

Return a short representation for debugging.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
87
88
89
def __repr__(self) -> str:
    """Return a short representation for debugging."""
    return f"<{self.__class__.__name__}:{self.key}:{self.title[:32]}>"

episodes() abstractmethod

Get child episodes belonging to the show.

Returns:

Type Description
Sequence[LibraryEpisode[LibraryProviderT]]

Sequence[LibraryEpisode]: Child episodes.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
179
180
181
182
183
184
185
186
@abstractmethod
def episodes(self) -> Sequence[LibraryEpisode[LibraryProviderT]]:
    """Get child episodes belonging to the show.

    Returns:
        Sequence[LibraryEpisode]: Child episodes.
    """
    ...

history() abstractmethod async

Return user history entries for this media item (tz-aware timestamps).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
117
118
119
120
@abstractmethod
async def history(self) -> Sequence[HistoryEntry]:
    """Return user history entries for this media item (tz-aware timestamps)."""
    ...

mapping_descriptors() abstractmethod

Return possible mapping descriptors for the media item.

The returned descriptors refer to providers in the mapping database. They are not related to the library provider of this item (although, they might match).

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
122
123
124
125
126
127
128
129
@abstractmethod
def mapping_descriptors(self) -> Sequence[MappingDescriptor]:
    """Return possible mapping descriptors for the media item.

    The returned descriptors refer to providers in the mapping database. They are
    not related to the library provider of this item (although, they might match).
    """
    ...

media() abstractmethod

Return the media item associated with this entry.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
131
132
133
134
@abstractmethod
def media(self) -> LibraryMedia[ProviderT]:
    """Return the media item associated with this entry."""
    ...

provider()

Return the provider associated with this entity.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
63
64
65
def provider(self) -> ProviderT:
    """Return the provider associated with this entity."""
    return self._provider

seasons() abstractmethod

Get child seasons belonging to the show.

Returns:

Type Description
Sequence[LibrarySeason[LibraryProviderT]]

Sequence[LibrarySeason]: Child seasons.
Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
188
189
190
191
192
193
194
195
@abstractmethod
def seasons(self) -> Sequence[LibrarySeason[LibraryProviderT]]:
    """Get child seasons belonging to the show.

    Returns:
        Sequence[LibrarySeason]: Child seasons.
    """
    ...

section() abstractmethod

Return the parent library section for this media item.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
154
155
156
157
@abstractmethod
def section(self) -> LibrarySection[LibraryProviderT]:
    """Return the parent library section for this media item."""
    ...

LibraryUser dataclass

User information for a library provider.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
269
270
271
272
273
274
275
276
277
278
@dataclass(frozen=True, slots=True)
class LibraryUser:
    """User information for a library provider."""

    key: str
    title: str

    def __hash__(self) -> int:
        """Return a hash based on the user key."""
        return hash(self.key)

__hash__()

Return a hash based on the user key.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
276
277
278
def __hash__(self) -> int:
    """Return a hash based on the user key."""
    return hash(self.key)

MediaKind

Bases: StrEnum

Supported high-level media kinds within a library provider.

Source code in .venv/lib/python3.14/site-packages/anibridge/library/base.py 
35
36
37
38
39
40
41
class MediaKind(StrEnum):
    """Supported high-level media kinds within a library provider."""

    MOVIE = "movie"
    SHOW = "show"
    SEASON = "season"
    EPISODE = "episode"