Books Service

The BookService allows searching for books and retrieving detailed information.

Example

from pyskoob import SkoobClient
from pyskoob.models.enums import BookSearch

with SkoobClient() as client:
    results = client.books.search("Duna", BookSearch.TITLE)
    for book in results.results:
        print(book.title, book.book_id)

Bases: _BookServiceMixin, BaseSkoobService

High level operations for retrieving and searching books.

Source code in pyskoob/books.py

class BookService(_BookServiceMixin, BaseSkoobService):
    """High level operations for retrieving and searching books."""

    def search(
        self,
        query: str,
        search_by: BookSearch = BookSearch.TITLE,
        page: int = 1,
    ) -> Pagination[BookSearchResult]:
        """Search for books by query and type.

        Parameters
        ----------
        query : str
            Text to search for in book titles, ISBNs or authors depending on
            ``search_by``.
        search_by : BookSearch, optional
            Criteria used for searching, by default ``BookSearch.TITLE``.
        page : int, optional
            Result page number, by default ``1``.

        Returns
        -------
        Pagination[BookSearchResult]
            Paginated collection of matching books.

        Examples
        --------
        >>> service.search("Duna").results[0].title
        'Duna'
        """
        return run_sync(self._search(query, search_by, page))

    def get_by_id(self, edition_id: int) -> Book:
        """Retrieve a book by its edition ID.

        Parameters
        ----------
        edition_id : int
            Edition identifier from Skoob.

        Returns
        -------
        Book
            Fully parsed book information.
        """
        return run_sync(self._get_by_id(edition_id))

    def get_reviews(self, book_id: int, edition_id: int | None = None, page: int = 1) -> Pagination[BookReview]:
        """Retrieve reviews for a book.

        Parameters
        ----------
        book_id : int
            Identifier of the book whose reviews will be retrieved.
        edition_id : int, optional
            Specific edition identifier. When ``None`` the edition is inferred
            from the reviews page.
        page : int, optional
            Review page number, by default ``1``.

        Returns
        -------
        Pagination[BookReview]
            Paginated list of book reviews.
        """
        return run_sync(self._get_reviews(book_id, edition_id, page))

    def get_users_by_status(
        self,
        book_id: int,
        status: BookUserStatus,
        edition_id: int | None = None,
        limit: int = 500,
        page: int = 1,
    ) -> Pagination[int]:
        """Retrieve users who have a book with a specific status.

        Parameters
        ----------
        book_id : int
            Identifier of the book to inspect.
        status : BookUserStatus
            Desired user status for the book.
        edition_id : int, optional
            Specific edition identifier to filter by.
        limit : int, optional
            Maximum number of IDs per page, by default ``500``.
        page : int, optional
            Page number to retrieve, by default ``1``.

        Returns
        -------
        Pagination[int]
            Paginated list of user IDs.
        """
        return run_sync(self._get_users_by_status(book_id, status, edition_id, limit, page))

get_by_id(edition_id)

Retrieve a book by its edition ID.

Parameters:

Name	Type	Description	Default
edition_id	int	Edition identifier from Skoob.	required

Returns:

Type	Description
Book	Fully parsed book information.

Source code in pyskoob/books.py

def get_by_id(self, edition_id: int) -> Book:
    """Retrieve a book by its edition ID.

    Parameters
    ----------
    edition_id : int
        Edition identifier from Skoob.

    Returns
    -------
    Book
        Fully parsed book information.
    """
    return run_sync(self._get_by_id(edition_id))

get_reviews(book_id, edition_id=None, page=1)

Retrieve reviews for a book.

Parameters:

Name	Type	Description	Default
book_id	int	Identifier of the book whose reviews will be retrieved.	required
edition_id	int	Specific edition identifier. When None the edition is inferred from the reviews page.	None
page	int	Review page number, by default 1.	1

Returns:

Type	Description
Pagination[BookReview]	Paginated list of book reviews.

Source code in pyskoob/books.py

def get_reviews(self, book_id: int, edition_id: int | None = None, page: int = 1) -> Pagination[BookReview]:
    """Retrieve reviews for a book.

    Parameters
    ----------
    book_id : int
        Identifier of the book whose reviews will be retrieved.
    edition_id : int, optional
        Specific edition identifier. When ``None`` the edition is inferred
        from the reviews page.
    page : int, optional
        Review page number, by default ``1``.

    Returns
    -------
    Pagination[BookReview]
        Paginated list of book reviews.
    """
    return run_sync(self._get_reviews(book_id, edition_id, page))

get_users_by_status(book_id, status, edition_id=None, limit=500, page=1)

Retrieve users who have a book with a specific status.

Parameters:

Name	Type	Description	Default
book_id	int	Identifier of the book to inspect.	required
status	BookUserStatus	Desired user status for the book.	required
edition_id	int	Specific edition identifier to filter by.	None
limit	int	Maximum number of IDs per page, by default 500.	500
page	int	Page number to retrieve, by default 1.	1

Returns:

Type	Description
Pagination[int]	Paginated list of user IDs.

Source code in pyskoob/books.py

def get_users_by_status(
    self,
    book_id: int,
    status: BookUserStatus,
    edition_id: int | None = None,
    limit: int = 500,
    page: int = 1,
) -> Pagination[int]:
    """Retrieve users who have a book with a specific status.

    Parameters
    ----------
    book_id : int
        Identifier of the book to inspect.
    status : BookUserStatus
        Desired user status for the book.
    edition_id : int, optional
        Specific edition identifier to filter by.
    limit : int, optional
        Maximum number of IDs per page, by default ``500``.
    page : int, optional
        Page number to retrieve, by default ``1``.

    Returns
    -------
    Pagination[int]
        Paginated list of user IDs.
    """
    return run_sync(self._get_users_by_status(book_id, status, edition_id, limit, page))

search(query, search_by=BookSearch.TITLE, page=1)

Search for books by query and type.

Parameters:

Name	Type	Description	Default
query	str	Text to search for in book titles, ISBNs or authors depending on search_by.	required
search_by	BookSearch	Criteria used for searching, by default BookSearch.TITLE.	TITLE
page	int	Result page number, by default 1.	1

Returns:

Type	Description
Pagination[BookSearchResult]	Paginated collection of matching books.

Examples:

>>> service.search("Duna").results[0].title
'Duna'

Source code in pyskoob/books.py

def search(
    self,
    query: str,
    search_by: BookSearch = BookSearch.TITLE,
    page: int = 1,
) -> Pagination[BookSearchResult]:
    """Search for books by query and type.

    Parameters
    ----------
    query : str
        Text to search for in book titles, ISBNs or authors depending on
        ``search_by``.
    search_by : BookSearch, optional
        Criteria used for searching, by default ``BookSearch.TITLE``.
    page : int, optional
        Result page number, by default ``1``.

    Returns
    -------
    Pagination[BookSearchResult]
        Paginated collection of matching books.

    Examples
    --------
    >>> service.search("Duna").results[0].title
    'Duna'
    """
    return run_sync(self._search(query, search_by, page))