pyskoob 0.2.0

Python client for the Skoob website handling authentication and HTML parsing

PySkoob

PySkoob is a Python client that makes it easy to interact with the Skoob website. It takes care of authentication and HTML parsing so you can focus on your automation or data collection tasks.

Features

• Search books by title, author or ISBN
• Retrieve detailed book information and reviews
• Access user profiles and reading statistics
• Authenticate using email/password or an existing session cookie

Services

Documentation for each service is available on GitHub Pages:

• Author Service
• Books Service
• Publisher Service
• Users Service
• Profile Service

Installation

Install the latest release from PyPI:

python -m pip install pyskoob

Or install the bleeding edge version from GitHub:

python -m pip install git+https://github.com/victor-soeiro/pyskoob.git

Authentication

You can authenticate in two different ways:

1. Email and password

   from pyskoob import SkoobClient
   
   with SkoobClient() as client:
       me = client.auth.login(email="[e-mail]", password="secret")
   

2. Session cookie

   from pyskoob import SkoobClient
   
   with SkoobClient() as client:
       me = client.auth.login_with_cookies("PHPSESSID_TOKEN")
   

Once authenticated you can access all other services.

Usage example

Search for books

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

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

Fetch book details

from pyskoob import SkoobClient

with SkoobClient() as client:
    book = client.books.get_by_id(1)  # replace with a real edition ID
    print(book.title, book.publisher.name)

Authenticate and access your profile

from pyskoob import SkoobClient

with SkoobClient() as client:
    # TIP: use environment variables or a secrets manager instead of hard-coding credentials
    me = client.auth.login(email="[e-mail]", password="secret")
    print(me.name)

Rate limiting

Skoob may block clients that issue too many requests in a short period of time. PySkoob includes a basic rate limiter that throttles requests to one per second by default. Adjusting this limit is possible but done entirely at your own risk—Skoob may block or ban your account. Provide a custom :class:pyskoob.utils.RateLimiter instance to change or disable the limit:

from pyskoob import RateLimiter, SkoobClient

limiter = RateLimiter(max_calls=2, period=1)  # two requests per second (use at your own risk)
with SkoobClient(rate_limiter=limiter) as client:
    ...

SkoobAsyncClient accepts the same configuration options and forwards any extra keyword arguments to httpx.AsyncClient. You may also provide a pre-configured HTTP client or manage the lifecycle manually using the explicit close method:

from pyskoob import RateLimiter, SkoobAsyncClient
from pyskoob.http.httpx import HttpxAsyncClient

limiter = RateLimiter(max_calls=2, period=1)
http_client = HttpxAsyncClient(rate_limiter=limiter, timeout=5)
client = SkoobAsyncClient(http_client=http_client)
try:
    ...
finally:
    await client.close()

Running tests

Install the project in editable mode and run the test suite:

uv pip install -e .[dev]
pytest -vv

Contributing

Before working on new features, set up a local development environment:

# Install uv if it's not already available
python -m pip install uv

# Create and activate a virtual environment
uv venv .venv
source .venv/bin/activate
# On Windows
.\.venv\Scripts\activate

# Install the project with development dependencies
uv pip install -e .[dev]

# Install pre-commit hooks
pre-commit install

# Verify linting, formatting, and tests
pytest -vv
pre-commit run --all-files

Once everything is ready:

1. Fork the repository and create a branch for your feature.

2. Implement your change and add tests.

3. Format your code with Ruff:

   ruff format .
   

4. Ensure lint checks pass:

   ruff check .
   

5. Run pytest -vv and pre-commit run --all-files and ensure everything passes.

6. Open a pull request describing your changes.

Learn more

• Examples
• Documentation
• Contributing guidelines