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 cloud client, the async client, the cloud-sync client, 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 manga sources SDK. The default client (nyora.Nyora) is a thin client over the Nyora cloud helper (https://api.hasanraza.tech — the kotatsu-parsers engine, ~960 sources): it runs no parsers in-process, speaking the helper’s REST contract over httpx. nyora.sync.NyoraSync adds account and library sync against the Nyora cloud (https://stream.hasanraza.tech).

This module is the public surface of the SDK. It re-exports the primary client (and the async nyora.AsyncNyora), the cloud sync client, 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.client`¶

The cloud clients (Nyora, AsyncNyora) and the CLOUD_BASE_URL default.

Nyora helper HTTP clients.

This module provides the cloud-backed REST clients. They run no parsers themselves; they speak the camelCase helper REST contract over HTTP via httpx against the Nyora cloud helper.

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 base URL defaults to the public Nyora cloud (https://api.hasanraza.tech); it can be overridden with an explicit argument, the NYORA_BASE_URL environment variable, or a local helper’s port file. A self-hosted helper jar can also be launched and managed via Nyora.managed().

nyora.client.CLOUD_BASE_URL = 'https://api.hasanraza.tech'¶: Public Nyora cloud helper. Used by default so a bare Nyora() works with no local helper — the SDK is a thin cloud client.

class nyora.client.Nyora(base_url=None, *, timeout=60.0, helper=None)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Close the HTTP connection and stop any managed helper process.

Return type:: None

health()[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Close the underlying async HTTP connection.

Return type:: None

async health()[source]¶

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)[source]¶

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.sync`¶

Cloud account and library sync (NyoraSync) against the Nyora sync server.

Nyora cloud sync — account + library sync against the self-hosted sync server.

NyoraSync talks to the Nyora sync server (https://stream.hasanraza.tech) using an OAuth2 password flow + JWT, then a generic last-write-wins upsert/select over the per-user tables (nyora_manga, nyora_favourite, tracking, …). It mirrors the iOS NyoraSyncClient and replaces the old Supabase-based sync.

Tokens are held in memory and, when a token_path is given, persisted to disk so a process can stay signed in across runs.

class nyora.sync.NyoraSync(base_url=None, *, timeout=30.0, token_path=None)[source]¶

Bases: object

Account and library sync against the Nyora sync server.

Example

>>> sync = NyoraSync()
>>> sync.sign_in("me@example.com", "hunter2")
>>> sync.upsert("nyora_manga", [{"key": "...", "source": "...", "title": "..."}])
>>> rows = sync.select("nyora_manga")

Parameters:

base_url (str | None)
timeout (float)
token_path (str | PathLike[str] | None)

Create a sync client.

Parameters:

base_url (str | None) – Sync server base URL. Defaults to https://stream.hasanraza.tech (or the NYORA_SYNC_URL env var).
timeout (float) – Per-request HTTP timeout in seconds.
token_path (str | PathLike[str] | None) – Where to persist tokens. None uses the default user config path; pass False-y string to disable persistence.

property is_signed_in: bool¶: Whether an access token is currently held.

register(email, password)[source]¶

Parameters:

email (str)
password (str)

Return type:

None

sign_in(email, password)[source]¶

Parameters:

email (str)
password (str)

Return type:

None

sign_out()[source]¶

Forget the stored tokens.

Return type:: None

upsert(table, rows)[source]¶

Last-write-wins upsert of rows into table. Returns rows written.

Parameters:

table (str)
rows (list[dict[str, Any]])

Return type:

int

select(table, since=None)[source]¶

Fetch rows from table, optionally only those changed after since.

Parameters:

table (str)
since (str | None)

Return type:

list[dict[str, Any]]

delete_extension_repo(type, base_url)[source]¶

Hard-delete one extension-repo row for the signed-in user.

Parameters:

type (str)
base_url (str)

Return type:

None

close()[source]¶

Close the underlying HTTP client.

Return type:: None

exception nyora.sync.NotSignedInError[source]¶

Bases: RuntimeError

Raised when a sync operation is attempted without signing in.

`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 cloud 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.Nyora and the service objects.

class nyora.models.MangaPage(url, headers=<factory>)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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>)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Build a MangaDetails from a raw payload.

Parameters:: data (Any) – An object with manga and chapters.
Return type:: MangaDetails
Returns:: The parsed details.

reading_order()[source]¶

Return the chapters in canonical reading order (earliest first).

Sources order their chapter arrays inconsistently (ascending on some, descending on others); this normalises them so index 0 is always the earliest chapter.

Return type:: list[MangaChapter]

next_chapter(current)[source]¶

Return the next (later) chapter after current, order-independent.

Parameters:: current (MangaChapter)
Return type:: MangaChapter | None

previous_chapter(current)[source]¶

Return the previous (earlier) chapter before current, order-independent.

Parameters:: current (MangaChapter)
Return type:: MangaChapter | None

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

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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')[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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>)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Build a BackupImportResult from a raw payload.

Parameters:: data (Any) – A result object from the helper.
Return type:: BackupImportResult
Returns:: The parsed result.

`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[source]¶

Bases: Exception

Base exception for Nyora SDK failures.

exception nyora.errors.HelperNotFoundError[source]¶

Bases: NyoraError

Raised when no running helper can be discovered.

exception nyora.errors.HelperLaunchError[source]¶

Bases: NyoraError

Raised when a managed helper process fails to start.

exception nyora.errors.NyoraHTTPError(status_code, message, *, body='')[source]¶

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`¶

Endpoint-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()[source]¶

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)[source]¶

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 client (nyora.client.Nyora).

`nyora.services.sources`¶

Source catalog operations.

class nyora.services.sources.SourcesService(client)[source]¶

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()[source]¶

List the installed sources.

Return type:: list[Source]
Returns:: The installed Source records.

catalog()[source]¶

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

Return type:: list[Source]
Returns:: All catalog Source records.

refresh()[source]¶

Refresh the source catalog from the remote feed.

Return type:: list[Source]
Returns:: The refreshed list of Source records.

install(source_id)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Return personalized manga suggestions.

Return type:: list[Manga]
Returns:: Suggested Manga entries.

prefs(manga_id)[source]¶

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='')[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

Clear all reading history.

Return type:: dict[str, Any]
Returns:: The raw helper response.

favourites(category_id=None)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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='')[source]¶

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)[source]¶

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()[source]¶

List the user’s library categories.

Return type:: list[Category]
Returns:: The Category records.

create_category(title)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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()[source]¶

List pending library update entries.

Return type:: list[dict[str, Any]]
Returns:: Raw update-entry dicts.

refresh_updates()[source]¶

Trigger a refresh of library updates.

Return type:: dict[str, Any]
Returns:: The raw helper response.

mark_update_seen(update_id)[source]¶

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)[source]¶

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()[source]¶

List current download tasks.

Return type:: list[Download]
Returns:: The Download tasks.

start(*, source_id, manga_url, chapter_url, manga_title='', chapter_title='')[source]¶

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='')[source]¶

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)[source]¶

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()[source]¶

Return the current download settings.

Return type:: DownloadSettings
Returns:: The DownloadSettings.

save_settings(*, max_concurrent=None, format=None)[source]¶

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, LocalService, TrackerService, and SystemService.

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

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

Cloud sync is a separate client: nyora.sync.NyoraSync.

class nyora.services.backup.BackupService(client)[source]¶

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()[source]¶

Export the full backup archive.

Return type:: Any
Returns:: The backup payload as returned by the helper.

import_(backup_json)[source]¶

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.LocalService(client)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Bases: object

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

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

Cloud sync now lives in the standalone nyora.sync.NyoraSync client (OAuth2/JWT against the Nyora sync server), not on client.system.

Variables:

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()[source]¶

Return aggregate reading statistics.

Return type:: Stats
Returns:: The Stats.

network_settings()[source]¶

Return the current network settings.

Return type:: dict[str, Any]
Returns:: The settings dict.

save_network_settings(**settings)[source]¶

Update network settings.

Parameters:: **settings (Any) – Setting key/value pairs to apply.
Return type:: dict[str, Any]
Returns:: The updated settings dict.

ota_status()[source]¶

Return the helper’s OTA parser-feed status.

Return type:: dict[str, Any]
Returns:: The raw OTA status payload.

ota_check()[source]¶

Trigger an OTA update check on the helper.

Return type:: dict[str, Any]
Returns:: The raw OTA check payload.

API reference¶

Package overview¶

nyora.client¶

nyora.sync¶

nyora.models¶

nyora.errors¶

nyora.config¶

Services¶

nyora.services.sources¶

nyora.services.manga¶

nyora.services.library¶

nyora.services.downloads¶

nyora.services.backup¶

`nyora.client`¶

`nyora.sync`¶

`nyora.models`¶

`nyora.errors`¶

`nyora.config`¶

`nyora.services.sources`¶

`nyora.services.manga`¶

`nyora.services.library`¶

`nyora.services.downloads`¶

`nyora.services.backup`¶