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: 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