lanraragi_api.api package<a class="headerlink" href="#lanraragi-api-api-package" title="Link to this heading">¶

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

clear_archive_new_flag(id: str) → OperationResponse¶

Clear the “New!” flag on an archive.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

delete_archive(id: str) → OperationResponse¶

Delete both the archive metadata and the file stored on the server.

Please ask your user for confirmation before invoking this endpoint.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

delete_archive_toc(id: str, page: int) → OperationResponse¶

Delete an entry from the Table of Contents of a given Archive.

Parameters:

id – ID of the Archive to process.
page – Page number of the chapter/section to delete.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

download_archive(id: str) → Response¶

Download an Archive from the server.

Parameters:: id – ID of the Archive to download.
Returns:: Response of the server carrying the archive file.
Return type:: Response
Raises:: APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

extract_archive(id: str, force: bool = False) → dict[Any, Any]¶

Get a list of URLs pointing to the images contained in an archive.

If necessary, this endpoint also launches a background Minion job to extract the archive so it is ready for reading.

Parameters:

id – ID of the Archive to process.
force – Force a full background re-extraction of the Archive. Existing cached files might still be used in subsequent /api/archives/:id/page calls until the Archive is fully re-extracted. Defaults to False.

Returns:

Decoded response, with the page URLs in pages and the ID: of the background extract job in job.

Return type:

dict

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

get_all_archives() → list[ArchiveMetadata]¶

Return a list of all Archives in the database.

This doesn’t include Tankoubons by design. You can use the IDs of this JSON with the other endpoints.

Returns:

Metadata of every Archive in the database.

Return type:

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list of objects matching ArchiveMetadata.

get_archive(id: str) → ArchiveMetadata | None¶

Get Metadata (title, tags) for a given Archive.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of the archive, or None when the: server answers with 400.

Return type:

ArchiveMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

This endpoint is deprecated; use get_archive_metadata instead. The 400 response, sent when no archive ID was given, is turned into None instead of raising.

get_archive_categories(id: str) → list[CategoryMetadata]¶

Get all the Categories which currently refer to this Archive ID.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of every Category referring to: this Archive.

Return type:

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.
APIResponseDecodeError – If the response has no categories list, or if an item does not match CategoryMetadata.

get_archive_metadata(id: str) → ArchiveMetadata | None¶

Get Metadata (title, tags) for a given Archive.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of the archive, or None when the: server answers with 400.

Return type:

ArchiveMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

The 400 response, sent when no archive ID was given, is turned into None instead of raising.

get_archive_page(id: str, path: str) → Response¶

Get an archive page.

This call is mainly used alongside /api/archives/files.

Parameters:

id – ID of the Archive to download.
path – Path to the image in the extracted archive files.

Returns:

Response of the server carrying the image.

Return type:

Response

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

get_archive_tankoubons(id: str) → list[str]¶

Get all the Tankoubons which currently refer to this Archive ID.

Tankoubon (単行本) is the Japanese term for a bound volume.

Parameters:

id – ID of the Archive to process.

Returns:

IDs of the Tankoubons referring to this Archive.

Return type:

list[str]

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.
APIResponseDecodeError – If the response has no tankoubons list.

get_archive_thumbnail(id: str, page: int = 1, no_fallback: bool | None = None) → Response¶

Get a Thumbnail image for a given Archive.

This endpoint will return a placeholder image if it doesn’t already exist. If you want to queue generation of the thumbnail in the background, use the no_fallback parameter: you will get a background job ID instead of the placeholder.

Parameters:

id – ID of the Archive to process.
page – Specify which page you want to get a thumbnail for. Defaults to 1, the cover.
no_fallback – Disables the placeholder image, queues the thumbnail for extraction and returns a JSON with code 202. This parameter does nothing if the image already exists. (You will get the image with code 200 no matter what) Defaults to None.

Returns:

Response of the server, either the thumbnail bytes with: code 200 or the job JSON with code 202.

Return type:

Response

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

Note

A queued extraction returns a Minion job ID; use /api/minion/:jobid to track when the thumbnail is ready.

get_untagged_archives() → list[str]¶

Get Archives that don’t have any tags recorded.

This follows the same rules as the Batch Tagging filter and will include Archives that have parody:, date_added:, series: or artist: tags.

Returns:

IDs of the Archives that have no tags recorded.

Return type:

list[str]

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list.

queue_extraction_of_page_thumbnails(id: str, force: bool = False) → MinionJobResponse¶

Create thumbnails for every page of a given Archive.

This endpoint will queue generation of the thumbnails in the background.

If all thumbnails are detected as already existing, the call will return HTTP code 200.

This endpoint can be called multiple times – If a thumbnailing job is already in progress for the given ID, it’ll just give you the ID for that ongoing job.

Parameters:

id – ID of the Archive to process.
force – Whether to force regeneration of all thumbnails even if they already exist. Defaults to False.

Returns:

Result of the operation, with the ID of the: queued or ongoing Minion job in job.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

The job field is None when all thumbnails already exist and the server answers with code 200 instead of queueing a job. A 400 response is returned in the operation result, with success set to 0, instead of raising.

set_archive_new_flag(id: str) → OperationResponse¶

Set or restore the “New!” flag on an archive.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

update_archive_metadata(id: str, archive: ArchiveMetadata | None = None, *, title: str | None = None, tags: str | None = None, summary: str | None = None) → OperationResponse¶

Update tags, title and summary for the given Archive.

Data supplied to the server through this method will overwrite the previous data.

Parameters:

id – ID of the Archive to process.
archive – Optional backward-compatible metadata object, used to fill title, tags or summary when they are omitted. Defaults to None.
title – Archive title to set. If omitted and archive is provided, archive.title is used. Defaults to None.
tags – Archive tags string to set. If omitted and archive is provided, archive.tags is used. Defaults to None.
summary – Archive summary to set. If omitted and archive is provided, archive.summary is used. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

update_reading_progression(id: str, page: int) → OperationResponse¶

Tell the server which page of this Archive you are currently reading.

This endpoint will also update the date this Archive was last read, using the current server timestamp.

You should call this endpoint only when you’re sure the user is currently reading the page you present. Don’t use it when preloading images off the server.

Whether to make reading progression regressible or not is up to the client. (The web client will reduce progression if the user starts reading previous pages)

Consider however removing the “New!” flag from an archive when you start updating its progress - The web client won’t display any reading progression if the new flag is still set.

Parameters:

id – ID of the Archive to process.
page – Current page to update the reading progress to. Must be a positive integer, and inferior or equal to the total page number of the archive.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response), 401 (authentication required) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising. If the server is configured to use clientside progress tracking, this API call returns an error. Check with /api/info whether the server tracks reading progression before calling this endpoint.

update_thumbnail(id: str, page: int = 1) → OperationResponse¶

Update the cover thumbnail for the given Archive.

You can specify a page number to use as the thumbnail, or you can use the default thumbnail.

Parameters:

id – ID of the Archive to process.
page – Page you want to make the thumbnail out of. Defaults to 1.

Returns:

Result of the operation, with the path of the: new thumbnail in the extra new_thumbnail field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

Upload an Archive to the server.

If a SHA1 checksum of the Archive is included, the server will perform an optional in-transit, file integrity validation, and reject the upload if the server-side checksum does not match.

Parameters:

archive – str type for path of the archive file to upload, or a tuple made up of a filename and the file content in bytes.
title – Title of the Archive. Defaults to None.
tags – Set of tags you want to insert in the database alongside the archive. Defaults to None.
summary – Summary of the Archive. Defaults to None.
category_id – Category ID you’d want the archive to be added to. Defaults to None.
file_checksum – SHA1 checksum of the archive for in-transit validation. Defaults to None.

Returns:

Result of the operation, with the ID of the: uploaded Archive in the extra id field.

Return type:

Raises:

FileNotFoundError – If archive points to an no-existing file.
APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Uploading an archive that already exists is reported with a 409 response, whose body carries the reason in the error field. Other failure responses, such as 415 (unsupported file), 417 (checksum mismatch) or 422 (unprocessable entity), are returned in the operation result, with success set to 0, instead of raising.

lanraragi_api.api.base module¶

class lanraragi_api.api.base.BaseAPICall(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: object

Base class for every API section, handling transport and errors.

Subclasses expose one method per endpoint. Those methods build their request through the request_* helpers below, which send the call and decode the payload into pydantic models.

Parameters:

server – Base URL of the LANraragi server, with or without a trailing slash.
key – API key sent with every request. Defaults to None, which sends no credentials.
auth_way – How the API key is transmitted. Defaults to Auth.AUTH_HEADER.
timeout – Timeout applied to every request, either a single value or a (connect, read) pair. Defaults to None, meaning no timeout.
include_error_payload – Whether APIOperationError carries the raw response payload. Defaults to False.
include_operation_error_message – Whether APIOperationError carries the error message reported by the server. Defaults to True.
raise_on_operation_error – Whether a failed operation raises APIOperationError instead of being returned to the caller. Defaults to False.
default_headers – Extra headers sent with every request. Defaults to None, which sends no extra headers.
default_params – Extra query parameters sent with every request. Defaults to None, which sends no extra parameters.

Raises:

APIRequestError – From any endpoint method, when a request cannot be sent to the server because of a connection failure or a timeout.

parse_json_response(response: Response, path: str)¶

Decode the body of a response as JSON.

Parameters:

response – Response to decode.
path – Path of the request, used in error messages.

Returns:

The decoded JSON payload.

Raises:

APIResponseDecodeError – If the body is not valid JSON.

parse_model(model: type[T], payload: Any, path: str) → T¶

Validate a decoded payload against a pydantic model.

Parameters:

model – Model to validate the payload with.
payload – Decoded JSON payload.
path – Path of the request, used in error messages.

Returns:

Instance of model built from payload.

Return type:

BaseModel

Raises:

APIResponseDecodeError – If payload does not match model.

parse_model_list(model: type[T], payload: Any, path: str) → list[T]¶

Validate a decoded payload as a list of a pydantic model.

Parameters:

model – Model to validate every item of the payload with.
payload – Decoded JSON payload, expected to be a list.
path – Path of the request, used in error messages.

Returns:

One instance of model per item.

Return type:

list[BaseModel]

Raises:

APIResponseDecodeError – If payload is not a list, or if any item does not match model.

Send an HTTP request and return the raw response.

Parameters:

method – HTTP method to use.
path – Path of the request.
params – Query parameters for this request. Defaults to None.
headers – Headers for this request. Defaults to None.
expected_statuses – Status codes considered a success. Defaults to None, which accepts every 2xx status.
timeout – Timeout for this request, overriding the client timeout. Defaults to None, which uses the client timeout.
**kwargs – Extra arguments forwarded to requests.request, such as data, json, files or stream.

Returns:

Response returned by the server.

Return type:

requests.Response

Raises:

APIRequestError – If the request cannot be sent to the server.
APIHttpError – If the status code of the response is not part of expected_statuses.

Send a request and decode its body as JSON.

Parameters:

method – HTTP method to use.
path – Path of the request.
params – Query parameters for this request. Defaults to None.
headers – Headers for this request. Defaults to None.
expected_statuses – Status codes considered a success. Defaults to None, which accepts every 2xx status.
timeout – Timeout for this request, overriding the client timeout. Defaults to None, which uses the client timeout.
**kwargs – Extra arguments forwarded to requests.request.

Returns:

The decoded JSON payload.

Raises:

APIRequestError – If the request cannot be sent to the server.
APIHttpError – If the status code of the response is not part of expected_statuses.
APIResponseDecodeError – If the body is not valid JSON.

Send a request and validate its JSON body against a model.

Parameters:

method – HTTP method to use.
path – Path of the request.
model – Model to validate the body with.
params – Query parameters for this request. Defaults to None.
headers – Headers for this request. Defaults to None.
expected_statuses – Status codes considered a success. Defaults to None, which accepts every 2xx status.
timeout – Timeout for this request, overriding the client timeout. Defaults to None, which uses the client timeout.
**kwargs – Extra arguments forwarded to requests.request.

Returns:

Instance of model built from the response body.

Return type:

BaseModel

Raises:

APIRequestError – If the request cannot be sent to the server.
APIHttpError – If the status code of the response is not part of expected_statuses.
APIResponseDecodeError – If the body is not valid JSON, or does not match model.

request_model_list(method: str, path: str, model: type[T], params: dict[str, Any] | None = None, headers: dict[str, str] | None = None, expected_statuses: set[int] | None = None, timeout: float | tuple[int, int] | None = None, **kwargs: Any) → list[T]¶

Send a request and validate its JSON body as a list of a model.

Parameters:

method – HTTP method to use.
path – Path of the request.
model – Model to validate every item of the body with.
params – Query parameters for this request. Defaults to None.
headers – Headers for this request. Defaults to None.
expected_statuses – Status codes considered a success. Defaults to None, which accepts every 2xx status.
timeout – Timeout for this request, overriding the client timeout. Defaults to None, which uses the client timeout.
**kwargs – Extra arguments forwarded to requests.request.

Returns:

One instance of model per item of the body.

Return type:

list[BaseModel]

Raises:

APIRequestError – If the request cannot be sent to the server.
APIHttpError – If the status code of the response is not part of expected_statuses.
APIResponseDecodeError – If the body is not a list of objects matching model.

request_operation(method: str, path: str, model: type[~lanraragi_api.api.base.R] = <class 'lanraragi_api.entity.base.OperationResponse'>, params: dict[str, ~typing.Any] | None = None, headers: dict[str, str] | None = None, expected_statuses: set[int] | None = None, raise_on_failure: bool | None = None, timeout: float | tuple[int, int] | None = None, **kwargs: ~typing.Any) → R¶

Send a request whose body reports the result of an operation.

The server reports most operation failures inside the body, through the success field, rather than through the status code. Every status from 200 to 599 is therefore accepted by default, and a failed operation is only turned into an exception when raising is enabled.

Parameters:

method – HTTP method to use.
path – Path of the request.
model – Model to validate the body with. Defaults to OperationResponse.
params – Query parameters for this request. Defaults to None.
headers – Headers for this request. Defaults to None.
expected_statuses – Status codes considered a success. Defaults to None, which accepts every status from 200 to 599.
raise_on_failure – Whether to raise on a failed operation, overriding the raise_on_operation_error setting of the client. Defaults to None, which keeps the setting of the client.
timeout – Timeout for this request, overriding the client timeout. Defaults to None, which uses the client timeout.
**kwargs – Extra arguments forwarded to requests.request.

Returns:

Instance of model built from the response: body.

Return type:

Raises:

APIRequestError – If the request cannot be sent to the server.
APIHttpError – If the status code of the response is not part of expected_statuses.
APIResponseDecodeError – If the body is not valid JSON, or does not match model.
APIOperationError – If the operation failed and raising is enabled.

lanraragi_api.api.category module¶

class lanraragi_api.api.category.CategoryAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to Categories.

Shared request and error behavior is documented on BaseAPICall.

add_archive_to_category(category_id: str, archive_id: str) → OperationResponse¶

Add the specified Archive ID (see Archive API) to the given Category.

Parameters:

category_id – Category ID to add the Archive to.
archive_id – Archive ID to add.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

create_category(name: str, search: str | None = None, pinned: bool | None = None) → OperationResponse¶

Create a new Category.

Parameters:

name – Name of the Category.
search – Matching predicate, if creating a Dynamic Category. Defaults to None.
pinned – Whether the created category will be pinned. Defaults to None.

Returns:

Result of the operation, with the ID of the: created Category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

delete_category(id: str) → OperationResponse¶

Remove a Category.

Parameters:

id – Category ID.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

disable_bookmark_feature() → OperationResponse¶

Disable the bookmark feature by removing the link to any category.

Returns:

Result of the operation, with the ID of the: previously linked category in the extra category_id field, as an empty string if no category was linked.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

get_all_categories() → list[CategoryMetadata]¶

Get all the categories saved on the server.

Returns:

Metadata of every category on the server.

Return type:

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list of objects matching CategoryMetadata.

get_bookmark_link() → dict[Any, Any]¶

Retrieve the ID of the category linked to the bookmark feature.

Returns:

Decoded response, with the linked category ID in: category_id, as an empty string if no category is linked.

Return type:

dict

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not valid JSON.

get_category(id: str) → CategoryMetadata | None¶

Get the details of the specified category ID.

Parameters:

id – ID of the Category desired.

Returns:

Details of the category, or None when the: server answers with 400.

Return type:

CategoryMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

The 400 response of the server is turned into None instead of raising.

remove_archive_from_category(category_id: str, archive_id: str) → OperationResponse¶

Remove an Archive ID from a Category.

Parameters:

category_id – Category ID.
archive_id – Archive ID.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

update_bookmark_link(id: str) → OperationResponse¶

Link the bookmark feature to the specified static category.

This determines which category archives are added to when using the bookmark button.

Parameters:

id – ID of the static category to link with the bookmark feature.

Returns:

Result of the operation, with the ID of the: linked category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 404 (no category with the given ID) are returned in the operation result, with success set to 0, instead of raising.

update_category(id: str, name: str | None = None, search: str | None = None, pinned: bool | None = None) → OperationResponse¶

Modify a Category.

Parameters:

id – ID of the Category to update.
name – New name of the Category. Defaults to None.
search – Predicate. Trying to add a predicate to a category that already contains Archives will give you an error. Defaults to None.
pinned – Add this argument to pin the Category. If you don’t, the category will be unpinned on update. Defaults to None.

Returns:

Result of the operation, with the ID of the: updated Category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Category locked for modification) are returned in the operation result, with success set to 0, instead of raising.

lanraragi_api.api.database module¶

class lanraragi_api.api.database.DatabaseAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Database management APIs.

Shared request and error behavior is documented on BaseAPICall.

clean_database() → OperationResponse¶

Clean the Database.

Entries for files that are no longer on the filesystem are hidden and then removed. They are only unlinked at first, so they do not appear in the UI; a subsequent run of this cleanup deletes the unlinked entries.

Returns:

Result of the cleanup, including the amount of: deleted and unlinked entries reported by the server.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

clear_all_new_flags() → OperationResponse¶

Clear the “New!” flag on all archives.

Returns:

Result of the flag clearing operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

download_backup(jobid: int, format: str | None = None) → Response¶

Download the backup JSON file generated by a completed backup job.

Parameters:

jobid – ID of the completed backup job.
format – Format of the returned backup. json returns the backup as a JSON response, while file returns it as a file. Defaults to None, which the server treats as file.

Returns:

Raw response of the server, holding the backup file or: JSON payload.

Return type:

Response

Raises:

APIHttpError – 400 if the job is not found or not completed yet, or any other non-2xx status code.

drop_database() → OperationResponse¶

Delete the entire database, including user preferences.

This is a rather dangerous endpoint: invoking it might lock you out of the server as a client.

Returns:

Result of the database drop.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

get_backup() → DatabaseBackup¶

Scan the entire database and return a backup in JSON form.

Consider using queue_backup if your database is large, as this basic GET endpoint might time out if it takes too long to generate the backup.

This backup can be reimported manually through the Backup and Restore feature.

Returns:

Archive, category and tankoubon metadata of the: entire database.

Return type:

DatabaseBackup

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match DatabaseBackup.

get_tag_statistics(min_weight: int = 1, hide_excluded_namespaces: bool | None = None) → list[TagStatistic]¶

Get tags from the database, with a value symbolizing their prevalence.

Parameters:

min_weight – Only get tags whose weight is at least the given minimum. Defaults to 1, which gets all tags.
hide_excluded_namespaces – Set to True to exclude tags whose namespace is configured in the server settings. Defaults to None, which returns all tags.

Returns:

One entry per tag, with its namespace, text and: weight.

Return type:

list[TagStatistic]

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or if it is not a list of TagStatistic objects.

queue_backup() → MinionJobResponse¶

Queue a Minion job to generate a backup JSON file.

Use the returned job ID to check progress, then download the file once the job is complete through download_backup.

Returns:

Enqueued job, whose job field holds the ID: of the Minion job.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

queue_restore(file_path: str) → MinionJobResponse¶

Queue a Minion job to restore from a backup JSON file.

Use the returned job ID to check progress.

Parameters:

file_path – Path to the backup JSON file to restore. Backslashes are normalized to forward slashes before the file is looked up.

Returns:

Enqueued job, whose job field holds the ID: of the Minion job.

Return type:

Raises:

FileNotFoundError – If file_path does not point to an existing file.
APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response, returned for an invalid request such as a malformed backup file, is returned in the operation result, with success set to 0, instead of raising.

lanraragi_api.api.minion module¶

class lanraragi_api.api.minion.MinionAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Minion Job Queue APIs.

Shared request and error behavior is documented on BaseAPICall.

get_basic_status(job_id: int | str) → BasicJobStatus¶

Check whether a Minion job succeeded or failed.

Minion jobs are ran for various occasions like thumbnails, cache warmup and handling incoming files.

For some jobs, you can check the notes field for progress information. Look at the Minion Guide for more details: https://docs.mojolicious.org/Minion/Guide#Job-progress

Parameters:

job_id – ID of the job to query status for.

Returns:

Basic status of the job.

Return type:

BasicJobStatus

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match BasicJobStatus.

get_full_status(job_id: int | str) → FullJobStatus¶

Get the status of a Minion job.

This API is there for internal usage mostly, but you can use it to get detailed status for jobs like plugin runs or URL downloads.

Parameters:

job_id – ID of the job.

Returns:

Detailed status of the job.

Return type:

FullJobStatus

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match FullJobStatus.

queue_minion_job(jobname: str, args: str | list[Any], priority: int = 0) → MinionJobResponse¶

Queue a job with the specified type and parameters.

See LANraragi::Utils::Minion for all the available types of jobs and the parameters they require.

There’s no API contract in place for whether a job type exists on a given server version, so using this is not recommended unless you have a good reason to.

Parameters:

jobname – Type of the job to instantiate. Documented values are thumbnail_task, tank_thumbnail_task, page_thumbnails, regen_all_thumbnails, find_duplicates, build_stat_hashes, handle_upload, download_url and run_plugin.
args – Arguments of the job, either a JSON array string or a list of values.
priority – Priority of the Minion job. The higher the number, the more important the job is. Defaults to 0.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

TempfolderCleanupResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

lanraragi_api.api.misc module¶

class lanraragi_api.api.misc.MiscAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Other APIs that don’t fit a dedicated theme.

Shared request and error behavior is documented on BaseAPICall.

clean_temporary_folder() → TempfolderCleanupResponse¶

Clean the server’s temporary folder.

Returns:

Result of the cleanup, with the new size: of the temporary folder.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match TempfolderCleanupResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A cleanup error is reported in the error field of the result while the call still answers with 200.

get_server_information() → ServerInfo¶

Return basic information about the LRR instance this server is running.

Returns:

Basic information about the instance.

Return type:

ServerInfo

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match ServerInfo.

queue_url_to_download(url: str, category_id: str | None = None, use_form_data: bool = False) → DownloadUrlResponse¶

Add a URL to be downloaded by the server and added to its library.

Parameters:

url – URL to download.
category_id – Category ID to add the downloaded URL to. Defaults to None.
use_form_data – Send the arguments as form data instead of query parameters. Defaults to False.

Returns:

Result of the call, with the ID of the queued: job and the URL that was queued.

Return type:

DownloadUrlResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match DownloadUrlResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

The endpoint takes its arguments either as query parameters or in a multipart form body; this switch picks the body variant. A 400 response, returned for a bad request such as a missing URL, is returned in the operation result, with success set to 0, instead of raising.

regenerate_thumbnails(force: bool = False) → MinionJobResponse¶

Queue a Minion job to regenerate missing/all thumbnails on the server.

Parameters:

force – Whether to generate all thumbnails, or only the missing ones. Defaults to False.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

lanraragi_api.api.opds module¶

class lanraragi_api.api.opds.OPDSAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to OPDS catalog generation and serving.

Shared request and error behavior is documented on BaseAPICall.

get_opds_catalog(archive_id: str | None = None, category_id: str | None = None) → str¶

Get the Archive Index as an OPDS 1.2 Catalog with PSE 1.1 compatibility.

Parameters:

archive_id – ID of a single archive. When set, the request is forwarded to get_opds_item and one OPDS entry is returned instead of the catalog. Defaults to None.
category_id – Category ID. If passed, the OPDS catalog will be filtered to only show archives from this category. Defaults to None.

Returns:

OPDS catalog, or a single OPDS entry when archive_id is: set, as an XML string.

Return type:

str

Raises:

APIHttpError – Any non-2xx status code returned by the server.

get_opds_item(id: str) → str¶

Return a specific OPDS item as XML.

This shows only one <entry> for the given ID in the result, instead of all the archives.

Parameters:: id – ID of an archive.
Returns:: OPDS entry as an XML string.
Return type:: str
Raises:: APIHttpError – Any non-2xx status code returned by the server.

get_opds_page(id: str, page: int | None = None) → Response¶

Return a specific image page for OPDS-PSE.

Parameters:

id – ID of an archive.
page – Page number to fetch. Defaults to None, which lets the server pick the page.

Returns:

Raw response holding the image bytes of the page.

Return type:

Response

Raises:

APIHttpError – Any non-2xx status code returned by the server.

lanraragi_api.api.plugin module¶

class lanraragi_api.api.plugin.PluginAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

APIs to list and execute Plugins.

Shared request and error behavior is documented on BaseAPICall.

get_available_plugins(type: str) → list[PluginInfo]¶

List all plugins of the given type.

Parameters:

type – Type of plugins you want to list, one of download, login, metadata or script. Use all to get every type at once.

Returns:

One entry per plugin of the given type.

Return type:

list[PluginInfo]

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body is not a list of objects matching PluginInfo.

use_plugin(plugin: str, id: str | None = None, arg: str | None = None) → PluginUseResponse¶

Use a Plugin and return the result.

If using a metadata plugin, the matching archive will not be modified in the database. See more info on Plugins in the matching section of the Docs.

Parameters:

plugin – Namespace of the plugin to use.
id – ID of the archive to use the plugin on. Only mandatory for metadata plugins. Defaults to None.
arg – One-shot argument to use when executing this plugin. Defaults to None.

Returns:

Result of the plugin run, with the type of the: plugin and any data it returned.

Return type:

PluginUseResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match PluginUseResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A failed plugin run is reported inside the body, through success set to 0, and does not raise unless raising is enabled.

use_plugin_async(plugin: str, id: str | None = None, arg: str | None = None, priority: int = 0) → MinionJobResponse¶

Use a Plugin and return the Minion job ID matching the run.

This endpoint is useful if you want to run longer-lived plugins which might timeout if ran with the standard endpoint.

Parameters:

plugin – Namespace of the plugin to use.
id – ID of the archive to use the plugin on. Only mandatory for metadata plugins. Defaults to None.
arg – One-shot argument to use when executing this plugin. Defaults to None.
priority – Priority of the Minion job. The higher the number, the more important the job is. Defaults to 0.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

lanraragi_api.api.search module¶

class lanraragi_api.api.search.SearchAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Perform searches.

Shared request and error behavior is documented on BaseAPICall.

discard_search_cache() → OperationResponse¶

Discard the cache containing previous user searches.

Returns:

Result of the cache discard operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

get_random_archives(category: str | None = None, filter: str | None = None, count: int = 5, new_only: bool = False, untagged_only: bool = False, hide_completed: bool | None = None, groupby_tanks: bool = True) → list[ArchiveMetadata]¶

Get randomly selected Archives from the given filter and/or category.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the same rules as the queries in /api/search. Defaults to None.
count – How many archives you want to pull randomly. If the search doesn’t return enough data to match your count, you will get the full search shuffled randomly. Defaults to 5.
new_only – Limit search to new archives only. Defaults to False, which is not sent to the server.
untagged_only – Limit search to untagged archives only. Defaults to False, which is not sent to the server.
hide_completed – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to True; a falsy value is not sent to the server.

Returns:

Randomly selected archives, one object per: archive.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, if it has no data list, or if an item of that list does not match ArchiveMetadata.

search(category: str | None = None, filter: str | None = None, start: int | None = None, sort_by: str = 'title', order: str = 'asc', new_only: bool = False, untagged_only: bool = False, hide_completed: bool | None = None, groupby_tanks: bool = True) → SearchResult¶

Search for Archives using the legacy parameter names.

This compatibility wrapper forwards every argument to search_archives, renaming sort_by to sortby, new_only to newonly, untagged_only to untaggedonly and hide_completed to hidecompleted. groupby_tanks keeps its name.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the rules of search_archives. Defaults to None.
start – From which archive in the total result count this enumeration should start, with “-1” for the full, unpaged data. Defaults to None.
sort_by – Namespace by which you want to sort the results, sent as sortby. Defaults to “title”.
order – Order of the sort, either asc or desc, sent as order. Defaults to “asc”.
new_only – Limit search to new archives only, sent as newonly. Defaults to False.
untagged_only – Limit search to untagged archives only, sent as untaggedonly. Defaults to False.
hide_completed – Hide archives where reading progress has reached the end, sent as hidecompleted. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. Defaults to True.

Returns:

Same result as search_archives.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchResult.

Note

Falsy values are not forwarded to the server: new_only, untagged_only, hide_completed and groupby_tanks become None, so the server-side default applies instead.

Search for Archives like /api/search, but return only IDs.

The ordered list of matching Archive IDs is returned without the accompanying metadata.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the same rules as the queries in /api/search. Defaults to None.
start – From which archive in the total result count this enumeration should start. The total number of archives displayed depends on the server-side page size preference. From 0.8.2 onwards, “-1” gives the full, unpaged list of IDs. Defaults to None.
sortby – Namespace by which you want to sort the results. Use title to sort by title, or lastread to sort by last read time, which requires Server-side Progress Tracking to be enabled. Defaults to None, which sorts by title; sorting by lastread removes IDs that have never been read from the search.
order – Order of the sort, either asc or desc. Defaults to None, which the server treats as asc.
newonly – Limit search to new archives only. Defaults to None.
untaggedonly – Limit search to untagged archives only. Defaults to None.
hidecompleted – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to None, which the server treats as true.

Returns:

One archive ID per matching archive in data.

Return type:

SearchIdsResult

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchIdsResult.

Note

The server answers with 204 when the search engine is not initialized yet. That response carries no body and therefore raises APIResponseDecodeError; wait a few seconds and retry the search in that case.

Search for Archives.

You can use the IDs of this JSON with the other endpoints.

The filter parameter accepts the following special characters:

Quotation marks ("..."): exact string search. Allows a search term to include spaces, as everything inside a pair of quotation marks is treated as a singular term. Wildcard characters are still interpreted as wildcards.
Question mark (?), underscore (_): wildcard matching any single character.
Asterisk (*), percentage sign (%): wildcard matching any sequence of characters, including none.
Subtraction sign (-): exclusion. When placed before a term, it prevents search results from including that term.
Dollar sign ($): add at the end of a tag to perform an exact tag search rather than displaying all elements that start with the term. Only matches tags regardless of the search parameters, and can be used as an exclusion to ignore misc tags in the search query.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, using the special characters listed above. Defaults to None.
start – From which archive in the total result count this enumeration should start. The total number of archives displayed depends on the server-side page size preference. From 0.8.2 onwards, “-1” gives the full, unpaged data. Defaults to None.
sortby – Namespace by which you want to sort the results. Use title to sort by title, or lastread to sort by last read time, which requires Server-side Progress Tracking to be enabled. Defaults to None, which sorts by title; sorting by lastread removes IDs that have never been read from the search.
order – Order of the sort, either asc or desc. Defaults to None, which the server treats as asc.
newonly – Limit search to new archives only. Defaults to None.
untaggedonly – Limit search to untagged archives only. Defaults to None.
hidecompleted – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to None, which the server treats as true.

Returns:

One ArchiveMetadata object per matching archive: in data.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchResult.

Note

The server answers with 204 when the search engine is not initialized yet. That response carries no body and therefore raises APIResponseDecodeError; wait a few seconds and retry the search in that case.

lanraragi_api.api.shinobu module¶

class lanraragi_api.api.shinobu.ShinobuAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Shinobu Filewatcher APIs.

Shared request and error behavior is documented on BaseAPICall.

get_shinobu_status() → dict[str, Any]¶

Get the current status of the filewatcher.

Returns:

Decoded status payload, holding the is_alive flag and the: pid of the watcher process.

Return type:

dict

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body is not valid JSON.

rescan_shinobu() → OperationResponse¶

Rescan the filemap and restart Shinobu.

This deletes the internal map of scanned files on your system (the “filemap”) and restarts Shinobu, effectively prompting a full rescan of your FS.

Returns:

Result of the operation, with the new process: PID as an extra field.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

restart_shinobu() → OperationResponse¶

Restart the Shinobu filewatcher.

This also starts the filewatcher again when it was stopped.

Returns:

Result of the operation, with the new process: PID as an extra field.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

stop_shinobu() → OperationResponse¶

Stop the filewatcher.

Use /api/shinobu/restart to start it again.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

lanraragi_api.api.stamp module¶

class lanraragi_api.api.stamp.StampAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Stamps.

Shared request and error behavior is documented on BaseAPICall.

add_stamp(archive_id: str, index: int, content: str | None = None, position: str | None = None) → AddStampResponse¶

Add a new Stamp to the page at the given coordinates.

Parameters:

archive_id – ID of the archive.
index – Page of the archive.
content – Text of the stamp. Defaults to None.
position – Position of the stamp in the page. Defaults to None.

Returns:

Result of the operation, with the stamp_id of: the created stamp.

Return type:

AddStampResponse

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match AddStampResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

delete_stamp(id: str) → OperationResponse¶

Remove a stamp from an Archive.

Parameters:

id – ID of the stamp.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Stamp locked for modification) are returned in the operation result, with success set to 0, instead of raising.

get_stamp(id: str) → StampsData¶

Get a stamp from an Archive.

Parameters:

id – ID of the stamp.

Returns:

Stamp data.

Return type:

StampsData

Raises:

APIHttpError – 400 if the server rejected the request; 423 if the Stamp is currently locked for modification.
APIResponseDecodeError – If the response does not match StampsData.

get_stamped_pages(archive_id: str) → StampsResponse¶

Get pages that contain at least one stamp in the archive.

Parameters:

archive_id – ID of the archive.

Returns:

Page indices of the archive that contain a stamp.

Return type:

StampsResponse

Raises:

APIHttpError – 400 if the server rejected the request.
APIResponseDecodeError – If the response does not match StampsResponse.

get_stamps_by_page(archive_id: str, index: int) → list[StampsData]¶

Get the stamps linked to the page.

Parameters:

archive_id – ID of the archive.
index – Page of the archive.

Returns:

Stamps of the page.

Return type:

list[StampsData]

Raises:

APIHttpError – 400 if the server rejected the request.
APIResponseDecodeError – If the response has no result list, or if an item does not match StampsData.

update_stamp(id: str, content: str | None = None, position: str | None = None) → OperationResponse¶

Update a stamp from an Archive.

Parameters:

id – ID of the stamp.
content – Text of the stamp. Defaults to None.
position – Position of the stamp in the page. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Stamp locked for modification) are returned in the operation result, with success set to 0, instead of raising.

lanraragi_api.api.tankoubon module¶

class lanraragi_api.api.tankoubon.TankoubonAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to Tankoubons.

Shared request and error behavior is documented on BaseAPICall.

add_archive_to_tankoubon(tankoubon_id: str, archive_id: str) → OperationResponse¶

Append an archive at the final position of a Tankoubon.

Parameters:

tankoubon_id – ID of the Tankoubon to update.
archive_id – ID of the Archive to append.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

create_tankoubon(name: str, tankid: str | None = None) → OperationResponse¶

Create a new Tankoubon or update the name of an existing one.

Parameters:

name – Name of the Tankoubon.
tankid – ID of an existing Tankoubon, if you want to change its name. Defaults to None, which creates a new Tankoubon.

Returns:

Result of the operation; tankoubon_id holds: the ID of the created or modified Tankoubon.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

delete_tankoubon(id: str) → OperationResponse¶

Remove a Tankoubon from the server.

This doesn’t delete the underlying Archives.

Parameters:

id – ID of the Tankoubon to delete.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

get_all_tankoubons(page: int | None = None) → list[TankoubonMetadata]¶

Return only the tankoubon list of the paginated list endpoint.

This is a backward-compatible wrapper around get_tankoubon_list.

Parameters:: page – Page of the list of Tankoubons. Defaults to None.
Returns:: Tankoubons of the requested page.
Return type:: list[TankoubonMetadata]

get_tankoubon(id: str) → TankoubonMetadata¶

Get the details of the specified tankoubon ID.

This is a backward-compatible wrapper around get_tankoubon_detail.

Parameters:: id – ID of the Tankoubon desired.
Returns:: Metadata of the tankoubon.
Return type:: TankoubonMetadata

get_tankoubon_detail(id: str) → TankoubonMetadata¶

Get the details of the specified tankoubon ID.

Parameters:

id – ID of the Tankoubon desired.

Returns:

Metadata of the tankoubon.

Return type:

TankoubonMetadata

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.
APIResponseDecodeError – If the response does not match TankoubonMetadata.

get_tankoubon_full(id: str, page: int = -1) → TankoubonDetailResponse¶

Get the details of a tankoubon with paginated archive metadata.

The amount of archives per page depends on the server archives_per_page setting.

Parameters:

id – ID of the Tankoubon desired.
page – Page of the Archives list. Defaults to -1, which returns all archives.

Returns:

Tankoubon metadata with full_data: filled in.

Return type:

TankoubonDetailResponse

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.
APIResponseDecodeError – If the response has no result payload, or if it does not match TankoubonMetadata.

get_tankoubon_list(page: int | None = None) → TankoubonListResponse¶

Get list of Tankoubons paginated.

The amount of tanks per page depends on the server archives_per_page setting.

Parameters:

page – Page of the list of Tankoubons. Defaults to None.

Returns:

Tankoubons of the requested page.

Return type:

TankoubonListResponse

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response has no result list, or if an item does not match TankoubonMetadata.

get_tankoubon_thumbnail(id: str, no_fallback: bool | None = None) → Response¶

Get the cover thumbnail for a given Tankoubon.

By default, the thumbnail is sourced from the first page of the first archive. This endpoint returns a placeholder image if the thumbnail does not exist yet. If you want to queue generation of the thumbnail in the background, you can use the no_fallback query parameter.

Parameters:

id – ID of the Tankoubon desired.
no_fallback – Disables the placeholder image, queues the thumbnail for extraction and returns a JSON with code 202. This parameter does nothing if the image already exists. Defaults to None.

Returns:

Response of the server, either the thumbnail bytes with: code 200 or the job JSON with code 202.

Return type:

Response

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.

Note

When the thumbnail already exists, the image is returned with code 200 no matter what. Otherwise, no_fallback queues the extraction and the 202 body carries a Minion job; use /api/minion/:jobid to track when the thumbnail is ready.

remove_archive_from_tankoubon(tankoubon_id: str, archive_id: str) → OperationResponse¶

Remove an archive from a Tankoubon.

Parameters:

tankoubon_id – ID of the Tankoubon to update.
archive_id – ID of the archive to remove.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

update_tank_progress(id: str, page: int) → OperationResponse¶

Tell the server which page of this Tankoubon you’re reading.

The server updates its internal reading progression accordingly. The page number is global across all Archives in the tank (if a tank has two Archives with 20 and 25 pages, page 26 will be page 6 in Archive #2).

Parameters:

id – ID of the Tankoubon to update.
page – Global 1-indexed page number to update the reading progress to. Must be a positive integer.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

If the server is configured to use clientside progress tracking, this API call returns an error. Make sure to check through /api/info whether the server tracks reading progression or not before calling this endpoint.

Modify the full metadata (name, summary, additional tags) or the contents of a Tankoubon.

If you only need to change the name of a Tank, consider just using PUT /api/tankoubons instead.

Parameters:

id – ID of the Tankoubon to update.
archives – Ordered list of archive IDs. Defaults to None.
name – Name of the Tankoubon. Defaults to None.
summary – Summary of the Tankoubon. Defaults to None.
tags – Additional tags for the Tankoubon, in LRR comma-separated format. This replaces whatever additional tags the Tank already has, unless append is True. Defaults to None.
append – If True, tags are appended to the Tank’s existing own tags instead of replacing them. Defaults to None, which leaves the server default of False.
metadata – Metadata payload, merged with the explicit arguments. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

If there is no need to update something in one of the metadata keys, do not send the key, as this can otherwise result in unwanted results.

update_tankoubon_thumbnail(id: str, page: int) → OperationResponse¶

Set the cover thumbnail of a Tankoubon from a global page number.

The global page falls within all archives of the tank, in order, and is translated to the correct archive and local page automatically.

Parameters:

id – ID of the Tankoubon desired.
page – Global 1-indexed page number across all archives in the tankoubon. Page 1 is the first page of the first archive, and so on.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

On success the server also returns a new_thumbnail field with the path of the new thumbnail file.

Module contents¶

class lanraragi_api.api.ArchiveAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Everything dealing with Archives.

Shared request and error behavior is documented on BaseAPICall.

add_archive_toc(id: str, page: int, title: str) → OperationResponse¶

Add an entry to the Table of Contents of a given Archive.

The ToC is stored as a JSON-encoded key-value array mapping a page to a title for the chapter/section starting at that page.

Parameters:

id – ID of the Archive to process.
page – Page number where the chapter/section starts.
title – Title of the chapter/section.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

clear_archive_new_flag(id: str) → OperationResponse¶

Clear the “New!” flag on an archive.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

delete_archive(id: str) → OperationResponse¶

Delete both the archive metadata and the file stored on the server.

Please ask your user for confirmation before invoking this endpoint.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

delete_archive_toc(id: str, page: int) → OperationResponse¶

Delete an entry from the Table of Contents of a given Archive.

Parameters:

id – ID of the Archive to process.
page – Page number of the chapter/section to delete.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

download_archive(id: str) → Response¶

Download an Archive from the server.

Parameters:: id – ID of the Archive to download.
Returns:: Response of the server carrying the archive file.
Return type:: Response
Raises:: APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

extract_archive(id: str, force: bool = False) → dict[Any, Any]¶

Get a list of URLs pointing to the images contained in an archive.

If necessary, this endpoint also launches a background Minion job to extract the archive so it is ready for reading.

Parameters:

id – ID of the Archive to process.
force – Force a full background re-extraction of the Archive. Existing cached files might still be used in subsequent /api/archives/:id/page calls until the Archive is fully re-extracted. Defaults to False.

Returns:

Decoded response, with the page URLs in pages and the ID: of the background extract job in job.

Return type:

dict

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

get_all_archives() → list[ArchiveMetadata]¶

Return a list of all Archives in the database.

This doesn’t include Tankoubons by design. You can use the IDs of this JSON with the other endpoints.

Returns:

Metadata of every Archive in the database.

Return type:

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list of objects matching ArchiveMetadata.

get_archive(id: str) → ArchiveMetadata | None¶

Get Metadata (title, tags) for a given Archive.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of the archive, or None when the: server answers with 400.

Return type:

ArchiveMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

This endpoint is deprecated; use get_archive_metadata instead. The 400 response, sent when no archive ID was given, is turned into None instead of raising.

get_archive_categories(id: str) → list[CategoryMetadata]¶

Get all the Categories which currently refer to this Archive ID.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of every Category referring to: this Archive.

Return type:

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.
APIResponseDecodeError – If the response has no categories list, or if an item does not match CategoryMetadata.

get_archive_metadata(id: str) → ArchiveMetadata | None¶

Get Metadata (title, tags) for a given Archive.

Parameters:

id – ID of the Archive to process.

Returns:

Metadata of the archive, or None when the: server answers with 400.

Return type:

ArchiveMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

The 400 response, sent when no archive ID was given, is turned into None instead of raising.

get_archive_page(id: str, path: str) → Response¶

Get an archive page.

This call is mainly used alongside /api/archives/files.

Parameters:

id – ID of the Archive to download.
path – Path to the image in the extracted archive files.

Returns:

Response of the server carrying the image.

Return type:

Response

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

get_archive_tankoubons(id: str) → list[str]¶

Get all the Tankoubons which currently refer to this Archive ID.

Tankoubon (単行本) is the Japanese term for a bound volume.

Parameters:

id – ID of the Archive to process.

Returns:

IDs of the Tankoubons referring to this Archive.

Return type:

list[str]

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.
APIResponseDecodeError – If the response has no tankoubons list.

get_archive_thumbnail(id: str, page: int = 1, no_fallback: bool | None = None) → Response¶

Get a Thumbnail image for a given Archive.

This endpoint will return a placeholder image if it doesn’t already exist. If you want to queue generation of the thumbnail in the background, use the no_fallback parameter: you will get a background job ID instead of the placeholder.

Parameters:

id – ID of the Archive to process.
page – Specify which page you want to get a thumbnail for. Defaults to 1, the cover.
no_fallback – Disables the placeholder image, queues the thumbnail for extraction and returns a JSON with code 202. This parameter does nothing if the image already exists. (You will get the image with code 200 no matter what) Defaults to None.

Returns:

Response of the server, either the thumbnail bytes with: code 200 or the job JSON with code 202.

Return type:

Response

Raises:

APIHttpError – 400 if no archive ID was given, or any other non-2xx status code.

Note

A queued extraction returns a Minion job ID; use /api/minion/:jobid to track when the thumbnail is ready.

get_untagged_archives() → list[str]¶

Get Archives that don’t have any tags recorded.

This follows the same rules as the Batch Tagging filter and will include Archives that have parody:, date_added:, series: or artist: tags.

Returns:

IDs of the Archives that have no tags recorded.

Return type:

list[str]

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list.

queue_extraction_of_page_thumbnails(id: str, force: bool = False) → MinionJobResponse¶

Create thumbnails for every page of a given Archive.

This endpoint will queue generation of the thumbnails in the background.

If all thumbnails are detected as already existing, the call will return HTTP code 200.

This endpoint can be called multiple times – If a thumbnailing job is already in progress for the given ID, it’ll just give you the ID for that ongoing job.

Parameters:

id – ID of the Archive to process.
force – Whether to force regeneration of all thumbnails even if they already exist. Defaults to False.

Returns:

Result of the operation, with the ID of the: queued or ongoing Minion job in job.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

The job field is None when all thumbnails already exist and the server answers with code 200 instead of queueing a job. A 400 response is returned in the operation result, with success set to 0, instead of raising.

set_archive_new_flag(id: str) → OperationResponse¶

Set or restore the “New!” flag on an archive.

Parameters:

id – ID of the Archive to process.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

update_archive_metadata(id: str, archive: ArchiveMetadata | None = None, *, title: str | None = None, tags: str | None = None, summary: str | None = None) → OperationResponse¶

Update tags, title and summary for the given Archive.

Data supplied to the server through this method will overwrite the previous data.

Parameters:

id – ID of the Archive to process.
archive – Optional backward-compatible metadata object, used to fill title, tags or summary when they are omitted. Defaults to None.
title – Archive title to set. If omitted and archive is provided, archive.title is used. Defaults to None.
tags – Archive tags string to set. If omitted and archive is provided, archive.tags is used. Defaults to None.
summary – Archive summary to set. If omitted and archive is provided, archive.summary is used. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising.

update_reading_progression(id: str, page: int) → OperationResponse¶

Tell the server which page of this Archive you are currently reading.

This endpoint will also update the date this Archive was last read, using the current server timestamp.

You should call this endpoint only when you’re sure the user is currently reading the page you present. Don’t use it when preloading images off the server.

Whether to make reading progression regressible or not is up to the client. (The web client will reduce progression if the user starts reading previous pages)

Consider however removing the “New!” flag from an archive when you start updating its progress - The web client won’t display any reading progression if the new flag is still set.

Parameters:

id – ID of the Archive to process.
page – Current page to update the reading progress to. Must be a positive integer, and inferior or equal to the total page number of the archive.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response), 401 (authentication required) or 423 (locked resource) are returned in the operation result, with success set to 0, instead of raising. If the server is configured to use clientside progress tracking, this API call returns an error. Check with /api/info whether the server tracks reading progression before calling this endpoint.

update_thumbnail(id: str, page: int = 1) → OperationResponse¶

Update the cover thumbnail for the given Archive.

You can specify a page number to use as the thumbnail, or you can use the default thumbnail.

Parameters:

id – ID of the Archive to process.
page – Page you want to make the thumbnail out of. Defaults to 1.

Returns:

Result of the operation, with the path of the: new thumbnail in the extra new_thumbnail field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

Upload an Archive to the server.

If a SHA1 checksum of the Archive is included, the server will perform an optional in-transit, file integrity validation, and reject the upload if the server-side checksum does not match.

Parameters:

archive – str type for path of the archive file to upload, or a tuple made up of a filename and the file content in bytes.
title – Title of the Archive. Defaults to None.
tags – Set of tags you want to insert in the database alongside the archive. Defaults to None.
summary – Summary of the Archive. Defaults to None.
category_id – Category ID you’d want the archive to be added to. Defaults to None.
file_checksum – SHA1 checksum of the archive for in-transit validation. Defaults to None.

Returns:

Result of the operation, with the ID of the: uploaded Archive in the extra id field.

Return type:

Raises:

FileNotFoundError – If archive points to an no-existing file.
APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Uploading an archive that already exists is reported with a 409 response, whose body carries the reason in the error field. Other failure responses, such as 415 (unsupported file), 417 (checksum mismatch) or 422 (unprocessable entity), are returned in the operation result, with success set to 0, instead of raising.

class lanraragi_api.api.CategoryAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to Categories.

Shared request and error behavior is documented on BaseAPICall.

add_archive_to_category(category_id: str, archive_id: str) → OperationResponse¶

Add the specified Archive ID (see Archive API) to the given Category.

Parameters:

category_id – Category ID to add the Archive to.
archive_id – Archive ID to add.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

create_category(name: str, search: str | None = None, pinned: bool | None = None) → OperationResponse¶

Create a new Category.

Parameters:

name – Name of the Category.
search – Matching predicate, if creating a Dynamic Category. Defaults to None.
pinned – Whether the created category will be pinned. Defaults to None.

Returns:

Result of the operation, with the ID of the: created Category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

delete_category(id: str) → OperationResponse¶

Remove a Category.

Parameters:

id – Category ID.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

disable_bookmark_feature() → OperationResponse¶

Disable the bookmark feature by removing the link to any category.

Returns:

Result of the operation, with the ID of the: previously linked category in the extra category_id field, as an empty string if no category was linked.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

get_all_categories() → list[CategoryMetadata]¶

Get all the categories saved on the server.

Returns:

Metadata of every category on the server.

Return type:

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not a list of objects matching CategoryMetadata.

get_bookmark_link() → dict[Any, Any]¶

Retrieve the ID of the category linked to the bookmark feature.

Returns:

Decoded response, with the linked category ID in: category_id, as an empty string if no category is linked.

Return type:

dict

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response body is not valid JSON.

get_category(id: str) → CategoryMetadata | None¶

Get the details of the specified category ID.

Parameters:

id – ID of the Category desired.

Returns:

Details of the category, or None when the: server answers with 400.

Return type:

CategoryMetadata | None

Raises:

APIHttpError – Any status code other than 200 and 400.

Note

The 400 response of the server is turned into None instead of raising.

remove_archive_from_category(category_id: str, archive_id: str) → OperationResponse¶

Remove an Archive ID from a Category.

Parameters:

category_id – Category ID.
archive_id – Archive ID.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 423 response, sent when the Category is locked for modification, is returned in the operation result, with success set to 0, instead of raising.

update_bookmark_link(id: str) → OperationResponse¶

Link the bookmark feature to the specified static category.

This determines which category archives are added to when using the bookmark button.

Parameters:

id – ID of the static category to link with the bookmark feature.

Returns:

Result of the operation, with the ID of the: linked category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 404 (no category with the given ID) are returned in the operation result, with success set to 0, instead of raising.

update_category(id: str, name: str | None = None, search: str | None = None, pinned: bool | None = None) → OperationResponse¶

Modify a Category.

Parameters:

id – ID of the Category to update.
name – New name of the Category. Defaults to None.
search – Predicate. Trying to add a predicate to a category that already contains Archives will give you an error. Defaults to None.
pinned – Add this argument to pin the Category. If you don’t, the category will be unpinned on update. Defaults to None.

Returns:

Result of the operation, with the ID of the: updated Category in the extra category_id field.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Category locked for modification) are returned in the operation result, with success set to 0, instead of raising.

class lanraragi_api.api.DatabaseAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Database management APIs.

Shared request and error behavior is documented on BaseAPICall.

clean_database() → OperationResponse¶

Clean the Database.

Entries for files that are no longer on the filesystem are hidden and then removed. They are only unlinked at first, so they do not appear in the UI; a subsequent run of this cleanup deletes the unlinked entries.

Returns:

Result of the cleanup, including the amount of: deleted and unlinked entries reported by the server.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

clear_all_new_flags() → OperationResponse¶

Clear the “New!” flag on all archives.

Returns:

Result of the flag clearing operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

download_backup(jobid: int, format: str | None = None) → Response¶

Download the backup JSON file generated by a completed backup job.

Parameters:

jobid – ID of the completed backup job.
format – Format of the returned backup. json returns the backup as a JSON response, while file returns it as a file. Defaults to None, which the server treats as file.

Returns:

Raw response of the server, holding the backup file or: JSON payload.

Return type:

Response

Raises:

APIHttpError – 400 if the job is not found or not completed yet, or any other non-2xx status code.

drop_database() → OperationResponse¶

Delete the entire database, including user preferences.

This is a rather dangerous endpoint: invoking it might lock you out of the server as a client.

Returns:

Result of the database drop.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

get_backup() → DatabaseBackup¶

Scan the entire database and return a backup in JSON form.

Consider using queue_backup if your database is large, as this basic GET endpoint might time out if it takes too long to generate the backup.

This backup can be reimported manually through the Backup and Restore feature.

Returns:

Archive, category and tankoubon metadata of the: entire database.

Return type:

DatabaseBackup

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match DatabaseBackup.

get_tag_statistics(min_weight: int = 1, hide_excluded_namespaces: bool | None = None) → list[TagStatistic]¶

Get tags from the database, with a value symbolizing their prevalence.

Parameters:

min_weight – Only get tags whose weight is at least the given minimum. Defaults to 1, which gets all tags.
hide_excluded_namespaces – Set to True to exclude tags whose namespace is configured in the server settings. Defaults to None, which returns all tags.

Returns:

One entry per tag, with its namespace, text and: weight.

Return type:

list[TagStatistic]

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or if it is not a list of TagStatistic objects.

queue_backup() → MinionJobResponse¶

Queue a Minion job to generate a backup JSON file.

Use the returned job ID to check progress, then download the file once the job is complete through download_backup.

Returns:

Enqueued job, whose job field holds the ID: of the Minion job.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

queue_restore(file_path: str) → MinionJobResponse¶

Queue a Minion job to restore from a backup JSON file.

Use the returned job ID to check progress.

Parameters:

file_path – Path to the backup JSON file to restore. Backslashes are normalized to forward slashes before the file is looked up.

Returns:

Enqueued job, whose job field holds the ID: of the Minion job.

Return type:

Raises:

FileNotFoundError – If file_path does not point to an existing file.
APIResponseDecodeError – If the response body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response, returned for an invalid request such as a malformed backup file, is returned in the operation result, with success set to 0, instead of raising.

class lanraragi_api.api.MinionAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Minion Job Queue APIs.

Shared request and error behavior is documented on BaseAPICall.

get_basic_status(job_id: int | str) → BasicJobStatus¶

Check whether a Minion job succeeded or failed.

Minion jobs are ran for various occasions like thumbnails, cache warmup and handling incoming files.

For some jobs, you can check the notes field for progress information. Look at the Minion Guide for more details: https://docs.mojolicious.org/Minion/Guide#Job-progress

Parameters:

job_id – ID of the job to query status for.

Returns:

Basic status of the job.

Return type:

BasicJobStatus

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match BasicJobStatus.

get_full_status(job_id: int | str) → FullJobStatus¶

Get the status of a Minion job.

This API is there for internal usage mostly, but you can use it to get detailed status for jobs like plugin runs or URL downloads.

Parameters:

job_id – ID of the job.

Returns:

Detailed status of the job.

Return type:

FullJobStatus

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match FullJobStatus.

queue_minion_job(jobname: str, args: str | list[Any], priority: int = 0) → MinionJobResponse¶

Queue a job with the specified type and parameters.

See LANraragi::Utils::Minion for all the available types of jobs and the parameters they require.

There’s no API contract in place for whether a job type exists on a given server version, so using this is not recommended unless you have a good reason to.

Parameters:

jobname – Type of the job to instantiate. Documented values are thumbnail_task, tank_thumbnail_task, page_thumbnails, regen_all_thumbnails, find_duplicates, build_stat_hashes, handle_upload, download_url and run_plugin.
args – Arguments of the job, either a JSON array string or a list of values.
priority – Priority of the Minion job. The higher the number, the more important the job is. Defaults to 0.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

TempfolderCleanupResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

class lanraragi_api.api.MiscAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Other APIs that don’t fit a dedicated theme.

Shared request and error behavior is documented on BaseAPICall.

clean_temporary_folder() → TempfolderCleanupResponse¶

Clean the server’s temporary folder.

Returns:

Result of the cleanup, with the new size: of the temporary folder.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match TempfolderCleanupResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A cleanup error is reported in the error field of the result while the call still answers with 200.

get_server_information() → ServerInfo¶

Return basic information about the LRR instance this server is running.

Returns:

Basic information about the instance.

Return type:

ServerInfo

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body does not match ServerInfo.

queue_url_to_download(url: str, category_id: str | None = None, use_form_data: bool = False) → DownloadUrlResponse¶

Add a URL to be downloaded by the server and added to its library.

Parameters:

url – URL to download.
category_id – Category ID to add the downloaded URL to. Defaults to None.
use_form_data – Send the arguments as form data instead of query parameters. Defaults to False.

Returns:

Result of the call, with the ID of the queued: job and the URL that was queued.

Return type:

DownloadUrlResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match DownloadUrlResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

The endpoint takes its arguments either as query parameters or in a multipart form body; this switch picks the body variant. A 400 response, returned for a bad request such as a missing URL, is returned in the operation result, with success set to 0, instead of raising.

regenerate_thumbnails(force: bool = False) → MinionJobResponse¶

Queue a Minion job to regenerate missing/all thumbnails on the server.

Parameters:

force – Whether to generate all thumbnails, or only the missing ones. Defaults to False.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

class lanraragi_api.api.OPDSAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to OPDS catalog generation and serving.

Shared request and error behavior is documented on BaseAPICall.

get_opds_catalog(archive_id: str | None = None, category_id: str | None = None) → str¶

Get the Archive Index as an OPDS 1.2 Catalog with PSE 1.1 compatibility.

Parameters:

archive_id – ID of a single archive. When set, the request is forwarded to get_opds_item and one OPDS entry is returned instead of the catalog. Defaults to None.
category_id – Category ID. If passed, the OPDS catalog will be filtered to only show archives from this category. Defaults to None.

Returns:

OPDS catalog, or a single OPDS entry when archive_id is: set, as an XML string.

Return type:

str

Raises:

APIHttpError – Any non-2xx status code returned by the server.

get_opds_item(id: str) → str¶

Return a specific OPDS item as XML.

This shows only one <entry> for the given ID in the result, instead of all the archives.

Parameters:: id – ID of an archive.
Returns:: OPDS entry as an XML string.
Return type:: str
Raises:: APIHttpError – Any non-2xx status code returned by the server.

get_opds_page(id: str, page: int | None = None) → Response¶

Return a specific image page for OPDS-PSE.

Parameters:

id – ID of an archive.
page – Page number to fetch. Defaults to None, which lets the server pick the page.

Returns:

Raw response holding the image bytes of the page.

Return type:

Response

Raises:

APIHttpError – Any non-2xx status code returned by the server.

class lanraragi_api.api.PluginAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

APIs to list and execute Plugins.

Shared request and error behavior is documented on BaseAPICall.

get_available_plugins(type: str) → list[PluginInfo]¶

List all plugins of the given type.

Parameters:

type – Type of plugins you want to list, one of download, login, metadata or script. Use all to get every type at once.

Returns:

One entry per plugin of the given type.

Return type:

list[PluginInfo]

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body is not a list of objects matching PluginInfo.

use_plugin(plugin: str, id: str | None = None, arg: str | None = None) → PluginUseResponse¶

Use a Plugin and return the result.

If using a metadata plugin, the matching archive will not be modified in the database. See more info on Plugins in the matching section of the Docs.

Parameters:

plugin – Namespace of the plugin to use.
id – ID of the archive to use the plugin on. Only mandatory for metadata plugins. Defaults to None.
arg – One-shot argument to use when executing this plugin. Defaults to None.

Returns:

Result of the plugin run, with the type of the: plugin and any data it returned.

Return type:

PluginUseResponse

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match PluginUseResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A failed plugin run is reported inside the body, through success set to 0, and does not raise unless raising is enabled.

use_plugin_async(plugin: str, id: str | None = None, arg: str | None = None, priority: int = 0) → MinionJobResponse¶

Use a Plugin and return the Minion job ID matching the run.

This endpoint is useful if you want to run longer-lived plugins which might timeout if ran with the standard endpoint.

Parameters:

plugin – Namespace of the plugin to use.
id – ID of the archive to use the plugin on. Only mandatory for metadata plugins. Defaults to None.
arg – One-shot argument to use when executing this plugin. Defaults to None.
priority – Priority of the Minion job. The higher the number, the more important the job is. Defaults to 0.

Returns:

Result of the call, with the ID of the queued: job.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match MinionJobResponse.
APIOperationError – If the operation failed and raising is enabled.

class lanraragi_api.api.SearchAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Perform searches.

Shared request and error behavior is documented on BaseAPICall.

discard_search_cache() → OperationResponse¶

Discard the cache containing previous user searches.

Returns:

Result of the cache discard operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

get_random_archives(category: str | None = None, filter: str | None = None, count: int = 5, new_only: bool = False, untagged_only: bool = False, hide_completed: bool | None = None, groupby_tanks: bool = True) → list[ArchiveMetadata]¶

Get randomly selected Archives from the given filter and/or category.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the same rules as the queries in /api/search. Defaults to None.
count – How many archives you want to pull randomly. If the search doesn’t return enough data to match your count, you will get the full search shuffled randomly. Defaults to 5.
new_only – Limit search to new archives only. Defaults to False, which is not sent to the server.
untagged_only – Limit search to untagged archives only. Defaults to False, which is not sent to the server.
hide_completed – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to True; a falsy value is not sent to the server.

Returns:

Randomly selected archives, one object per: archive.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, if it has no data list, or if an item of that list does not match ArchiveMetadata.

search(category: str | None = None, filter: str | None = None, start: int | None = None, sort_by: str = 'title', order: str = 'asc', new_only: bool = False, untagged_only: bool = False, hide_completed: bool | None = None, groupby_tanks: bool = True) → SearchResult¶

Search for Archives using the legacy parameter names.

This compatibility wrapper forwards every argument to search_archives, renaming sort_by to sortby, new_only to newonly, untagged_only to untaggedonly and hide_completed to hidecompleted. groupby_tanks keeps its name.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the rules of search_archives. Defaults to None.
start – From which archive in the total result count this enumeration should start, with “-1” for the full, unpaged data. Defaults to None.
sort_by – Namespace by which you want to sort the results, sent as sortby. Defaults to “title”.
order – Order of the sort, either asc or desc, sent as order. Defaults to “asc”.
new_only – Limit search to new archives only, sent as newonly. Defaults to False.
untagged_only – Limit search to untagged archives only, sent as untaggedonly. Defaults to False.
hide_completed – Hide archives where reading progress has reached the end, sent as hidecompleted. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. Defaults to True.

Returns:

Same result as search_archives.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchResult.

Note

Falsy values are not forwarded to the server: new_only, untagged_only, hide_completed and groupby_tanks become None, so the server-side default applies instead.

Search for Archives like /api/search, but return only IDs.

The ordered list of matching Archive IDs is returned without the accompanying metadata.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, following the same rules as the queries in /api/search. Defaults to None.
start – From which archive in the total result count this enumeration should start. The total number of archives displayed depends on the server-side page size preference. From 0.8.2 onwards, “-1” gives the full, unpaged list of IDs. Defaults to None.
sortby – Namespace by which you want to sort the results. Use title to sort by title, or lastread to sort by last read time, which requires Server-side Progress Tracking to be enabled. Defaults to None, which sorts by title; sorting by lastread removes IDs that have never been read from the search.
order – Order of the sort, either asc or desc. Defaults to None, which the server treats as asc.
newonly – Limit search to new archives only. Defaults to None.
untaggedonly – Limit search to untagged archives only. Defaults to None.
hidecompleted – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to None, which the server treats as true.

Returns:

One archive ID per matching archive in data.

Return type:

SearchIdsResult

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchIdsResult.

Note

The server answers with 204 when the search engine is not initialized yet. That response carries no body and therefore raises APIResponseDecodeError; wait a few seconds and retry the search in that case.

Search for Archives.

You can use the IDs of this JSON with the other endpoints.

The filter parameter accepts the following special characters:

Quotation marks ("..."): exact string search. Allows a search term to include spaces, as everything inside a pair of quotation marks is treated as a singular term. Wildcard characters are still interpreted as wildcards.
Question mark (?), underscore (_): wildcard matching any single character.
Asterisk (*), percentage sign (%): wildcard matching any sequence of characters, including none.
Subtraction sign (-): exclusion. When placed before a term, it prevents search results from including that term.
Dollar sign ($): add at the end of a tag to perform an exact tag search rather than displaying all elements that start with the term. Only matches tags regardless of the search parameters, and can be used as an exclusion to ignore misc tags in the search query.

Parameters:

category – ID of the category you want to restrict this search to. Defaults to None.
filter – Search query, using the special characters listed above. Defaults to None.
start – From which archive in the total result count this enumeration should start. The total number of archives displayed depends on the server-side page size preference. From 0.8.2 onwards, “-1” gives the full, unpaged data. Defaults to None.
sortby – Namespace by which you want to sort the results. Use title to sort by title, or lastread to sort by last read time, which requires Server-side Progress Tracking to be enabled. Defaults to None, which sorts by title; sorting by lastread removes IDs that have never been read from the search.
order – Order of the sort, either asc or desc. Defaults to None, which the server treats as asc.
newonly – Limit search to new archives only. Defaults to None.
untaggedonly – Limit search to untagged archives only. Defaults to None.
hidecompleted – Hide archives where reading progress has reached the end. Defaults to None.
groupby_tanks – Enable or disable Tankoubon grouping. When enabled, Tankoubons show in search results, replacing all the archive IDs they contain. Defaults to None, which the server treats as true.

Returns:

One ArchiveMetadata object per matching archive: in data.

Return type:

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the response body is not valid JSON, or does not match SearchResult.

Note

The server answers with 204 when the search engine is not initialized yet. That response carries no body and therefore raises APIResponseDecodeError; wait a few seconds and retry the search in that case.

class lanraragi_api.api.ShinobuAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Shinobu Filewatcher APIs.

Shared request and error behavior is documented on BaseAPICall.

get_shinobu_status() → dict[str, Any]¶

Get the current status of the filewatcher.

Returns:

Decoded status payload, holding the is_alive flag and the: pid of the watcher process.

Return type:

dict

Raises:

APIHttpError – Any status code other than 200.
APIResponseDecodeError – If the body is not valid JSON.

rescan_shinobu() → OperationResponse¶

Rescan the filemap and restart Shinobu.

This deletes the internal map of scanned files on your system (the “filemap”) and restarts Shinobu, effectively prompting a full rescan of your FS.

Returns:

Result of the operation, with the new process: PID as an extra field.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

restart_shinobu() → OperationResponse¶

Restart the Shinobu filewatcher.

This also starts the filewatcher again when it was stopped.

Returns:

Result of the operation, with the new process: PID as an extra field.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

stop_shinobu() → OperationResponse¶

Stop the filewatcher.

Use /api/shinobu/restart to start it again.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

class lanraragi_api.api.StampAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Stamps.

Shared request and error behavior is documented on BaseAPICall.

add_stamp(archive_id: str, index: int, content: str | None = None, position: str | None = None) → AddStampResponse¶

Add a new Stamp to the page at the given coordinates.

Parameters:

archive_id – ID of the archive.
index – Page of the archive.
content – Text of the stamp. Defaults to None.
position – Position of the stamp in the page. Defaults to None.

Returns:

Result of the operation, with the stamp_id of: the created stamp.

Return type:

AddStampResponse

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match AddStampResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

A 400 response is returned in the operation result, with success set to 0, instead of raising.

delete_stamp(id: str) → OperationResponse¶

Remove a stamp from an Archive.

Parameters:

id – ID of the stamp.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Stamp locked for modification) are returned in the operation result, with success set to 0, instead of raising.

get_stamp(id: str) → StampsData¶

Get a stamp from an Archive.

Parameters:

id – ID of the stamp.

Returns:

Stamp data.

Return type:

StampsData

Raises:

APIHttpError – 400 if the server rejected the request; 423 if the Stamp is currently locked for modification.
APIResponseDecodeError – If the response does not match StampsData.

get_stamped_pages(archive_id: str) → StampsResponse¶

Get pages that contain at least one stamp in the archive.

Parameters:

archive_id – ID of the archive.

Returns:

Page indices of the archive that contain a stamp.

Return type:

StampsResponse

Raises:

APIHttpError – 400 if the server rejected the request.
APIResponseDecodeError – If the response does not match StampsResponse.

get_stamps_by_page(archive_id: str, index: int) → list[StampsData]¶

Get the stamps linked to the page.

Parameters:

archive_id – ID of the archive.
index – Page of the archive.

Returns:

Stamps of the page.

Return type:

list[StampsData]

Raises:

APIHttpError – 400 if the server rejected the request.
APIResponseDecodeError – If the response has no result list, or if an item does not match StampsData.

update_stamp(id: str, content: str | None = None, position: str | None = None) → OperationResponse¶

Update a stamp from an Archive.

Parameters:

id – ID of the stamp.
content – Text of the stamp. Defaults to None.
position – Position of the stamp in the page. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Stamp locked for modification) are returned in the operation result, with success set to 0, instead of raising.

class lanraragi_api.api.TankoubonAPI(server: str, key: str | None = None, auth_way: Auth = Auth.AUTH_HEADER, timeout: float | tuple[int, int] | None = None, include_error_payload: bool = False, include_operation_error_message: bool = True, raise_on_operation_error: bool = False, default_headers: dict[str, str] | None = None, default_params: dict[str, str] | None = None)¶

Bases: BaseAPICall

Endpoints related to Tankoubons.

Shared request and error behavior is documented on BaseAPICall.

add_archive_to_tankoubon(tankoubon_id: str, archive_id: str) → OperationResponse¶

Append an archive at the final position of a Tankoubon.

Parameters:

tankoubon_id – ID of the Tankoubon to update.
archive_id – ID of the Archive to append.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

create_tankoubon(name: str, tankid: str | None = None) → OperationResponse¶

Create a new Tankoubon or update the name of an existing one.

Parameters:

name – Name of the Tankoubon.
tankid – ID of an existing Tankoubon, if you want to change its name. Defaults to None, which creates a new Tankoubon.

Returns:

Result of the operation; tankoubon_id holds: the ID of the created or modified Tankoubon.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

delete_tankoubon(id: str) → OperationResponse¶

Remove a Tankoubon from the server.

This doesn’t delete the underlying Archives.

Parameters:

id – ID of the Tankoubon to delete.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

get_all_tankoubons(page: int | None = None) → list[TankoubonMetadata]¶

Return only the tankoubon list of the paginated list endpoint.

This is a backward-compatible wrapper around get_tankoubon_list.

Parameters:: page – Page of the list of Tankoubons. Defaults to None.
Returns:: Tankoubons of the requested page.
Return type:: list[TankoubonMetadata]

get_tankoubon(id: str) → TankoubonMetadata¶

Get the details of the specified tankoubon ID.

This is a backward-compatible wrapper around get_tankoubon_detail.

Parameters:: id – ID of the Tankoubon desired.
Returns:: Metadata of the tankoubon.
Return type:: TankoubonMetadata

get_tankoubon_detail(id: str) → TankoubonMetadata¶

Get the details of the specified tankoubon ID.

Parameters:

id – ID of the Tankoubon desired.

Returns:

Metadata of the tankoubon.

Return type:

TankoubonMetadata

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.
APIResponseDecodeError – If the response does not match TankoubonMetadata.

get_tankoubon_full(id: str, page: int = -1) → TankoubonDetailResponse¶

Get the details of a tankoubon with paginated archive metadata.

The amount of archives per page depends on the server archives_per_page setting.

Parameters:

id – ID of the Tankoubon desired.
page – Page of the Archives list. Defaults to -1, which returns all archives.

Returns:

Tankoubon metadata with full_data: filled in.

Return type:

TankoubonDetailResponse

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.
APIResponseDecodeError – If the response has no result payload, or if it does not match TankoubonMetadata.

get_tankoubon_list(page: int | None = None) → TankoubonListResponse¶

Get list of Tankoubons paginated.

The amount of tanks per page depends on the server archives_per_page setting.

Parameters:

page – Page of the list of Tankoubons. Defaults to None.

Returns:

Tankoubons of the requested page.

Return type:

TankoubonListResponse

Raises:

APIHttpError – Any non-2xx status code returned by the server.
APIResponseDecodeError – If the response has no result list, or if an item does not match TankoubonMetadata.

get_tankoubon_thumbnail(id: str, no_fallback: bool | None = None) → Response¶

Get the cover thumbnail for a given Tankoubon.

By default, the thumbnail is sourced from the first page of the first archive. This endpoint returns a placeholder image if the thumbnail does not exist yet. If you want to queue generation of the thumbnail in the background, you can use the no_fallback query parameter.

Parameters:

id – ID of the Tankoubon desired.
no_fallback – Disables the placeholder image, queues the thumbnail for extraction and returns a JSON with code 202. This parameter does nothing if the image already exists. Defaults to None.

Returns:

Response of the server, either the thumbnail bytes with: code 200 or the job JSON with code 202.

Return type:

Response

Raises:

APIHttpError – 400 if the server rejected the request, or any other non-2xx status code.

Note

When the thumbnail already exists, the image is returned with code 200 no matter what. Otherwise, no_fallback queues the extraction and the 202 body carries a Minion job; use /api/minion/:jobid to track when the thumbnail is ready.

remove_archive_from_tankoubon(tankoubon_id: str, archive_id: str) → OperationResponse¶

Remove an archive from a Tankoubon.

Parameters:

tankoubon_id – ID of the Tankoubon to update.
archive_id – ID of the archive to remove.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

Failure responses such as 400 (error response) or 423 (Tankoubon locked for modification) are returned in the operation result, with success set to 0, instead of raising.

update_tank_progress(id: str, page: int) → OperationResponse¶

Tell the server which page of this Tankoubon you’re reading.

The server updates its internal reading progression accordingly. The page number is global across all Archives in the tank (if a tank has two Archives with 20 and 25 pages, page 26 will be page 6 in Archive #2).

Parameters:

id – ID of the Tankoubon to update.
page – Global 1-indexed page number to update the reading progress to. Must be a positive integer.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

If the server is configured to use clientside progress tracking, this API call returns an error. Make sure to check through /api/info whether the server tracks reading progression or not before calling this endpoint.

Modify the full metadata (name, summary, additional tags) or the contents of a Tankoubon.

If you only need to change the name of a Tank, consider just using PUT /api/tankoubons instead.

Parameters:

id – ID of the Tankoubon to update.
archives – Ordered list of archive IDs. Defaults to None.
name – Name of the Tankoubon. Defaults to None.
summary – Summary of the Tankoubon. Defaults to None.
tags – Additional tags for the Tankoubon, in LRR comma-separated format. This replaces whatever additional tags the Tank already has, unless append is True. Defaults to None.
append – If True, tags are appended to the Tank’s existing own tags instead of replacing them. Defaults to None, which leaves the server default of False.
metadata – Metadata payload, merged with the explicit arguments. Defaults to None.

Returns:

Result of the operation.

Return type:

Raises:

APIResponseDecodeError – If the response body is not valid JSON, or does not match OperationResponse.
APIOperationError – If the operation failed and raising is enabled.

Note

If there is no need to update something in one of the metadata keys, do not send the key, as this can otherwise result in unwanted results.

update_tankoubon_thumbnail(id: str, page: int) → OperationResponse¶

Set the cover thumbnail of a Tankoubon from a global page number.

The global page falls within all archives of the tank, in order, and is translated to the correct archive and local page automatically.

Parameters:

id – ID of the Tankoubon desired.
page – Global 1-indexed page number across all archives in the tankoubon. Page 1 is the first page of the first archive, and so on.

Returns:

Result of the operation.

Return type: