anibridge-library-base 0.2.1

Library provider base classes for the AniBridge project.

anibridge-library-base

anibridge-library-base provides base classes and utilities to implement and register media library providers for the AniBridge project.

[!IMPORTANT] This package is intended for developers building AniBridge library providers. If you're looking to use AniBridge as an end user, please refer to the AniBridge documentation.

Installation

pip install anibridge-library-base
# pip install git+https://github.com/anibridge/anibridge-library-base.git

API reference

The package exposes its public API from anibridge.library and the core definitions in anibridge.library.base.

To get more context, read the anibridge.library.base module docstrings.

• LibraryProvider (base class)

  • Key methods and hooks:
    • __init__(*, logger: ProviderLogger, config: dict | None = None) -> None: Construct a provider with an injected logger and optional configuration.
    • async initialize() -> None: Optional async initialization hook for I/O or authentication.
    • async clear_cache() -> None: Clear any provider caches to free memory or refresh data.
    • async close() -> None: Close the provider and release resources.
    • async get_sections() -> Sequence[LibrarySection[LibraryProviderT]]: Return available library sections for the provider.
    • async list_items(section: LibrarySection[LibraryProviderT], *, min_last_modified: datetime | None = None, require_watched: bool = False, keys: Sequence[str] | None = None) -> Sequence[LibraryEntry[LibraryProviderT]]: List entries within a section with optional filtering.
    • async parse_webhook(request: litestar.connection.request.Request) -> tuple[bool, Sequence[str]]: Parse an incoming webhook and return whether it applies plus affected item keys.
    • user() -> LibraryUser | None: Return the associated user object, if any.

• LibraryEntry (per-item user state)

  • Key methods and properties:
    • async history() -> Sequence[HistoryEntry]: Return user history events for the item (tz-aware timestamps).
    • mapping_descriptors() -> Sequence[MappingDescriptor]: Return mapping descriptors for AniBridge matching.
    • media() -> LibraryMedia[LibraryProviderT]: Return the associated LibraryMedia object.
    • on_watching -> bool: Whether the item is currently being watched.
    • on_watchlist -> bool: Whether the item is on the user's watchlist.
    • review -> str | None: Optional user review text.
    • section() -> LibrarySection[LibraryProviderT]: Return the parent library section for the item.
    • user_rating -> int | None: Optional user rating on a 0-100 scale.
    • view_count -> int: Total view count for the item (including children).

• LibraryMedia (media metadata)

  • Key properties:
    • external_url -> str | None: URL to the provider's media item, if available.
    • poster_image -> str | None: Poster or cover image URL, if available.

• LibraryShow, LibrarySeason, LibraryEpisode, LibraryMovie

  • LibraryShow exposes episodes() and seasons().
  • LibrarySeason exposes index, episodes(), and show().
  • LibraryEpisode exposes index, season_index, season(), and show().

• HistoryEntry

  • library_key: str, viewed_at: datetime record a timezone-aware view event for an item.

• MediaKind (StrEnum)

  • High-level media kinds: MOVIE, SHOW, SEASON, EPISODE.

Examples

You can view the following built-in provider implementations as examples of how to implement the base classes:

• anibridge-provider-template
• anibridge-plex-provider