# anibridge-library-base

anibridge-library-base provides base classes and utilities to implement and register media library providers for the [AniBridge](https://github.com/anibridge/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](https://anibridge.eliasbenb.dev/).

## Installation

```shell
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](https://github.com/anibridge/anibridge-provider-template)
- [anibridge-plex-provider](https://github.com/anibridge/anibridge-plex-provider)
