lanraragi_api package¶

Subpackages¶

Submodules¶

lanraragi_api.error module¶

exception lanraragi_api.error.APIError¶

Bases: Exception

Base exception for all API client errors.

exception lanraragi_api.error.APIHttpError(status_code: int, url: str)¶

Bases: APIError

Raised when the server answers with an unexpected status code.

status_code¶: HTTP status code returned by the server.

url¶: Absolute URL the request was sent to.

exception lanraragi_api.error.APIOperationError(operation: str, message: str | None, status_code: int | None = None, payload: dict[str, Any] | None = None)¶

Bases: APIError

Raised when an operation endpoint reports a failure.

Only raised when raising is enabled, either through the client-level raise_on_operation_error setting or through the raise_on_failure argument of a single call. Otherwise the failed operation is returned to the caller like any other result.

operation¶: Name of the operation reported by the server.

message¶: Error message reported by the server, if it was kept.

status_code¶: HTTP status code of the response, if one was returned.

payload¶: Raw response payload, if the client was configured to keep it.

exception lanraragi_api.error.APIRequestError(url: str, error_type: str | None = None)¶

Bases: APIError

Raised when a request cannot be sent to the server.

It covers transport level failures such as a refused connection or a timeout. HTTP error statuses are reported through APIHttpError instead. The message names the class of the underlying requests exception when one is available.

url¶: Absolute URL the request was sent to.

exception lanraragi_api.error.APIResponseDecodeError(url: str, message: str)¶

Bases: APIError

Raised when a response body cannot be turned into the expected model.

It is raised for a body that is not valid JSON for a JSON endpoint, and for a JSON payload that does not match the pydantic model of the endpoint.

url¶: Absolute URL the request was sent to.

lanraragi_api.lanraragi module¶

class lanraragi_api.lanraragi.LANraragiAPI(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

Entry point of the library, grouping every API section of a server.

Each attribute is an independent client for one group of endpoints, and all of them share the connection settings passed to this class.

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.

search¶

Search endpoints.

Type:: SearchAPI

archives¶

Archive endpoints.

Type:: ArchiveAPI

database¶

Database endpoints.

Type:: DatabaseAPI

categories¶

Category endpoints.

Type:: CategoryAPI

tankoubons¶

Tankoubon endpoints.

Type:: TankoubonAPI

plugins¶

Plugin endpoints.

Type:: PluginAPI

shinobu¶

Shinobu endpoints.

Type:: ShinobuAPI

minion¶

Minion job endpoints.

Type:: MinionAPI

opds¶

OPDS endpoints.

Type:: OPDSAPI

misc¶

Miscellaneous endpoints.

Type:: MiscAPI

stamps¶

Stamp endpoints.

Type:: StampAPI

Module contents¶

exception lanraragi_api.APIError¶

Bases: Exception

Base exception for all API client errors.

exception lanraragi_api.APIHttpError(status_code: int, url: str)¶

Bases: APIError

Raised when the server answers with an unexpected status code.

status_code¶: HTTP status code returned by the server.

url¶: Absolute URL the request was sent to.

exception lanraragi_api.APIOperationError(operation: str, message: str | None, status_code: int | None = None, payload: dict[str, Any] | None = None)¶

Bases: APIError

Raised when an operation endpoint reports a failure.

Only raised when raising is enabled, either through the client-level raise_on_operation_error setting or through the raise_on_failure argument of a single call. Otherwise the failed operation is returned to the caller like any other result.

operation¶: Name of the operation reported by the server.

message¶: Error message reported by the server, if it was kept.

status_code¶: HTTP status code of the response, if one was returned.

payload¶: Raw response payload, if the client was configured to keep it.

exception lanraragi_api.APIRequestError(url: str, error_type: str | None = None)¶

Bases: APIError

Raised when a request cannot be sent to the server.

It covers transport level failures such as a refused connection or a timeout. HTTP error statuses are reported through APIHttpError instead. The message names the class of the underlying requests exception when one is available.

url¶: Absolute URL the request was sent to.

exception lanraragi_api.APIResponseDecodeError(url: str, message: str)¶

Bases: APIError

Raised when a response body cannot be turned into the expected model.

It is raised for a body that is not valid JSON for a JSON endpoint, and for a JSON payload that does not match the pydantic model of the endpoint.

url¶: Absolute URL the request was sent to.

class lanraragi_api.LANraragiAPI(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

Entry point of the library, grouping every API section of a server.

Each attribute is an independent client for one group of endpoints, and all of them share the connection settings passed to this class.

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.