API reference

Auto-generated reference for every public symbol in the Nyora library (import nyora). Each section renders the live docstrings of a module. For narrative usage, see the library guide.

Package overview

The top-level nyora package re-exports the primary client, the helper REST clients, the OTA manager, the embedded server, the model dataclasses, and the exception hierarchy. Each re-exported symbol is documented in full under its canonical module section below.

Nyora Python SDK — the importable nyora library.

Nyora is a self-contained manga sources SDK. The default client (nyora.direct.Nyora, re-exported here as Nyora) embeds the JavaScript parser bundle inside a QuickJS context via nyora.runtime.ParserRuntime, so it needs no Node and no JVM helper: HTTP is handled by httpx and HTML parsing by selectolax. The parser bundle and source catalog are kept current through nyora.ota.OtaManager (over-the-air updates).

This module is the public surface of the SDK. It re-exports the primary client, the helper-backed REST clients, the over-the-air manager, the embedded nyora.server.NyoraServer, the typed nyora.models dataclasses, and the SDK exception hierarchy.

The importable nyora library and the separately shipped nyora-cli tool (which launches the terminal UI) are distinct: this package documents the SDK.

Example

>>> import nyora
>>> with nyora.Nyora() as client:
...     source = client.sources.find("mangadex")
...     page = client.manga.popular(source.id)
...     first = page.entries[0]
...     details = client.manga.details(source.id, first.url, title=first.title)

nyora.direct

The default, self-contained client and its in-process services.

Self-contained Nyora client that does not require the JVM helper.

This module provides the default Nyora SDK entry point. Nyora drives an embedded nyora.runtime.ParserRuntime (the JavaScript parser bundle running inside QuickJS) and exposes two service objects:

• DirectSourcesService — list and look up bundled sources.

• DirectMangaService — browse popular/latest, search, and fetch manga details and chapter pages.

Unlike nyora.client (which talks to an external helper over REST), this path is fully in-process: no Node, no JVM. Over-the-air updates of the parser bundle and source catalog are managed through the attached nyora.ota.OtaManager (self.ota).

class nyora.direct.Nyora(*, timeout=60.0)

Bases: object

Default no-helper Nyora SDK client.

Drives an embedded nyora.runtime.ParserRuntime (the JavaScript parser bundle inside QuickJS) entirely in-process, so it requires neither a Node runtime nor the JVM helper. The parser bundle and source catalog are kept current through the attached nyora.ota.OtaManager (self.ota).

Variables:

• ota – Over-the-air manager for the parser bundle and source catalog.

• sources – DirectSourcesService for listing and finding sources.

• manga – DirectMangaService for browsing, search, and details.

Example

>>> with Nyora() as client:
...     source = client.sources.find("mangadex")
...     page = client.manga.popular(source.id)
...     entry = page.entries[0]
...     details = client.manga.details(source.id, entry.url, title=entry.title)

Parameters:

timeout (float)

Initialize the client and its embedded parser runtime.

Parameters:

timeout (float) – Per-call timeout in seconds for parser runtime operations.

update(*, force=False)

Fetch the latest OTA parser bundle and reload the runtime.

Parameters:

force (bool) – Re-download and reload even if the installed version is already current.

Return type:

OtaUpdateResult

Returns:

The OtaUpdateResult describing the applied update (updated is False when already up to date).

check_update()

Check whether a newer OTA parser bundle is available.

Return type:

tuple[bool, int | None, int | None]

Returns:

A tuple (available, installed_version, latest_version). Versions are None when unknown (e.g. nothing installed yet, or the manifest could not be reached).

classmethod helper(base_url=None, *, timeout=60.0)

Attach to an already-running external Nyora helper over REST.

Parameters:

• base_url (str | None) – Helper base URL. When None it is discovered from the NYORA_BASE_URL environment variable or the helper port file.

• timeout (float) – Per-request HTTP timeout in seconds.

Return type:

Nyora

Returns:

A connected nyora.client.Nyora helper client.

classmethod managed_helper(jar_path, *, timeout=60.0, launch_timeout=20.0)

Launch and attach to a helper process from a JVM jar.

Parameters:

• jar_path (str) – Filesystem path to the helper jar to launch.

• timeout (float) – Per-request HTTP timeout in seconds for the client.

• launch_timeout (float) – Seconds to wait for the helper to become healthy.

Return type:

Nyora

Returns:

A nyora.client.Nyora client bound to the managed process.

close()

Close the embedded parser runtime and release its resources.

Return type:

None

class nyora.direct.DirectSourcesService(runtime)

Bases: object

List and look up the sources bundled with the parser runtime.

Parameters:

runtime (ParserRuntime)

Bind the service to a parser runtime.

Parameters:

runtime (ParserRuntime) – The embedded runtime providing the bundled source catalog.

list()

List every source available in the bundled catalog.

Return type:

list[Source]

Returns:

A list of Source records.

find(query)

Find a bundled source by a case-insensitive id or name substring.

Parameters:

query (str) – Substring matched against each source’s id and name.

Return type:

Source

Returns:

The first matching Source.

Raises:

LookupError – If no bundled source matches query.

class nyora.direct.DirectMangaService(runtime)

Bases: object

Browse, search, and read manga directly through the parser runtime.

Parameters:

runtime (ParserRuntime)

Bind the service to a parser runtime.

Parameters:

runtime (ParserRuntime) – The embedded runtime used to invoke parser methods.

popular(source_id, page=1)

Fetch a page of popular manga from a source.

Parameters:

• source_id (str) – Identifier of the source to query.

• page (int) – One-based page number to fetch.

Return type:

SearchPage

Returns:

A SearchPage of entries.

latest(source_id, page=1)

Fetch a page of the latest updated manga from a source.

Parameters:

• source_id (str) – Identifier of the source to query.

• page (int) – One-based page number to fetch.

Return type:

SearchPage

Returns:

A SearchPage of entries.

search(source_id, query, page=1)

Search a source for manga matching a query.

Parameters:

• source_id (str) – Identifier of the source to query.

• query (str) – Free-text search query.

• page (int) – One-based page number to fetch.

Return type:

SearchPage

Returns:

A SearchPage of matching entries.

details(source_id, manga_url, *, title='')

Fetch full metadata and the chapter list for one manga.

Parameters:

• source_id (str) – Identifier of the source that owns the manga.

• manga_url (str) – The manga’s source-relative or absolute URL.

• title (str) – Optional known title, passed through to the parser to help resolve the entry.

Return type:

MangaDetails

Returns:

A MangaDetails with the manga and its chapters.

pages(source_id, chapter_url, *, branch=None)

Resolve the readable image pages of a single chapter.

Parameters:

• source_id (str) – Identifier of the source that owns the chapter.

• chapter_url (str) – The chapter’s source-relative or absolute URL.

• branch (str | None) – Optional scanlation branch/translation to select.

Return type:

list[MangaPage]

Returns:

An ordered list of MangaPage objects.

nyora.client

The helper-backed REST clients (Nyora, AsyncNyora).

Nyora helper HTTP clients.

This module provides the helper-backed REST clients used when an external Nyora helper process (the JVM helper, or an embedded nyora.server.NyoraServer) is available. Unlike nyora.direct.Nyora, these clients do not embed a parser runtime; they speak the camelCase helper REST contract over HTTP via httpx.

It exposes:

• Nyora — synchronous client with the full set of service objects (sources, manga, library, downloads, backup, system).

• AsyncNyora — lightweight async client for read-style requests.

The helper base URL is discovered from an explicit argument, the NYORA_BASE_URL environment variable, or the helper port file written by a running Nyora app. A helper jar can also be launched and managed via Nyora.managed().

class nyora.client.Nyora(base_url=None, *, timeout=60.0, helper=None)

Bases: object

Synchronous Nyora SDK client backed by a helper REST API.

Wraps an httpx.Client against a discovered or managed helper and exposes the full set of service objects. Use as a context manager to release the HTTP connection (and stop a managed helper) on exit.

Variables:

• base_url – The resolved helper base URL.

• sources – SourcesService.

• manga – MangaService.

• library – LibraryService.

• downloads – DownloadsService.

• backup – BackupService.

• system – SystemService.

Example

>>> with Nyora.attach() as client:
...     for source in client.sources.list():
...         print(source.id, source.name)

Parameters:

• base_url (str | None)

• timeout (float)

• helper (HelperProcess | None)

Connect to a helper and construct the service objects.

Parameters:

• base_url (str | None) – Explicit helper base URL, or None to auto-discover.

• timeout (float) – Per-request HTTP timeout in seconds.

• helper (HelperProcess | None) – An owned HelperProcess to stop on close(), when the client launched the helper itself.

Raises:

HelperNotFoundError – If no helper can be discovered.

classmethod attach(base_url=None, *, timeout=60.0)

Attach to an already-running helper.

Parameters:

• base_url (str | None) – Explicit helper base URL, or None to auto-discover.

• timeout (float) – Per-request HTTP timeout in seconds.

Return type:

Self

Returns:

A connected client.

classmethod managed(jar_path=None, *, java='java', timeout=60.0, launch_timeout=20.0)

Launch a helper jar and return a client bound to it.

The launched process is owned by the returned client and is stopped on close().

Parameters:

• jar_path (str | PathLike[str] | None) – Path to the helper jar. When None it is read from the NYORA_HELPER_JAR environment variable.

• java (str) – The java executable to invoke.

• timeout (float) – Per-request HTTP timeout in seconds for the client.

• launch_timeout (float) – Seconds to wait for the helper to report healthy.

Return type:

Self

Returns:

A client connected to the managed helper.

Raises:

• HelperNotFoundError – If the jar path is missing or does not exist.

• HelperLaunchError – If the helper fails to start within the timeout.

close()

Close the HTTP connection and stop any managed helper process.

Return type:

None

health()

Return the helper’s /health payload.

Return type:

dict[str, Any]

Returns:

The health dict, or an empty dict if the response was not an object.

get(path, *, params=None)

Issue a GET request against the helper.

Parameters:

• path (str) – Request path relative to the base URL.

• params (dict[str, Any] | None) – Optional query parameters.

Return type:

Any

Returns:

Parsed JSON, or the response text for non-JSON bodies.

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.

post(path, *, params=None, json=None, content=None)

Issue a POST request against the helper.

Parameters:

• path (str) – Request path relative to the base URL.

• params (dict[str, Any] | None) – Optional query parameters.

• json (Any | None) – Optional JSON-serializable request body.

• content (str | bytes | None) – Optional raw request body (mutually exclusive with json).

Return type:

Any

Returns:

Parsed JSON, or the response text for non-JSON bodies.

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.

delete(path, *, params=None)

Issue a DELETE request against the helper.

Parameters:

• path (str) – Request path relative to the base URL.

• params (dict[str, Any] | None) – Optional query parameters.

Return type:

Any

Returns:

Parsed JSON, or the response text for non-JSON bodies.

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.

class nyora.client.AsyncNyora(base_url=None, *, timeout=60.0)

Bases: object

Asynchronous Nyora helper client for read-style requests.

A lightweight httpx.AsyncClient wrapper exposing get() against a discovered or explicit helper base URL. Use as an async context manager to release the connection on exit.

Variables:

base_url – The resolved helper base URL.

Example

>>> async with AsyncNyora.attach() as client:
...     payload = await client.get("/sources")

Parameters:

• base_url (str | None)

• timeout (float)

Connect to a helper.

Parameters:

• base_url (str | None) – Explicit helper base URL, or None to auto-discover.

• timeout (float) – Per-request HTTP timeout in seconds.

Raises:

HelperNotFoundError – If no helper can be discovered.

classmethod attach(base_url=None, *, timeout=60.0)

Attach to an already-running helper.

Parameters:

• base_url (str | None) – Explicit helper base URL, or None to auto-discover.

• timeout (float) – Per-request HTTP timeout in seconds.

Return type:

AsyncNyora

Returns:

A connected async client.

async close()

Close the underlying async HTTP connection.

Return type:

None

async health()

Return the helper’s /health payload.

Return type:

dict[str, Any]

Returns:

The health dict, or an empty dict if the response was not an object.

async get(path, *, params=None)

Issue a GET request against the helper.

Parameters:

• path (str) – Request path relative to the base URL.

• params (dict[str, Any] | None) – Optional query parameters.

Return type:

Any

Returns:

Parsed JSON, or an empty dict for empty bodies.

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.

nyora.models

Typed dataclasses returned throughout the SDK.

Typed data models for the Nyora SDK.

Lightweight, slotted dataclasses that mirror the JSON returned by the Nyora parser runtime and helper REST API. Every model exposes a tolerant from_json classmethod that accepts the raw camelCase payloads and coerces field types defensively, so missing or malformed fields fall back to sensible defaults rather than raising. These types are returned throughout nyora.direct.Nyora, nyora.client.Nyora, and the service objects.

class nyora.models.MangaPage(url, headers=<factory>)

Bases: object

A single readable image page of a chapter.

Variables:

• url – The image URL.

• headers – Request headers required to fetch the image (e.g. Referer).

Parameters:

• url (str)

• headers (dict[str, str])

url: str

headers: dict[str, str]

classmethod from_json(data)

Build a MangaPage from a raw payload.

Parameters:

data (Any) – A page object, or a bare string treated as the URL.

Return type:

MangaPage

Returns:

The parsed page.

class nyora.models.MangaChapter(id, title, number=0.0, volume=0, url='', scanlator=None, upload_date=0, branch=None, pages=<factory>, index=0)

Bases: object

A chapter belonging to a manga.

Variables:

• id – Stable chapter identifier.

• title – Display title.

• number – Chapter number (may be fractional).

• volume – Volume number, or 0 if unknown.

• url – Source-relative or absolute chapter URL.

• scanlator – Scanlation group, if known.

• upload_date – Upload timestamp in epoch milliseconds.

• branch – Scanlation branch/translation name, if any.

• pages – Resolved pages, when already loaded.

• index – Position within the chapter list.

Parameters:

• id (str)

• title (str)

• number (float)

• volume (int)

• url (str)

• scanlator (str | None)

• upload_date (int)

• branch (str | None)

• pages (list[MangaPage])

• index (int)

id: str

title: str

number: float

volume: int

url: str

scanlator: str | None

upload_date: int

branch: str | None

pages: list[MangaPage]

index: int

classmethod from_json(data)

Build a MangaChapter from a raw payload.

Parameters:

data (Any) – A chapter object from the parser or helper.

Return type:

MangaChapter

Returns:

The parsed chapter.

class nyora.models.Manga(id, title, alt_titles=<factory>, url='', public_url='', rating=-1.0, is_nsfw=False, content_rating=None, cover_url='', large_cover_url=None, state=None, authors=<factory>, source=<factory>, source_id='', description='', tags=<factory>, chapters=<factory>, unread=0, progress=0.0)

Bases: object

A manga entry as returned in listings and details.

Variables:

• id – Stable manga identifier.

• title – Primary title.

• alt_titles – Alternative titles.

• url – Source-relative or absolute manga URL.

• public_url – Public web URL for the manga, if distinct.

• rating – Normalized rating, or -1.0 when unknown.

• is_nsfw – Whether the entry is flagged adult/NSFW.

• content_rating – Source-provided content rating, if any.

• cover_url – Cover thumbnail URL.

• large_cover_url – High-resolution cover URL, if available.

• state – Publication state (e.g. ongoing/finished), if known.

• authors – Author names.

• source – Raw source metadata as a dict.

• source_id – Identifier of the owning source.

• description – Synopsis text.

• tags – Genre/tag dicts.

• chapters – Chapters, when already loaded.

• unread – Unread chapter count, for library entries.

• progress – Read progress fraction, for library entries.

Parameters:

• id (str)

• title (str)

• alt_titles (list[str])

• url (str)

• public_url (str)

• rating (float)

• is_nsfw (bool)

• content_rating (str | None)

• cover_url (str)

• large_cover_url (str | None)

• state (str | None)

• authors (list[str])

• source (dict[str, Any])

• source_id (str)

• description (str)

• tags (list[dict[str, Any]])

• chapters (list[MangaChapter])

• unread (int)

• progress (float)

id: str

title: str

alt_titles: list[str]

url: str

public_url: str

rating: float

is_nsfw: bool

content_rating: str | None

cover_url: str

large_cover_url: str | None

state: str | None

authors: list[str]

source: dict[str, Any]

source_id: str

description: str

tags: list[dict[str, Any]]

chapters: list[MangaChapter]

unread: int

progress: float

classmethod from_json(data)

Build a Manga from a raw payload.

Parameters:

data (Any) – A manga object from the parser or helper.

Return type:

Manga

Returns:

The parsed manga.

class nyora.models.Source(id, name, lang='', base_url='', engine='', content_type='', is_installed=False, is_pinned=False, is_nsfw=False, is_obsolete=False, icon_url='', version='', notes='', can_uninstall=True)

Bases: object

A content source (site) the SDK can read from.

Variables:

• id – Stable source identifier.

• name – Human-readable source name.

• lang – Primary content language/locale code.

• base_url – The source’s base site URL.

• engine – Parser engine (e.g. "JavaScript").

• content_type – Content type (e.g. "Manga").

• is_installed – Whether the source is installed/available.

• is_pinned – Whether the user pinned the source.

• is_nsfw – Whether the source is flagged adult/NSFW.

• is_obsolete – Whether the source is deprecated.

• icon_url – Source icon URL.

• version – Source/parser version string.

• notes – Free-form notes.

• can_uninstall – Whether the source may be uninstalled.

Parameters:

• id (str)

• name (str)

• lang (str)

• base_url (str)

• engine (str)

• content_type (str)

• is_installed (bool)

• is_pinned (bool)

• is_nsfw (bool)

• is_obsolete (bool)

• icon_url (str)

• version (str)

• notes (str)

• can_uninstall (bool)

id: str

name: str

lang: str

base_url: str

engine: str

content_type: str

is_installed: bool

is_pinned: bool

is_nsfw: bool

is_obsolete: bool

icon_url: str

version: str

notes: str

can_uninstall: bool

classmethod from_json(data)

Build a Source from a raw payload.

Accepts both name/title and lang/locale and baseUrl/site aliases.

Parameters:

data (Any) – A source object from the parser or helper.

Return type:

Source

Returns:

The parsed source.

class nyora.models.SourceFilter(name, type_name, values=<factory>)

Bases: object

A search filter advertised by a source.

Variables:

• name – Filter name.

• type_name – Filter widget/type (e.g. select, toggle).

• values – Allowed values for the filter.

Parameters:

• name (str)

• type_name (str)

• values (list[str])

name: str

type_name: str

values: list[str]

classmethod from_json(data)

Build a SourceFilter from a raw payload.

Parameters:

data (Any) – A filter object from the helper.

Return type:

SourceFilter

Returns:

The parsed filter.

class nyora.models.SearchPage(entries, has_next_page=False)

Bases: object

One page of manga results from browse or search.

Variables:

• entries – The manga on this page.

• has_next_page – Whether a further page is likely available.

Parameters:

• entries (list[Manga])

• has_next_page (bool)

entries: list[Manga]

has_next_page: bool

classmethod from_json(data)

Build a SearchPage from a raw payload.

Parameters:

data (Any) – A page object with entries and hasNextPage.

Return type:

SearchPage

Returns:

The parsed page.

class nyora.models.MangaDetails(manga, chapters)

Bases: object

Full metadata for one manga together with its chapter list.

Variables:

• manga – The manga metadata.

• chapters – The manga’s chapters.

Parameters:

• manga (Manga)

• chapters (list[MangaChapter])

manga: Manga

chapters: list[MangaChapter]

classmethod from_json(data)

Build a MangaDetails from a raw payload.

Parameters:

data (Any) – An object with manga and chapters.

Return type:

MangaDetails

Returns:

The parsed details.

class nyora.models.HistoryEntry(manga, chapter_id='', page=0, percent=0.0, updated_at=0)

Bases: object

A reading-history record for a manga.

Variables:

• manga – The manga that was read.

• chapter_id – The last-read chapter identifier.

• page – The last-read page index.

• percent – Read progress fraction within the chapter.

• updated_at – Last-update timestamp in epoch milliseconds.

Parameters:

• manga (Manga)

• chapter_id (str)

• page (int)

• percent (float)

• updated_at (int)

manga: Manga

chapter_id: str

page: int

percent: float

updated_at: int

classmethod from_json(data)

Build a HistoryEntry from a raw payload.

Parameters:

data (Any) – A history object from the helper.

Return type:

HistoryEntry

Returns:

The parsed entry.

class nyora.models.Category(id, title, manga_count=0)

Bases: object

A user-defined library category.

Variables:

• id – Category identifier.

• title – Display title.

• manga_count – Number of manga in the category.

Parameters:

• id (int)

• title (str)

• manga_count (int)

id: int

title: str

manga_count: int

classmethod from_json(data)

Build a Category from a raw payload.

Parameters:

data (Any) – A category object from the helper.

Return type:

Category

Returns:

The parsed category.

class nyora.models.Download(id, source_id, manga_title, chapter_title, chapter_url, status, total_pages=0, completed_pages=0, failed_pages=0, file_path=None, error=None)

Bases: object

A chapter download task and its progress.

Variables:

• id – Download task identifier.

• source_id – Identifier of the owning source.

• manga_title – Title of the manga being downloaded.

• chapter_title – Title of the chapter being downloaded.

• chapter_url – URL of the chapter being downloaded.

• status – Task status string.

• total_pages – Total number of pages to download.

• completed_pages – Pages downloaded so far.

• failed_pages – Pages that failed to download.

• file_path – Output path once complete, if available.

• error – Error message when the task failed, if any.

Parameters:

• id (str)

• source_id (str)

• manga_title (str)

• chapter_title (str)

• chapter_url (str)

• status (str)

• total_pages (int)

• completed_pages (int)

• failed_pages (int)

• file_path (str | None)

• error (str | None)

id: str

source_id: str

manga_title: str

chapter_title: str

chapter_url: str

status: str

total_pages: int

completed_pages: int

failed_pages: int

file_path: str | None

error: str | None

classmethod from_json(data)

Build a Download from a raw payload.

Parameters:

data (Any) – A download object from the helper.

Return type:

Download

Returns:

The parsed download.

class nyora.models.DownloadSettings(max_concurrent_downloads=3, format='AUTO')

Bases: object

Download subsystem settings.

Variables:

• max_concurrent_downloads – Maximum simultaneous downloads.

• format – Output format (e.g. "AUTO").

Parameters:

• max_concurrent_downloads (int)

• format (str)

max_concurrent_downloads: int

format: str

classmethod from_json(data)

Build DownloadSettings from a raw payload.

Accepts either a bare settings object or one nested under settings.

Parameters:

data (Any) – A settings object from the helper.

Return type:

DownloadSettings

Returns:

The parsed settings.

class nyora.models.MangaPrefs(manga_id, reader_mode='', brightness=0.0, contrast=1.0, saturation=1.0, hue=0.0, palette='', present=False)

Bases: object

Per-manga reader preferences.

Variables:

• manga_id – Identifier of the manga these preferences apply to.

• reader_mode – Reader layout/mode.

• brightness – Brightness adjustment.

• contrast – Contrast multiplier.

• saturation – Saturation multiplier.

• hue – Hue rotation.

• palette – Named color palette.

• present – Whether stored preferences exist for this manga.

Parameters:

• manga_id (str)

• reader_mode (str)

• brightness (float)

• contrast (float)

• saturation (float)

• hue (float)

• palette (str)

• present (bool)

manga_id: str

reader_mode: str

brightness: float

contrast: float

saturation: float

hue: float

palette: str

present: bool

classmethod from_json(data)

Build MangaPrefs from a raw payload.

Parameters:

data (Any) – A preferences object from the helper.

Return type:

MangaPrefs

Returns:

The parsed preferences.

class nyora.models.GlobalSearchGroup(source_id, source_name, entries, error=None)

Bases: object

Results from one source within a cross-source global search.

Variables:

• source_id – Identifier of the source that produced these results.

• source_name – Display name of the source.

• entries – Matching manga from this source.

• error – Error message if this source’s search failed, else None.

Parameters:

• source_id (str)

• source_name (str)

• entries (list[Manga])

• error (str | None)

source_id: str

source_name: str

entries: list[Manga]

error: str | None

classmethod from_json(data)

Build a GlobalSearchGroup from a raw payload.

Parameters:

data (Any) – A group object from the helper.

Return type:

GlobalSearchGroup

Returns:

The parsed group.

class nyora.models.Stats(total_chapters=0, distinct_manga=0, favourites_count=0, longest_streak_days=0, top_sources=<factory>)

Bases: object

Aggregate reading statistics.

Variables:

• total_chapters – Total chapters read.

• distinct_manga – Number of distinct manga read.

• favourites_count – Number of favourited manga.

• longest_streak_days – Longest consecutive reading streak in days.

• top_sources – Per-source usage breakdown dicts.

Parameters:

• total_chapters (int)

• distinct_manga (int)

• favourites_count (int)

• longest_streak_days (int)

• top_sources (list[dict[str, Any]])

total_chapters: int

distinct_manga: int

favourites_count: int

longest_streak_days: int

top_sources: list[dict[str, Any]]

classmethod from_json(data)

Build Stats from a raw payload.

Parameters:

data (Any) – A stats object from the helper.

Return type:

Stats

Returns:

The parsed statistics.

class nyora.models.BackupImportResult(ok, imported_favourites=0, imported_history=0)

Bases: object

Outcome of importing a backup archive.

Variables:

• ok – Whether the import succeeded.

• imported_favourites – Number of favourites imported.

• imported_history – Number of history records imported.

Parameters:

• ok (bool)

• imported_favourites (int)

• imported_history (int)

ok: bool

imported_favourites: int

imported_history: int

classmethod from_json(data)

Build a BackupImportResult from a raw payload.

Parameters:

data (Any) – A result object from the helper.

Return type:

BackupImportResult

Returns:

The parsed result.

nyora.ota

Over-the-air parser-bundle and source-catalog management.

Over-the-air parser feed management for Nyora Python.

This module keeps the JavaScript parser bundle and source catalog current without a package release. OtaManager fetches a signed manifest from the public OTA feed, verifies each artifact by SHA-256, and writes the bundle, catalog, and manifest atomically into a per-user cache directory. When nothing is cached, reads transparently fall back to the assets shipped inside the package, so the SDK works fully offline on first run.

class nyora.ota.OtaUpdateResult(updated, version, bundle_path, sources_path)

Bases: object

Outcome of an OTA update attempt.

Variables:

• updated – True if new artifacts were downloaded and written; False if the cache was already current.

• version – The manifest version now installed in the cache.

• bundle_path – Filesystem path to the cached parser bundle.

• sources_path – Filesystem path to the cached source catalog.

Parameters:

• updated (bool)

• version (int)

• bundle_path (Path)

• sources_path (Path)

updated: bool

version: int

bundle_path: Path

sources_path: Path

class nyora.ota.OtaManager(cache_dir=None, *, timeout=30.0)

Bases: object

Manages the over-the-air parser bundle and source catalog.

Coordinates fetching the OTA manifest, downloading and SHA-256-verifying the parser bundle and source catalog, and caching them atomically per user. Reads fall back to the bundled package assets when the cache is empty.

Example

>>> ota = OtaManager()
>>> available, installed, latest = ota.is_update_available()
>>> if available:
...     result = ota.update()
...     print("updated to", result.version)

Parameters:

• cache_dir (Path | None)

• timeout (float)

Initialize the manager.

Parameters:

• cache_dir (Path | None) – Directory for cached OTA artifacts. Defaults to the per-user cache directory (.../nyora/ota).

• timeout (float) – HTTP timeout in seconds for manifest and artifact fetches.

property cache_dir: Path

The directory where OTA artifacts are cached.

fetch_manifest()

Download and parse the remote OTA manifest.

Return type:

dict[str, Any]

Returns:

The manifest as a dict (containing version and per-artifact url/sha256 entries).

Raises:

NyoraError – If the manifest cannot be fetched, is invalid JSON, or is not a JSON object.

installed_version()

Return the manifest version currently cached, if any.

Return type:

int | None

Returns:

The cached integer version, or None when nothing is cached or the cached manifest is unreadable.

is_update_available()

Check whether the remote feed offers a newer version.

Network or manifest errors are treated as “no update available” rather than propagating, so this is safe to call opportunistically.

Return type:

tuple[bool, int | None, int | None]

Returns:

A tuple (available, installed_version, latest_version). Either version may be None when unknown.

update(*, force=False)

Download and cache the latest parser bundle and source catalog.

The remote manifest is fetched, each artifact is downloaded and verified against its SHA-256, and all files are written atomically. When the cache is already current and force is False, nothing is downloaded.

Parameters:

force (bool) – Re-download and overwrite even when already up to date.

Return type:

OtaUpdateResult

Returns:

An OtaUpdateResult describing what was applied.

Raises:

NyoraError – If the manifest or an artifact cannot be fetched, or if an artifact fails SHA-256 verification.

read_bundle_text()

Return the parser bundle source.

Return type:

str

Returns:

The cached bundle text, or the package-bundled fallback when no cache exists.

read_sources_text()

Return the source catalog JSON.

Return type:

str

Returns:

The cached catalog text, or the package-bundled fallback when no cache exists.

nyora.server

The stdlib HTTP server exposing the helper-compatible REST contract.

class nyora.server.NyoraServer(host='127.0.0.1', port=0, *, runtime=None, write_port_file=True, timeout=60.0)

Bases: object

Serve the camelCase helper REST contract over an embedded runtime.

Exposes the Nyora helper REST API backed by a ParserRuntime, so any Nyora client (including nyora.client.Nyora) can talk to the Python SDK as if it were the JVM helper.

Example

>>> server = NyoraServer()
>>> base_url = server.start()  # background thread, returns immediately
>>> # ... attach a client to base_url ...
>>> server.stop()

Parameters:

• host (str)

• port (int)

• runtime (ParserRuntime | None)

• write_port_file (bool)

• timeout (float)

Initialize the server.

Parameters:

• host (str) – Interface to bind. Defaults to loopback.

• port (int) – Port to bind, or 0 to pick a free ephemeral port.

• runtime (ParserRuntime | None) – An existing ParserRuntime to serve. When None, a new one is created and owned (closed on stop()).

• write_port_file (bool) – Whether to write the bound port to the standard helper port file so other apps can discover this server.

• timeout (float) – Per-call timeout in seconds for an owned runtime.

property base_url: str

The base URL the server is bound to.

Returns:

The http://host:port base URL.

Raises:

NyoraError – If the server has not been started yet.

start()

Start serving in a background daemon thread.

Idempotent: calling it again while running returns the existing URL.

Return type:

str

Returns:

The base URL the server is bound to.

serve_forever()

Serve requests in the calling thread until interrupted.

Blocks until the server is shut down (e.g. by KeyboardInterrupt), then stops and cleans up.

Return type:

None

stop()

Shut down the server and release its resources.

Closes the listening socket, joins the background thread, and closes an owned runtime. Safe to call when not running.

Return type:

None

dispatch(path, query)

Route one request to the appropriate handler.

Parameters:

• path (str) – The request path (no query string).

• query (dict[str, list[str]]) – Parsed query parameters (each value is a list).

Return type:

tuple[int, dict[str, Any]]

Returns:

A (status_code, json_body) tuple.

Raises:

• _BadRequest – If a required query parameter is missing or invalid.

• LookupError – If a referenced source does not exist.

• NyoraError – If the underlying runtime call fails.

nyora.runtime

The embedded QuickJS parser runtime that backs the direct client and the server.

Embedded JavaScript parser runtime for Nyora Python.

This module hosts ParserRuntime, the no-helper execution engine that runs Nyora’s bundled JavaScript parsers (parsers.bundle.js) inside a QuickJS context. The JavaScript side exposes a global NyoraParsers object whose parsers call back into Python for the things QuickJS cannot do on its own:

• HTTP requests are served by httpx (__py_http_get / __py_http_post).

• HTML parsing and DOM traversal are served by selectolax (__py_parse_html and the __py_query_* / __py_* node accessors).

The runtime is deliberately tolerant: HTTP errors return the response body (or an empty string on transport failure) instead of raising, and every DOM callback returns a safe default rather than raising into JavaScript. Combined with the browser/Node polyfills installed by _runtime_prelude(), this keeps the embedded parsers running for the widest possible range of real-world sources.

exception nyora.runtime.ParserRuntimeError

Bases: NyoraError

Raised when the embedded parser runtime fails.

class nyora.runtime.ParserRuntime(*, timeout=60.0, ota=None)

Bases: object

Run Nyora’s bundled JavaScript parsers inside an embedded QuickJS engine.

A single instance owns one httpx.Client, one QuickJS context, and the Python-side DOM node registry that backs the JavaScript PyNode wrapper. The context is built from the JavaScript prelude (_runtime_prelude()) followed by the OTA-managed parser bundle.

Parameters:

• timeout (float) – Per-request HTTP timeout, in seconds, for the shared client.

• ota (OtaManager | None) – Optional OtaManager. When omitted a default manager is created, which transparently uses the bundled assets and the user cache.

reload()

Rebuild the QuickJS context from the (possibly updated) bundle.

Re-reads the parser bundle via the OtaManager and recreates the JavaScript context and DOM registry from scratch. Call this after an OTA update so the new parsers take effect.

Return type:

None

close()

Release the shared HTTP client. Safe to call once per instance.

Return type:

None

sources()

Return the catalog of available sources as raw parser metadata dicts.

Return type:

list[dict[str, Any]]

Returns:

A list of source descriptors exactly as emitted by NyoraParsers.getAllSources() (camelCase keys), or an empty list if the bundle returns something other than an array.

call(source_id, method, args)

Invoke one parser method and return its decoded JSON result.

Parameters:

• source_id (str) – The source identifier, with or without the parser: prefix.

• method (str) – One of popular, latest, search, details, or pages.

• args (dict[str, Any]) – Method arguments (e.g. page, query, url, manga, branch, filter) passed through to the parser.

Return type:

Any

Returns:

The parser result, JSON-decoded into native Python objects.

Raises:

ParserRuntimeError – If the parser is missing, the method is unknown, the parser reports an error, or the embedded engine fails.

nyora.errors

The SDK exception hierarchy.

Nyora SDK exceptions.

Defines the exception hierarchy raised across the SDK. NyoraError is the common base; helper discovery, helper launch, and helper HTTP failures each have a dedicated subclass so callers can catch them selectively.

exception nyora.errors.NyoraError

Bases: Exception

Base exception for Nyora SDK failures.

exception nyora.errors.HelperNotFoundError

Bases: NyoraError

Raised when no running helper can be discovered.

exception nyora.errors.HelperLaunchError

Bases: NyoraError

Raised when a managed helper process fails to start.

exception nyora.errors.NyoraHTTPError(status_code, message, *, body='')

Bases: NyoraError

Raised when the helper returns a non-successful HTTP response.

Variables:

• status_code – The HTTP status code returned by the helper.

• body – The raw response body, when available.

Parameters:

• status_code (int)

• message (str)

• body (str)

Initialize the error.

Parameters:

• status_code (int) – The HTTP status code (>= 400).

• message (str) – A human-readable error message.

• body (str) – The raw response body, when available.

nyora.config

Helper-discovery configuration: environment variables and the port file.

Configuration helpers for local Nyora helper discovery.

Defines the environment-variable names the SDK honors and resolves the platform-specific path of the helper port file. These helpers let nyora.client and nyora.helper locate a running Nyora helper without explicit configuration.

Environment variables:

NYORA_BASE_URL: Explicit helper base URL, overriding port-file discovery. NYORA_HELPER_PORT_FILE: Override path for the helper port file. NYORA_HELPER_JAR: Path to a helper jar for managed launches.

nyora.config.default_port_file()

Return the path of the helper port file for this platform.

Honors NYORA_HELPER_PORT_FILE when set; otherwise uses the platform-conventional application-data location (macOS Application Support, Windows %APPDATA%, or the XDG config dir on Linux).

Return type:

Path

Returns:

The resolved port-file path (which may not yet exist).

nyora.config.read_base_url_from_port_file(port_file=None)

Derive a helper base URL from a port file, if present.

Parameters:

port_file (Path | None) – Path to read. Defaults to default_port_file().

Return type:

str | None

Returns:

http://127.0.0.1:<port> when the file exists and holds a port, else None.

Services

The service objects attached to the helper client (nyora.client.Nyora).

nyora.services.sources

Source catalog operations.

class nyora.services.sources.SourcesService(client)

Bases: object

Browse, manage, and inspect the helper’s content sources.

Attached to a client as client.sources.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

list()

List the installed sources.

Return type:

list[Source]

Returns:

The installed Source records.

catalog()

List every source available in the catalog (installed or not).

Return type:

list[Source]

Returns:

All catalog Source records.

refresh()

Refresh the source catalog from the remote feed.

Return type:

list[Source]

Returns:

The refreshed list of Source records.

install(source_id)

Install a source by id.

Parameters:

source_id (str) – Identifier of the source to install.

Return type:

Source | dict[str, Any]

Returns:

The installed Source, or the raw response dict when no source field is present.

uninstall(source_id)

Uninstall a source by id.

Parameters:

source_id (str) – Identifier of the source to uninstall.

Return type:

dict[str, Any]

Returns:

The raw helper response.

pin(source_id)

Toggle the pinned state of a source.

Parameters:

source_id (str) – Identifier of the source to pin/unpin.

Return type:

dict[str, Any]

Returns:

The raw helper response.

filters(source_id)

List the search filters a source advertises.

Parameters:

source_id (str) – Identifier of the source to query.

Return type:

list[SourceFilter]

Returns:

The source’s SourceFilter definitions.

find(query)

Find an installed source by a case-insensitive id or name substring.

Parameters:

query (str) – Substring matched against each source’s id and name.

Return type:

Source

Returns:

The first matching Source.

Raises:

LookupError – If no installed source matches query.

nyora.services.manga

Manga browse, search, reader, and metadata operations.

class nyora.services.manga.MangaService(client)

Bases: object

Browse, search, read, and configure manga via the helper.

Attached to a client as client.manga.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

popular(source_id, page=1)

Fetch a page of popular manga from a source.

Parameters:

• source_id (str) – Identifier of the source to query.

• page (int) – One-based page number.

Return type:

SearchPage

Returns:

A SearchPage of entries.

latest(source_id, page=1)

Fetch a page of the latest updated manga from a source.

Parameters:

• source_id (str) – Identifier of the source to query.

• page (int) – One-based page number.

Return type:

SearchPage

Returns:

A SearchPage of entries.

search(source_id, query, page=1, *, filters=None)

Search a source for manga matching a query.

Parameters:

• source_id (str) – Identifier of the source to query.

• query (str) – Free-text search query.

• page (int) – One-based page number.

• filters (list[dict[str, Any]] | None) – Optional source-specific filter selections.

Return type:

SearchPage

Returns:

A SearchPage of matching entries.

global_search(query, *, limit_per_source=8)

Search every installed source at once.

Parameters:

• query (str) – Free-text search query.

• limit_per_source (int) – Maximum entries to return per source.

Return type:

list[GlobalSearchGroup]

Returns:

One GlobalSearchGroup per source.

details(source_id, manga_url, *, manga_id=None)

Fetch full metadata and chapters for one manga.

Parameters:

• source_id (str) – Identifier of the owning source.

• manga_url (str) – The manga’s URL.

• manga_id (str | None) – Optional known manga id to disambiguate.

Return type:

MangaDetails

Returns:

A MangaDetails.

pages(source_id, chapter_url, *, branch=None)

Resolve the readable image pages of a chapter.

Parameters:

• source_id (str) – Identifier of the owning source.

• chapter_url (str) – The chapter’s URL.

• branch (str | None) – Optional scanlation branch/translation to select.

Return type:

list[MangaPage]

Returns:

An ordered list of MangaPage objects.

alternatives(title)

Find alternative editions/sources for a title.

Parameters:

title (str) – The manga title to look up.

Return type:

list[dict[str, Any]]

Returns:

Raw alternative-entry dicts from the helper.

suggestions()

Return personalized manga suggestions.

Return type:

list[Manga]

Returns:

Suggested Manga entries.

prefs(manga_id)

Fetch the stored reader preferences for a manga.

Parameters:

manga_id (str) – Identifier of the manga.

Return type:

MangaPrefs

Returns:

The manga’s MangaPrefs.

save_prefs(manga_id, *, reader_mode='', brightness=0.0, contrast=1.0, saturation=1.0, hue=0.0, palette='')

Save reader preferences for a manga.

Parameters:

• manga_id (str) – Identifier of the manga.

• reader_mode (str) – Reader layout/mode.

• brightness (float) – Brightness adjustment.

• contrast (float) – Contrast multiplier.

• saturation (float) – Saturation multiplier.

• hue (float) – Hue rotation.

• palette (str) – Named color palette.

Return type:

dict[str, Any]

Returns:

The raw helper response.

clear_prefs(manga_id)

Clear stored reader preferences for a manga.

Parameters:

manga_id (str) – Identifier of the manga.

Return type:

dict[str, Any]

Returns:

The raw helper response.

nyora.services.library

Library, history, favourites, bookmarks, and categories.

class nyora.services.library.LibraryService(client)

Bases: object

Manage reading history, favourites, bookmarks, and categories.

Attached to a client as client.library.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

history(limit=100)

Return recent reading history.

Parameters:

limit (int) – Maximum number of entries to return.

Return type:

list[HistoryEntry]

Returns:

The most recent HistoryEntry records.

record_history(*, manga_id, chapter_id, page, percent)

Record reading progress for a chapter.

Parameters:

• manga_id (str) – Identifier of the manga.

• chapter_id (str) – Identifier of the chapter read.

• page (int) – Last-read page index.

• percent (float) – Read progress fraction within the chapter.

Return type:

dict[str, Any]

Returns:

The raw helper response.

remove_history(manga_id, chapter_id=None)

Remove history for a manga, optionally narrowed to one chapter.

Parameters:

• manga_id (str) – Identifier of the manga.

• chapter_id (str | None) – Optional chapter to remove; omit to remove all history for the manga.

Return type:

dict[str, Any]

Returns:

The raw helper response.

clear_history()

Clear all reading history.

Return type:

dict[str, Any]

Returns:

The raw helper response.

favourites(category_id=None)

List favourited manga, optionally filtered by category.

Parameters:

category_id (int | None) – Optional category to filter by.

Return type:

list[Manga]

Returns:

The favourited Manga entries.

toggle_favourite(manga_id)

Toggle a manga’s favourite state.

Parameters:

manga_id (str) – Identifier of the manga.

Return type:

dict[str, Any]

Returns:

The raw helper response.

is_favourite(manga_id)

Check whether a manga is favourited.

Parameters:

manga_id (str) – Identifier of the manga.

Return type:

bool

Returns:

True if the manga is favourited.

bookmarks(manga_id=None)

List bookmarks, optionally scoped to one manga.

Parameters:

manga_id (str | None) – Optional manga to scope to.

Return type:

list[dict[str, Any]]

Returns:

Raw bookmark dicts.

add_bookmark(*, manga_id, chapter_id, page, title='')

Add a bookmark at a specific page.

Parameters:

• manga_id (str) – Identifier of the manga.

• chapter_id (str) – Identifier of the chapter.

• page (int) – Page index to bookmark.

• title (str) – Optional bookmark label.

Return type:

dict[str, Any]

Returns:

The raw helper response.

remove_bookmark(*, manga_id, chapter_id, page)

Remove a bookmark at a specific page.

Parameters:

• manga_id (str) – Identifier of the manga.

• chapter_id (str) – Identifier of the chapter.

• page (int) – Page index of the bookmark to remove.

Return type:

dict[str, Any]

Returns:

The raw helper response.

categories()

List the user’s library categories.

Return type:

list[Category]

Returns:

The Category records.

create_category(title)

Create a new library category.

Parameters:

title (str) – Title for the new category.

Return type:

Category | dict[str, Any]

Returns:

The created Category, or the raw response.

rename_category(category_id, title)

Rename a category.

Parameters:

• category_id (int) – Identifier of the category.

• title (str) – New title.

Return type:

dict[str, Any]

Returns:

The raw helper response.

delete_category(category_id)

Delete a category.

Parameters:

category_id (int) – Identifier of the category to delete.

Return type:

dict[str, Any]

Returns:

The raw helper response.

add_to_category(manga_id, category_id)

Add a manga to a category.

Parameters:

• manga_id (str) – Identifier of the manga.

• category_id (int) – Identifier of the category.

Return type:

dict[str, Any]

Returns:

The raw helper response.

remove_from_category(manga_id, category_id)

Remove a manga from a category.

Parameters:

• manga_id (str) – Identifier of the manga.

• category_id (int) – Identifier of the category.

Return type:

dict[str, Any]

Returns:

The raw helper response.

updates()

List pending library update entries.

Return type:

list[dict[str, Any]]

Returns:

Raw update-entry dicts.

refresh_updates()

Trigger a refresh of library updates.

Return type:

dict[str, Any]

Returns:

The raw helper response.

mark_update_seen(update_id)

Mark a library update as seen.

Parameters:

update_id (str) – Identifier of the update entry.

Return type:

dict[str, Any]

Returns:

The raw helper response.

nyora.services.downloads

Download operations.

class nyora.services.downloads.DownloadsService(client)

Bases: object

Start, enqueue, monitor, and configure chapter downloads.

Attached to a client as client.downloads.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

list()

List current download tasks.

Return type:

list[Download]

Returns:

The Download tasks.

start(*, source_id, manga_url, chapter_url, manga_title='', chapter_title='')

Start downloading a single chapter.

Parameters:

• source_id (str) – Identifier of the owning source.

• manga_url (str) – URL of the manga.

• chapter_url (str) – URL of the chapter to download.

• manga_title (str) – Optional manga title for display.

• chapter_title (str) – Optional chapter title for display.

Return type:

Download

Returns:

The created Download task.

enqueue(*, source_id, manga_url, chapters, manga_title='')

Enqueue multiple chapters for download.

Parameters:

• source_id (str) – Identifier of the owning source.

• manga_url (str) – URL of the manga.

• chapters (list[dict[str, Any]]) – Chapter descriptor dicts to enqueue.

• manga_title (str) – Optional manga title for display.

Return type:

list[Download]

Returns:

The created Download tasks.

cancel(download_id)

Cancel a download task.

Parameters:

download_id (str) – Identifier of the download to cancel.

Return type:

dict[str, Any]

Returns:

The raw helper response.

settings()

Return the current download settings.

Return type:

DownloadSettings

Returns:

The DownloadSettings.

save_settings(*, max_concurrent=None, format=None)

Update download settings.

Parameters:

• max_concurrent (int | None) – New maximum simultaneous downloads, if changing.

• format (str | None) – New output format, if changing.

Return type:

DownloadSettings

Returns:

The updated DownloadSettings.

nyora.services.backup

Includes BackupService, SyncService, LocalService, TrackerService, and SystemService.

Backup, sync, local file, tracker, and system operations.

Defines several helper-backed services: BackupService (export/import), SyncService (Supabase cloud sync), LocalService (local file scanning), TrackerService (AniList tracking), and SystemService (stats, settings, OTA) which composes the sync, local, and tracker services. SystemService is attached to a client as client.system; the rest are reachable as client.system.sync etc.

class nyora.services.backup.BackupService(client)

Bases: object

Export and import the helper’s library backup.

Attached to a client as client.backup.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

export()

Export the full backup archive.

Return type:

Any

Returns:

The backup payload as returned by the helper.

import_(backup_json)

Import a previously exported backup.

Parameters:

backup_json (str | bytes) – The backup payload as JSON text or bytes.

Return type:

BackupImportResult

Returns:

A BackupImportResult summarizing the import.

class nyora.services.backup.SyncService(client)

Bases: object

Supabase-backed cloud sync operations.

Reachable as client.system.sync.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

status()

Return the current cloud-sync status.

Return type:

dict[str, Any]

Returns:

The raw status payload.

sign_in(id_token)

Sign in to the cloud-sync backend.

Parameters:

id_token (str) – OAuth/identity token to authenticate with.

Return type:

dict[str, Any]

Returns:

The raw helper response.

sign_out()

Sign out of the cloud-sync backend.

Return type:

dict[str, Any]

Returns:

The raw helper response.

sync()

Run a cloud sync.

Return type:

dict[str, Any]

Returns:

The raw helper response.

restore_from_cloud()

Restore local data from the cloud copy.

Return type:

dict[str, Any]

Returns:

The raw helper response.

has_local_data()

Check whether local data exists that could be synced.

Return type:

bool

Returns:

True if local data is present.

class nyora.services.backup.LocalService(client)

Bases: object

Scan and read locally stored manga files.

Reachable as client.system.local.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

scan(folder)

Scan a folder for local manga archives.

Parameters:

folder (str) – Filesystem path to scan.

Return type:

list[dict[str, Any]]

Returns:

Raw entry dicts for the discovered items.

chapter(cbz)

Read metadata for a local chapter archive.

Parameters:

cbz (str) – Path to the .cbz archive.

Return type:

dict[str, Any]

Returns:

The raw chapter payload.

class nyora.services.backup.TrackerService(client)

Bases: object

Progress-tracking integrations (AniList).

Reachable as client.system.tracker.

Parameters:

client (Nyora)

Bind the service to a helper client.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

anilist_search(query)

Search AniList for a media entry.

Parameters:

query (str) – Free-text search query.

Return type:

dict[str, Any]

Returns:

The raw AniList search payload.

anilist_scrobble(*, token, media_id, progress)

Update AniList reading progress for a media entry.

Parameters:

• token (str) – AniList access token.

• media_id (int) – AniList media identifier.

• progress (int) – New progress (chapters read).

Return type:

dict[str, Any]

Returns:

The raw AniList response.

class nyora.services.backup.SystemService(client)

Bases: object

System-level operations: stats, settings, OTA, and sub-services.

Attached to a client as client.system. Composes SyncService (.sync), LocalService (.local), and TrackerService (.tracker).

Variables:

• sync – Cloud-sync operations.

• local – Local-file operations.

• tracker – Progress-tracking operations.

Parameters:

client (Nyora)

Bind the service to a helper client and build sub-services.

Parameters:

client (Nyora) – The owning nyora.client.Nyora instance.

stats()

Return aggregate reading statistics.

Return type:

Stats

Returns:

The Stats.

network_settings()

Return the current network settings.

Return type:

dict[str, Any]

Returns:

The settings dict.

save_network_settings(**settings)

Update network settings.

Parameters:

**settings (Any) – Setting key/value pairs to apply.

Return type:

dict[str, Any]

Returns:

The updated settings dict.

ota_status()

Return the helper’s OTA parser-feed status.

Return type:

dict[str, Any]

Returns:

The raw OTA status payload.

ota_check()

Trigger an OTA update check on the helper.

Return type:

dict[str, Any]

Returns:

The raw OTA check payload.