API reference ¶

Returns:

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

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.
NyoraTransportError – If the engine is unreachable after retries.

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:

Returns:

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

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.
NyoraTransportError – If the engine is unreachable after retries.

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:

Returns:

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

Raises:

NyoraHTTPError – If the helper returns a 4xx/5xx response.
NyoraTransportError – If the engine is unreachable after retries.

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

Bases: object

Asynchronous Nyora client for the read/browse surface.

Wraps an httpx.AsyncClient and exposes async sources and manga services (browse, search, details, pages) plus raw get/post/delete — with the same automatic retries and User-Agent as Nyora. Use as an async context manager to release the connection on exit.

Unlike Nyora, this client does not launch a bundled engine; point it at a running/configured server.

Variables:

base_url (str) – The resolved helper base URL.
sources – async source listing / lookup.
manga – async browse, search, details, pages (with iter_* pagers).

Example

>>> async with AsyncNyora.attach() as client:
...     src = await client.sources.find("mangadex")
...     async for manga in client.manga.iter_popular(src.id, limit=30):
...         print(manga.title)

Parameters:

base_url (str | None)
timeout (float)
retries (RetryConfig | int | None)

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.
retries (RetryConfig | int | None) – Retry policy (int or RetryConfig).

Raises:

HelperNotFoundError – If no helper can be discovered.

classmethod attach(base_url=None, *, timeout=60.0, retries=None)[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.
retries (RetryConfig | int | None) – Retry policy (int or RetryConfig).

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]

async get(path, *, params=None)[source]¶

Issue a GET request against the helper (with retries).

Parameters:

path (str)
params (dict[str, Any] | None)

Return type:

async post(path, *, params=None, json=None, content=None)[source]¶

Issue a POST request against the helper (with retries).

Parameters:

path (str)
params (dict[str, Any] | None)
json (Any | None)
content (str | bytes | None)

Return type:

async delete(path, *, params=None)[source]¶

Issue a DELETE request against the helper (with retries).

Parameters:

path (str)
params (dict[str, Any] | None)

Return type:

`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://sync.nyora.xyz) using an OAuth2 password flow + JWT. It offers a generic last-write-wins upsert/select transport, plus high-level favourite/history helpers that build rows through nyora.schema so they stay field-compatible with the nyora-web sync client. Row shapes are the single source of truth in nyora.schema.

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

>>> from nyora import Nyora
>>> sync = NyoraSync()
>>> sync.sign_in("[email protected]", "hunter2")
>>> with Nyora() as client:
...     manga = client.manga.popular("mangadex").entries[0]
...     sync.favourite("mangadex", manga)     # schema-correct upserts
>>> [row["title"] for row in sync.favourites()]
['...']

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://sync.nyora.xyz (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:

sign_in(email, password)[source]¶

Parameters:

email (str)
password (str)

Return type:

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

favourite(source_id, manga)[source]¶

Add manga to the cloud library (manga + favourite rows). Returns the id.

Parameters:

source_id (str)
manga (Any)

Return type:

str

unfavourite(manga_id)[source]¶

Soft-delete a favourite (last-write-wins tombstone).

Parameters:: manga_id (str)
Return type:: None

favourites()[source]¶

Return live favourites joined with their manga metadata (friendly view).

Return type:: list[dict[str, Any]]

record_history(source_id, manga, chapter, *, page=0, total=0, percent=0.0)[source]¶

Record reading progress for a chapter (manga + history rows).

Parameters:

source_id (str)
manga (Any)
chapter (Any)
page (int)
total (int)
percent (float)

Return type:

str

history()[source]¶

Return reading history (newest first) joined with manga metadata.

Return type:: list[dict[str, Any]]

push_snapshot(favourites, history)[source]¶

Bulk-push a device’s local library (favourites + history) to the cloud.

Mirrors nyora-web’s pushAll: one upsert per table, with a deduped nyora_manga row for each referenced title so joins resolve on pull.

Parameters:

favourites (list[dict[str, Any]])
history (list[dict[str, Any]])

Return type:

sync_now(favourites, history)[source]¶

Push the local library up, then pull the merged cloud state back down.

The web-parity primitive: pushAll then pullAll. Returns the cloud (favourites, history) for the caller to merge into its local store.

Parameters:

favourites (list[dict[str, Any]])
history (list[dict[str, Any]])

Return type:

tuple[list[dict[str, Any]], list[dict[str, Any]]]

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

Bases: NyoraError

Base for network/transport failures reaching the engine (after retries).

exception nyora.errors.NyoraTimeoutError[source]¶

Bases: NyoraTransportError

Raised when a request exceeds its timeout, and retries are exhausted.

exception nyora.errors.NyoraConnectionError[source]¶

Bases: NyoraTransportError

Raised when the engine is unreachable, and retries are exhausted.

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

Path of the persisted SDK config (NYORA_CONFIG_FILE override, else the platform user-config dir). Stores the preferred server URL and blocklist cache location so nyora uses your server, not the cloud, across runs.

Return type:: Path

nyora.config.read_config()[source]¶

Return the persisted config dict ({} if absent/corrupt).

Return type:: dict

nyora.config.write_config(data)[source]¶

Persist the config dict to config_file().

Parameters:: data (dict)
Return type:: None

nyora.config.read_base_url_from_config()[source]¶

Return the user’s persisted preferred server URL, or None.

Return type:: str | None

nyora.config.set_config_base_url(url)[source]¶

Persist (or clear, when url is falsy) the preferred server URL.

Parameters:: url (str | None)
Return type:: None

nyora.config.read_theme_from_config()[source]¶

Return the user’s persisted TUI colour-scheme id, or None.

Return type:: str | None

nyora.config.set_config_theme(theme_id)[source]¶

Persist (or clear, when theme_id is falsy) the TUI colour scheme.

Parameters:: theme_id (str | None)
Return type:: None

nyora.config.read_ui_lang()[source]¶

Return the user’s persisted TUI interface language code, or None.

Return type:: str | None

nyora.config.set_ui_lang(code)[source]¶

Persist (or clear, when code is falsy) the TUI interface language.

Parameters:: code (str | None)
Return type:: None

nyora.config.read_onboarded()[source]¶

Return whether the user has passed the welcome screen at least once.

Return type:: bool

nyora.config.set_onboarded(value=True)[source]¶

Mark (or clear) the one-time welcome screen as seen.

Parameters:: value (bool)
Return type:: None

nyora.config.read_show_nsfw()[source]¶

Return whether adult (18+) sources should be shown.

Return type:: bool

nyora.config.set_show_nsfw(value)[source]¶

Persist the 18+ content preference.

Parameters:: value (bool)
Return type:: None

nyora.config.read_languages()[source]¶

Return the user’s chosen language filter (empty = all languages).

Return type:: list[str]

nyora.config.set_languages(langs)[source]¶

Persist the language filter (a list of locale codes; empty = all).

Parameters:: langs (list[str])
Return type:: None

nyora.config.read_reader_prefs()[source]¶

Return persisted reader preferences (mode, fit), or {}.

Return type:: dict

nyora.config.set_reader_pref(key, value)[source]¶

Persist a single reader preference (e.g. mode or fit).

Parameters:

key (str)
value (str)

Return type:

list[GlobalSearchGroup]

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

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

Attached to a client as client.sources.

Parameters:: client (Nyora)

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

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

Attached to a client as client.manga.

Parameters:: client (Nyora)

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.

iter_popular(source_id, *, start_page=1, max_pages=None, limit=None)[source]¶

Auto-paging iterator over popular manga across all pages.

Parameters:

source_id (str) – Identifier of the source to query.
start_page (int) – First (1-based) page to fetch.
max_pages (int | None) – Stop after this many pages (None = until exhausted).
limit (int | None) – Stop after yielding this many manga (None = no cap).

Return type:

MangaPager

Returns:

A MangaPager — iterate for Manga.

iter_latest(source_id, *, start_page=1, max_pages=None, limit=None)[source]¶

Auto-paging iterator over the latest-updated manga across all pages.

Parameters:

source_id (str)
start_page (int)
max_pages (int | None)
limit (int | None)

Return type:

MangaPager

iter_search(source_id, query, *, start_page=1, max_pages=None, limit=None, filters=None)[source]¶

Auto-paging iterator over search results across all pages.

Parameters:

source_id (str)
query (str)
start_page (int)
max_pages (int | None)
limit (int | None)
filters (list[dict[str, Any]] | None)

Return type:

MangaPager

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:

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:

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

Manage reading history, favourites, bookmarks, and categories.

Attached to a client as client.library.

Parameters:: client (Nyora)

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:

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:

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:

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:

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:

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:

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:

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

Start, enqueue, monitor, and configure chapter downloads.

Attached to a client as client.downloads.

Parameters:: client (Nyora)

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

Export and import the helper’s library backup.

Attached to a client as client.backup.

Parameters:: client (Nyora)

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

Scan and read locally stored manga files.

Reachable as client.system.local.

Parameters:: client (Nyora)

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

Progress-tracking integrations (AniList).

Reachable as client.system.tracker.

Parameters:: client (Nyora)

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: