Skip to content

PySkoob Documentation

Welcome to the PySkoob documentation. This site provides usage examples and a reference of the available services.

Installation

pip install pyskoob

Usage

from pyskoob import SkoobClient

with SkoobClient() as client:
    books = client.books.search("python").results

API Reference

Client facades bundling synchronous and asynchronous services.

SkoobAsyncClient

Facade for interacting with Skoob services asynchronously.

Parameters:

Name Type Description Default
http_client AsyncHTTPClient | None

Optional pre-configured HTTP client implementing :class:AsyncHTTPClient. When provided, rate_limiter and client_kwargs are ignored.

 None
rate_limiter RateLimiter | None

Optional rate limiter used to throttle requests. When http_client is None, a default limiter allowing one request per second is used.

 None
retry Retry | None

Optional retry handler for automatically retrying requests on network errors. Ignored when http_client is provided.

 None
**client_kwargs Any

Additional keyword arguments forwarded to httpx.AsyncClient when the default client is constructed.

 {}
Source code in pyskoob/client.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
class SkoobAsyncClient:
    """Facade for interacting with Skoob services asynchronously.

    Parameters
    ----------
    http_client:
        Optional pre-configured HTTP client implementing :class:`AsyncHTTPClient`.
        When provided, ``rate_limiter`` and ``client_kwargs`` are ignored.
    rate_limiter:
        Optional rate limiter used to throttle requests. When ``http_client`` is
        ``None``, a default limiter allowing one request per second is used.
    retry:
        Optional retry handler for automatically retrying requests on network
        errors. Ignored when ``http_client`` is provided.
    **client_kwargs:
        Additional keyword arguments forwarded to ``httpx.AsyncClient`` when the
        default client is constructed.
    """

    def __init__(
        self,
        http_client: AsyncHTTPClient | None = None,
        *,
        rate_limiter: RateLimiter | None = None,
        retry: Retry | None = None,
        **client_kwargs: Any,
    ) -> None:
        if http_client is not None:
            self._client = http_client
        else:
            self._client = HttpxAsyncClient(rate_limiter=rate_limiter, retry=retry, **client_kwargs)
        self.auth = AsyncAuthService(self._client)
        self.books = AsyncBookService(self._client)
        self.authors = AsyncAuthorService(self._client)
        self.users = AsyncUserService(self._client, self.auth)
        self.me = AsyncSkoobProfileService(self._client, self.auth)
        self.publishers = AsyncPublisherService(self._client)

    async def __aenter__(self) -> SkoobAsyncClient:
        return self

    async def __aexit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> Literal[False]:
        """Exit the async runtime context, closing the HTTPX client.

        Parameters
        ----------
        exc_type : type[BaseException] | None
            The exception type.
        exc_val : BaseException | None
            The exception value.
        exc_tb : TracebackType | None
            The traceback object.

        Returns
        -------
        Literal[False]
            Always returns ``False`` so exceptions are never suppressed.
        """
        await self.close()
        return False

    async def close(self) -> None:
        """Close the underlying HTTP client.

        Examples
        --------
        >>> client = SkoobAsyncClient()
        >>> await client.close()
        """
        await self._client.close()

__aexit__(exc_type, exc_val, exc_tb) async

Exit the async runtime context, closing the HTTPX client.

Parameters:

Name Type Description Default
exc_type type[BaseException] | None

The exception type.

 required
exc_val BaseException | None

The exception value.

 required
exc_tb TracebackType | None

The traceback object.

 required

Returns:

Type Description
Literal[False]

Always returns False so exceptions are never suppressed.
Source code in pyskoob/client.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
async def __aexit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> Literal[False]:
    """Exit the async runtime context, closing the HTTPX client.

    Parameters
    ----------
    exc_type : type[BaseException] | None
        The exception type.
    exc_val : BaseException | None
        The exception value.
    exc_tb : TracebackType | None
        The traceback object.

    Returns
    -------
    Literal[False]
        Always returns ``False`` so exceptions are never suppressed.
    """
    await self.close()
    return False

close() async

Close the underlying HTTP client.

Examples:

>>> client = SkoobAsyncClient()
>>> await client.close()
Source code in pyskoob/client.py 
182
183
184
185
186
187
188
189
190
async def close(self) -> None:
    """Close the underlying HTTP client.

    Examples
    --------
    >>> client = SkoobAsyncClient()
    >>> await client.close()
    """
    await self._client.close()

SkoobClient

Facade for interacting with Skoob services.

Examples:

>>> with SkoobClient() as client:
...     client.auth.login_with_cookies("token")
Source code in pyskoob/client.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class SkoobClient:
    """Facade for interacting with Skoob services.

    Examples
    --------
    >>> with SkoobClient() as client:
    ...     client.auth.login_with_cookies("token")
    """

    def __init__(
        self,
        rate_limiter: RateLimiter | None = None,
        retry: Retry | None = None,
        **kwargs: Any,
    ) -> None:
        """Initializes the SkoobClient.

        Parameters
        ----------
        rate_limiter:
            Optional rate limiter used to throttle requests. If ``None``, a
            default limiter allowing one request per second is used.
        retry:
            Optional retry handler for automatically retrying requests on
            network errors. If ``None`` a default configuration is used.
        **kwargs:
            Additional keyword arguments forwarded to ``httpx.Client`` when the
            underlying :class:`HttpxSyncClient` is constructed.
        """

        self._client = HttpxSyncClient(rate_limiter=rate_limiter, retry=retry, **kwargs)
        self.auth = AuthService(self._client)
        self.books = BookService(self._client)
        self.authors = AuthorService(self._client)
        self.users = UserService(self._client, self.auth)
        self.me = SkoobProfileService(self._client, self.auth)
        self.publishers = PublisherService(self._client)

    def __enter__(self) -> SkoobClient:
        """
        Enter the runtime context for the SkoobClient.

        Returns
        -------
        SkoobClient
            The SkoobClient instance.

        Examples
        --------
        >>> with SkoobClient() as client:
        ...     pass
        """
        return self

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: TracebackType | None,
    ) -> Literal[False]:
        """
        Exit the runtime context, closing the HTTPX client.

        Parameters
        ----------
        exc_type : type[BaseException] | None
            The exception type.
        exc_val : BaseException | None
            The exception value.
        exc_tb : TracebackType | None
            The traceback object.

        Returns
        -------
        Literal[False]
            Always returns ``False`` so exceptions are never suppressed.

        Examples
        --------
        >>> client = SkoobClient()
        >>> client.__exit__(None, None, None)
        False
        """
        self.close()
        return False

    def close(self) -> None:
        """Close the underlying HTTP client.

        Examples
        --------
        >>> client = SkoobClient()
        >>> client.close()
        """
        self._client.close()

__enter__()

Enter the runtime context for the SkoobClient.

Returns:

Type Description
SkoobClient

The SkoobClient instance.

Examples:

>>> with SkoobClient() as client:
...     pass
Source code in pyskoob/client.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def __enter__(self) -> SkoobClient:
    """
    Enter the runtime context for the SkoobClient.

    Returns
    -------
    SkoobClient
        The SkoobClient instance.

    Examples
    --------
    >>> with SkoobClient() as client:
    ...     pass
    """
    return self

__exit__(exc_type, exc_val, exc_tb)

Exit the runtime context, closing the HTTPX client.

Parameters:

Name Type Description Default
exc_type type[BaseException] | None

The exception type.

 required
exc_val BaseException | None

The exception value.

 required
exc_tb TracebackType | None

The traceback object.

 required

Returns:

Type Description
Literal[False]

Always returns False so exceptions are never suppressed.

Examples:

>>> client = SkoobClient()
>>> client.__exit__(None, None, None)
False
Source code in pyskoob/client.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def __exit__(
    self,
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) -> Literal[False]:
    """
    Exit the runtime context, closing the HTTPX client.

    Parameters
    ----------
    exc_type : type[BaseException] | None
        The exception type.
    exc_val : BaseException | None
        The exception value.
    exc_tb : TracebackType | None
        The traceback object.

    Returns
    -------
    Literal[False]
        Always returns ``False`` so exceptions are never suppressed.

    Examples
    --------
    >>> client = SkoobClient()
    >>> client.__exit__(None, None, None)
    False
    """
    self.close()
    return False

__init__(rate_limiter=None, retry=None, **kwargs)

Initializes the SkoobClient.

Parameters:

Name Type Description Default
rate_limiter RateLimiter | None

Optional rate limiter used to throttle requests. If None, a default limiter allowing one request per second is used.

 None
retry Retry | None

Optional retry handler for automatically retrying requests on network errors. If None a default configuration is used.

 None
**kwargs Any

Additional keyword arguments forwarded to httpx.Client when the underlying :class:HttpxSyncClient is constructed.

 {}
Source code in pyskoob/client.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
def __init__(
    self,
    rate_limiter: RateLimiter | None = None,
    retry: Retry | None = None,
    **kwargs: Any,
) -> None:
    """Initializes the SkoobClient.

    Parameters
    ----------
    rate_limiter:
        Optional rate limiter used to throttle requests. If ``None``, a
        default limiter allowing one request per second is used.
    retry:
        Optional retry handler for automatically retrying requests on
        network errors. If ``None`` a default configuration is used.
    **kwargs:
        Additional keyword arguments forwarded to ``httpx.Client`` when the
        underlying :class:`HttpxSyncClient` is constructed.
    """

    self._client = HttpxSyncClient(rate_limiter=rate_limiter, retry=retry, **kwargs)
    self.auth = AuthService(self._client)
    self.books = BookService(self._client)
    self.authors = AuthorService(self._client)
    self.users = UserService(self._client, self.auth)
    self.me = SkoobProfileService(self._client, self.auth)
    self.publishers = PublisherService(self._client)

close()

Close the underlying HTTP client.

Examples:

>>> client = SkoobClient()
>>> client.close()
Source code in pyskoob/client.py 
105
106
107
108
109
110
111
112
113
def close(self) -> None:
    """Close the underlying HTTP client.

    Examples
    --------
    >>> client = SkoobClient()
    >>> client.close()
    """
    self._client.close()

Authentication helpers and session management for Skoob.

AsyncAuthService

Bases: _AuthServiceMixin, AsyncBaseSkoobService

Asynchronous authentication service.

Source code in pyskoob/auth.py 
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
class AsyncAuthService(_AuthServiceMixin, AsyncBaseSkoobService):  # pragma: no cover - thin async wrapper
    """Asynchronous authentication service."""

    def __init__(self, client: AsyncHTTPClient):
        super().__init__(client)
        self._is_logged_in = False

    async def login_with_cookies(self, session_token: str) -> User:
        """Log in using a pre-existing session token.

        Parameters
        ----------
        session_token : str
            Value of the ``PHPSESSID`` cookie obtained from the browser.

        Returns
        -------
        User
            Authenticated user information.
        """

        return await self._login_with_cookies(session_token)

    async def login(self, email: str, password: str) -> User:
        """Log in with email and password.

        Parameters
        ----------
        email : str
            Account email address.
        password : str
            Account password.

        Returns
        -------
        User
            Authenticated user information.
        """

        return await self._login(email, password)

    async def get_my_info(self) -> User:
        """Retrieve information about the authenticated user.

        Returns
        -------
        User
            Authenticated user details.
        """

        return await self._get_my_info()

    async def validate_login(self) -> None:
        """Validate that the current session is authenticated.

        Raises
        ------
        PermissionError
            If the service has not been authenticated yet.
        """

        self._validate_login()

get_my_info() async

Retrieve information about the authenticated user.

Returns:

Type Description
User

Authenticated user details.
Source code in pyskoob/auth.py 
245
246
247
248
249
250
251
252
253
254
async def get_my_info(self) -> User:
    """Retrieve information about the authenticated user.

    Returns
    -------
    User
        Authenticated user details.
    """

    return await self._get_my_info()

login(email, password) async

Log in with email and password.

Parameters:

Name Type Description Default
email str

Account email address.

 required
password str

Account password.

 required

Returns:

Type Description
User

Authenticated user information.
Source code in pyskoob/auth.py 
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
async def login(self, email: str, password: str) -> User:
    """Log in with email and password.

    Parameters
    ----------
    email : str
        Account email address.
    password : str
        Account password.

    Returns
    -------
    User
        Authenticated user information.
    """

    return await self._login(email, password)

login_with_cookies(session_token) async

Log in using a pre-existing session token.

Parameters:

Name Type Description Default
session_token str

Value of the PHPSESSID cookie obtained from the browser.

 required

Returns:

Type Description
User

Authenticated user information.
Source code in pyskoob/auth.py 
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
async def login_with_cookies(self, session_token: str) -> User:
    """Log in using a pre-existing session token.

    Parameters
    ----------
    session_token : str
        Value of the ``PHPSESSID`` cookie obtained from the browser.

    Returns
    -------
    User
        Authenticated user information.
    """

    return await self._login_with_cookies(session_token)

validate_login() async

Validate that the current session is authenticated.

Raises:

Type Description
PermissionError

If the service has not been authenticated yet.
Source code in pyskoob/auth.py 
256
257
258
259
260
261
262
263
264
265
async def validate_login(self) -> None:
    """Validate that the current session is authenticated.

    Raises
    ------
    PermissionError
        If the service has not been authenticated yet.
    """

    self._validate_login()

AuthService

Bases: _AuthServiceMixin, BaseSkoobService

Handle authentication with Skoob and track login state.

Source code in pyskoob/auth.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
class AuthService(_AuthServiceMixin, BaseSkoobService):
    """Handle authentication with Skoob and track login state."""

    def __init__(self, client: SyncHTTPClient):
        """Manage Skoob authentication and session validation."""

        super().__init__(client)
        self._is_logged_in = False

    def login_with_cookies(self, session_token: str) -> User:
        """Log in using a pre-existing session token.

        Parameters
        ----------
        session_token : str
            Value of the ``PHPSESSID`` cookie obtained from the browser.

        Returns
        -------
        User
            Authenticated user information.
        """

        return run_sync(self._login_with_cookies(session_token))

    def login(self, email: str, password: str) -> User:
        """Log in with email and password.

        Parameters
        ----------
        email : str
            Account email address.
        password : str
            Account password.

        Returns
        -------
        User
            Authenticated user information.
        """

        return run_sync(self._login(email, password))

    def get_my_info(self) -> User:
        """Retrieve information about the authenticated user.

        Returns
        -------
        User
            Authenticated user details.
        """

        return run_sync(self._get_my_info())

    def validate_login(self) -> None:
        """Validate that the current session is authenticated.

        Raises
        ------
        PermissionError
            If the service has not been authenticated yet.
        """

        self._validate_login()

__init__(client)

Manage Skoob authentication and session validation.

Source code in pyskoob/auth.py 
141
142
143
144
145
def __init__(self, client: SyncHTTPClient):
    """Manage Skoob authentication and session validation."""

    super().__init__(client)
    self._is_logged_in = False

get_my_info()

Retrieve information about the authenticated user.

Returns:

Type Description
User

Authenticated user details.
Source code in pyskoob/auth.py 
181
182
183
184
185
186
187
188
189
190
def get_my_info(self) -> User:
    """Retrieve information about the authenticated user.

    Returns
    -------
    User
        Authenticated user details.
    """

    return run_sync(self._get_my_info())

login(email, password)

Log in with email and password.

Parameters:

Name Type Description Default
email str

Account email address.

 required
password str

Account password.

 required

Returns:

Type Description
User

Authenticated user information.
Source code in pyskoob/auth.py 
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def login(self, email: str, password: str) -> User:
    """Log in with email and password.

    Parameters
    ----------
    email : str
        Account email address.
    password : str
        Account password.

    Returns
    -------
    User
        Authenticated user information.
    """

    return run_sync(self._login(email, password))

login_with_cookies(session_token)

Log in using a pre-existing session token.

Parameters:

Name Type Description Default
session_token str

Value of the PHPSESSID cookie obtained from the browser.

 required

Returns:

Type Description
User

Authenticated user information.
Source code in pyskoob/auth.py 
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def login_with_cookies(self, session_token: str) -> User:
    """Log in using a pre-existing session token.

    Parameters
    ----------
    session_token : str
        Value of the ``PHPSESSID`` cookie obtained from the browser.

    Returns
    -------
    User
        Authenticated user information.
    """

    return run_sync(self._login_with_cookies(session_token))

validate_login()

Validate that the current session is authenticated.

Raises:

Type Description
PermissionError

If the service has not been authenticated yet.
Source code in pyskoob/auth.py 
192
193
194
195
196
197
198
199
200
201
def validate_login(self) -> None:
    """Validate that the current session is authenticated.

    Raises
    ------
    PermissionError
        If the service has not been authenticated yet.
    """

    self._validate_login()

Further Reading