Modules Documentation

audible package

class audible.AsyncClient(auth, country_code=None, headers=None, timeout=10, response_callback=None, **session_kwargs)[source]

Bases: BaseClient[AsyncClient]

Parameters:

auth (Authenticator)
country_code (str | None)
headers (Union[Headers, Mapping[str, str], Mapping[bytes, bytes], Sequence[Tuple[str, str]], Sequence[Tuple[bytes, bytes]], None])
timeout (int)
response_callback (Callable[[Response], Any] | None)
session_kwargs (Any)

async close()[source]

Return type:: None

async delete(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async get(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async post(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async put(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

class audible.Authenticator[source]

Bases: Auth

Audible Authenticator class.

Note

A new class instance have to be instantiated with Authenticator.from_login() or Authenticator.from_file().

Added in version v0.8: The with_username attribute.

Note

Auth data saved with v0.8 or later can not be loaded with versions less than v0.8! If an auth file for a pre-Amazon account (with_username=True) was created with v0.7.1 or v0.7.2 set auth.with_username to True and save the data again. After this deregistration, refreshing access tokens and requesting cookies for another domain will work for pre-Amazon accounts.

access_token: str | None = None

property access_token_expired: bool

property access_token_expires: timedelta

activation_bytes: str | None = None

adp_token: str | None = None

auth_flow(request)[source]

Auth flow to be executed on every request by httpx.

Parameters:: request (Request) – The request made by httpx.
Yields:: The next request
Raises:: AuthFlowError – If no auth flow is available.
Return type:: Generator[Request, Response, None]

property available_auth_modes: list[str]

crypter: AESCipher | None = None

customer_info: dict[str, Any] | None = None

deregister_device(deregister_all=False)[source]

Parameters:: deregister_all (bool)
Return type:: Any

device_info: dict[str, Any] | None = None

device_private_key: str | None = None

encryption: str | bool | None = None

expires: float | None = None

filename: Optional[Path] = None

classmethod from_dict(data, locale=None)[source]

Instantiate an Authenticator from authentication file.

Added in version v0.7.1.

Parameters:

data (dict[str, Any]) – A dictionary with the authentication data
locale (Union[str, Locale, None]) – The country code of the Audible marketplace to interact with. If None the country code from file is used.

Return type:

Authenticator

Returns:

A new Authenticator instance.

classmethod from_file(filename, password=None, locale=None, encryption=None, **kwargs)[source]

Instantiate an Authenticator from authentication file.

Added in version v0.5.0.

Parameters:

filename (Union[str, Path]) – The name of the file with the authentication data.
password (str | None) – The password of the authentication file.
locale (Union[str, Locale, None]) – The country code of the Audible marketplace to interact with. If None the country code from file is used.
encryption (bool | str | None) – The encryption style to use. Can be json or bytes. If None, encryption will be auto detected.
**kwargs (Any) – Keyword arguments are passed to the AESCipher class. See below.

Keyword Arguments:

key_size (int, Optional)
salt_marker (Optional[bytes])
kdf_iterations (int, optional)
hashmod
mac

Return type:

Authenticator

Returns:

A new Authenticator instance.

Raises:

FileEncryptionError – If file ist encrypted without providing a password

classmethod from_login(username, password, locale, serial=None, with_username=False, captcha_callback=None, otp_callback=None, cvf_callback=None, approval_callback=None)[source]

Instantiate a new Authenticator with authentication data from login.

Added in version v0.5.0.

Added in version v0.5.4: The serial argument The with_username argument

Parameters:

username (str) – The Amazon email address.
password (str) – The Amazon password.
locale (Union[str, Locale]) – The country_code or audible.localization.Locale instance for the marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
captcha_callback (Callable[[str], str] | None) – A custom callback to handle captcha requests during login.
otp_callback (Callable[[], str] | None) – A custom callback to handle one-time password requests during login.
cvf_callback (Callable[[], str] | None) – A custom callback to handle verify code requests during login.
approval_callback (Callable[[], Any] | None) – A custom Callable for handling approval alerts.

Return type:

Authenticator

Returns:

An Authenticator instance.

classmethod from_login_external(locale, serial=None, with_username=False, login_url_callback=None)[source]

Instantiate a new Authenticator from login with external browser.

Added in version v0.5.1.

Added in version v0.5.4: The serial argument The with_username argument

Parameters:

locale (Union[str, Locale]) – The country_code or audible.localization.Locale instance for the marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
login_url_callback (Callable[[str], str] | None) – A custom Callable for handling login with external browsers.

Return type:

Authenticator

Returns:

An Authenticator instance.

get_activation_bytes(filename=None, extract=True, force_refresh=False)[source]

Get Activation bytes from Audible.

Parameters:

filename (Union[Path, str, None]) – [Optional] filename to save the activation blob
extract (Literal[True, False]) – [Optional] if True, returns the extracted activation bytes otherwise the whole activation blob
force_refresh (bool) – [Optional] if True, existing activation bytes in auth file will be ignored and new activation bytes will be requested from server.

Return type:

str | bytes

Returns:

The activation bytes

Added in version 0.5.1: The force_refresh argument. Fetched activation bytes are now stored to Authententicator.activation_bytes.

locale: Optional[Locale] = None

refresh_access_token(force=False)[source]

Parameters:: force (bool)
Return type:: None

refresh_token: str | None = None

requires_request_body: bool = True

set_website_cookies_for_country(country_code)[source]

Parameters:: country_code (str)
Return type:: None

sign_request(request)[source]

Sign a request.

Deprecated since version 0.5.0: Use self._apply_signing_auth_flow() instead.

Parameters:: request (Request)
Return type:: None

store_authentication_cookie: dict[str, Any] | None = None

to_dict()[source]: Returns authentication data as dict. :rtype: dict[str, Any]

Added in version 0.7.1.

Added in version v0.8: The returned dict now contains the with_username attribute

to_file(filename=None, password=None, encryption='default', indent=4, set_default=True, **kwargs)[source]

Save authentication data to file.

Added in version 0.5.1: Save activation bytes to auth file

Added in version v0.8: The saved file now contains the with_username attribute

Parameters:

filename (Union[Path, str, None])
password (str | None)
encryption (bool | str)
indent (int)
set_default (bool)
kwargs (Any)

Return type:

None

user_profile()[source]

Return type:: dict[str, Any]

website_cookies: dict[str, Any] | None = None

with_username: bool | None = False

class audible.Client(auth, country_code=None, headers=None, timeout=10, response_callback=None, **session_kwargs)[source]

Bases: BaseClient[Client]

Parameters:

auth (Authenticator)
country_code (str | None)
headers (Union[Headers, Mapping[str, str], Mapping[bytes, bytes], Sequence[Tuple[str, str]], Sequence[Tuple[bytes, bytes]], None])
timeout (int)
response_callback (Callable[[Response], Any] | None)
session_kwargs (Any)

close()[source]

Return type:: None

delete(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

get(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

post(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

put(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

audible.activation_bytes module

audible.activation_bytes.extract_activation_bytes(data)[source]

Extracts the activation bytes from activation blob.

Parameters:: data (bytes) – A activation blob returned by fetch_activation function
Return type:: str
Returns:: The extracted activation bytes.
Raises:: ValueError – If data is not a valid activation blob.

audible.activation_bytes.fetch_activation(player_token)[source]

Fetches the activation blob with player token from Audible server.

Parameters:: player_token (str) – A player token returned by get_player_token function.
Return type:: bytes
Returns:: The activation blob.

audible.activation_bytes.fetch_activation_sign_auth(auth)[source]

Fetches the activation blob with sign authentication from Audible server.

Parameters:: auth (Authenticator) – A Authenticator instance with valid adp_token and device_private_cert.
Return type:: bytes
Returns:: The activation blob.
Raises:: AuthFlowError – If no valid auth method is available.

audible.activation_bytes.get_activation_bytes(auth, filename=None, extract=True)[source]

Fetches the activation blob from Audible and extracts the bytes.

Parameters:

auth (Authenticator) – The Authenticator.
filename (str | Path | None) – The filename to save the activation blob (Default: None).
extract (Literal[True, False]) – If True, returns the extracted activation bytes otherwise the whole activation blob (Default: True).

Return type:

str | bytes

Returns:

The activation bytes or activation blob.

Raises:

AuthFlowError – If no valid auth method is available.

audible.activation_bytes.get_player_id()[source]

Build a software player Id.

Return type:: str

audible.activation_bytes.get_player_token(auth)[source]

Fetches a player token for further authentication.

Parameters:: auth (Authenticator) – The Authenticator.
Return type:: str
Returns:: The player token.
Raises:: Exception – If playerToken not found in response url query.

audible.aescipher module

class audible.aescipher.AESCipher(password, *, key_size=32, salt_marker=b'$', kdf_iterations=1000, hashmod=<built-in function openssl_sha256>, mac=<module 'hmac' from '/home/docs/.asdf/installs/python/3.12.7/lib/python3.12/hmac.py'>)[source]

Bases: object

Encrypt/Decrypt data using password to generate key.

The encryption algorithm used is symmetric AES in cipher-block chaining (CBC) mode.

The key is derived via the PBKDF2 key derivation function (KDF) from the password and a random salt of 16 bytes (the AES block size) minus the length of the salt header (see below). The hash function used by PBKDF2 is SHA256 per default. You can pass a different hash function module via the hashmod argument. The module must adhere to the Python API for Cryptographic Hash Functions (PEP 247). PBKDF2 uses a number of iterations of the hash function to derive the key, which can be set via the kdf_iterations keyword argument. The default number is 1000 and the maximum 65535. The header and the salt are written to the first block of the encrypted output (bytes mode) or written as key/value pairs (dict mode). The header consist of the number of KDF iterations encoded as a big-endian word bytes wrapped by salt_marker on both sides. With the default value of salt_marker = b'$', the header size is thus 4 and the salt 12 bytes. The salt marker must be a byte string of 1-6 bytes length. The last block of the encrypted output is padded with up to 16 bytes, all having the value of the length of the padding. All values in dict mode are written as base64 encoded string.

password: The password for encryption/decryption.

key_size: The size of the key. Can be 16, 24 or 32 (Default: 32).

salt_marker: The salt marker with max. length of 6 bytes (Default: $).

kdf_iterations: The number of iterations of the hash function to derive the key (Default: 1000).

hashmod: The hash method to use (Default: sha256).

mac: The mac module to use (Default: hmac).

Parameters:

password (str) – The password for encryption/decryption.
key_size (int) – The size of the key. Can be 16, 24 or 32 (Default: 32).
salt_marker (bytes) – The salt marker with max. length of 6 bytes (Default: $).
kdf_iterations (int) – The number of iterations of the hash function to derive the key (Default: 1000).
hashmod – The hash method to use (Default: sha256).
mac – The mac module to use (Default: hmac).

Raises:

ValueError – If salt_marker is not one to six bytes long.
ValueError – If kdf_iterations is greater than 65535.
TypeError – If type of salt_marker is not bytes.

from_bytes(data)[source]

Decrypts data previously encrypted with AESCipher.to_bytes().

Parameters:: data (bytes) – The encrypted data in bytes style.
Return type:: str
Returns:: The decrypted data.

from_dict(data)[source]

Decrypts data previously encrypted with AESCipher.to_dict().

Parameters:: data (dict[str, str]) – The encrypted data in json style.
Return type:: str
Returns:: The decrypted data.

from_file(filename, encryption='json')[source]

Loads and decrypts data from given file.

Parameters:

filename (Path) – The name of the file to load the data from.
encryption (str) – The encryption style which where used. Can be json or bytes (Default: json).

Return type:

str

Returns:

The decrypted data.

Raises:

ValueError – If encryption is not json or bytes.

to_bytes(data)[source]

Encrypts data in bytes style.

The output bytes contains the (packed) salt, iv and ciphertext.

Parameters:: data (str) – The data to encrypt.
Return type:: bytes
Returns:: The encrypted data in dict style.

to_dict(data)[source]

Encrypts data in dict style.

The output dict contains the base64 encoded (packed) salt, iv and ciphertext key/value pairs and an info key/value pair with additional encryption information.

Parameters:: data (str) – The data to encrypt.
Return type:: dict[str, str]
Returns:: The encrypted data in dict style.

to_file(data, filename, encryption='json', indent=4)[source]

Encrypts and saves data to given file.

Parameters:

data (str) – The data to encrypt.
filename (Path) – The name of the file to save the data to.
encryption (str) – The encryption style to use. Can be json or bytes (Default: json).
indent (int) – The indention level when saving in json style (Default: 4).

Raises:

ValueError – If encryption is not json or bytes.

Return type:

None

audible.aescipher.aes_cbc_decrypt(key, iv, encrypted_data, padding='default')[source]

Decrypts data encrypted in cipher block chaining mode of operation.

Parameters:

key (bytes) – The AES key used at encryption.
iv (bytes) – The initialization vector used at encryption.
encrypted_data (bytes) – The encrypted data to decrypt.
padding (str) – Can be default or none (Default: default)

Return type:

str

Returns:

The decrypted data.

audible.aescipher.aes_cbc_encrypt(key, iv, data, padding='default')[source]

Encrypts data in cipher block chaining mode of operation.

Parameters:

key (bytes) – The AES key.
iv (bytes) – The initialization vector.
data (str) – The data to encrypt.
padding (str) – Can be default or none (Default: default)

Return type:

bytes

Returns:

The encrypted data.

audible.aescipher.create_salt(salt_marker, kdf_iterations)[source]

Creates the header and salt for the derive_from_pbkdf2() function.

The header consist of the number of KDF iterations encoded as a big-endian word bytes wrapped by salt_marker on both sides. The random salt has a length of 16 bytes (the AES block size) minus the length of the salt header.

Parameters:

salt_marker (bytes)
kdf_iterations (int)

Return type:

tuple[bytes, bytes]

audible.aescipher.decrypt_voucher_from_licenserequest(auth, license_response)[source]

Decrypt the voucher from license request response.

Parameters:

auth (Authenticator) – The Authenticator.
license_response (dict[str, Any]) – The response content from a POST /1.0/content/(string:asin)/licenserequest request.

Return type:

dict[str, Any]

Returns:

The decrypted license voucher with needed key and iv.

Raises:

Exception – If device info or customer info data is missing.

Note

A device registration is needed to use the auth instance for a license request and to obtain the needed device data

audible.aescipher.derive_from_pbkdf2(password, *, key_size, salt, kdf_iterations, hashmod, mac)[source]

Creates an AES key with the PBKDF2 key derivation class.

Parameters:

password (str)
key_size (int)
salt (bytes)
kdf_iterations (int)

Return type:

bytes

audible.aescipher.detect_file_encryption(filename)[source]

Detect the encryption format from an authentication file.

Parameters:: filename (Path) – The name for the authentication file.
Return type:: Optional[Literal[False, 'json', 'bytes']]
Returns:: False if file is not encrypted otherwise the encryption format.

audible.aescipher.pack_salt(header, salt)[source]

Combines the header and salt created by create_salt() function.

Parameters:

header (bytes)
salt (bytes)

Return type:

bytes

audible.aescipher.remove_file_encryption(source, target, password, **kwargs)[source]

Removes the encryption from an authentication file.

Please try to load the authentication file with audible.Authenticator.from_file() and save the authentication data as a unencrypted file first. Use this function as fallback if you ran into any error.

Parameters:

source (str | Path) – The encrypted authentication file.
target (str | Path) – The filename for the decrypted file.
password (str) – The password for the encrypted authentication file.
**kwargs (Any) – keyword args supported by AESCipher

Raises:

ValueError – If source is not encrypted.

Return type:

None

audible.aescipher.unpack_salt(packed_salt, salt_marker)[source]

Unpack salt and kdf_iterations from previous created and packed salt.

Parameters:

packed_salt (bytes)
salt_marker (bytes)

Return type:

tuple[bytes, int]

audible.auth module

class audible.auth.Authenticator[source]

Bases: Auth

Audible Authenticator class.

Note

A new class instance have to be instantiated with Authenticator.from_login() or Authenticator.from_file().

Added in version v0.8: The with_username attribute.

Note

Auth data saved with v0.8 or later can not be loaded with versions less than v0.8! If an auth file for a pre-Amazon account (with_username=True) was created with v0.7.1 or v0.7.2 set auth.with_username to True and save the data again. After this deregistration, refreshing access tokens and requesting cookies for another domain will work for pre-Amazon accounts.

access_token: str | None = None

property access_token_expired: bool

property access_token_expires: timedelta

activation_bytes: str | None = None

adp_token: str | None = None

auth_flow(request)[source]

Auth flow to be executed on every request by httpx.

Parameters:: request (Request) – The request made by httpx.
Yields:: The next request
Raises:: AuthFlowError – If no auth flow is available.
Return type:: Generator[Request, Response, None]

property available_auth_modes: list[str]

crypter: AESCipher | None = None

customer_info: dict[str, Any] | None = None

deregister_device(deregister_all=False)[source]

Parameters:: deregister_all (bool)
Return type:: Any

device_info: dict[str, Any] | None = None

device_private_key: str | None = None

encryption: str | bool | None = None

expires: float | None = None

filename: Optional[Path] = None

classmethod from_dict(data, locale=None)[source]

Instantiate an Authenticator from authentication file.

Added in version v0.7.1.

Parameters:

data (dict[str, Any]) – A dictionary with the authentication data
locale (Union[str, Locale, None]) – The country code of the Audible marketplace to interact with. If None the country code from file is used.

Return type:

Authenticator

Returns:

A new Authenticator instance.

classmethod from_file(filename, password=None, locale=None, encryption=None, **kwargs)[source]

Instantiate an Authenticator from authentication file.

Added in version v0.5.0.

Parameters:

filename (Union[str, Path]) – The name of the file with the authentication data.
password (str | None) – The password of the authentication file.
locale (Union[str, Locale, None]) – The country code of the Audible marketplace to interact with. If None the country code from file is used.
encryption (bool | str | None) – The encryption style to use. Can be json or bytes. If None, encryption will be auto detected.
**kwargs (Any) – Keyword arguments are passed to the AESCipher class. See below.

Keyword Arguments:

key_size (int, Optional)
salt_marker (Optional[bytes])
kdf_iterations (int, optional)
hashmod
mac

Return type:

Authenticator

Returns:

A new Authenticator instance.

Raises:

FileEncryptionError – If file ist encrypted without providing a password

classmethod from_login(username, password, locale, serial=None, with_username=False, captcha_callback=None, otp_callback=None, cvf_callback=None, approval_callback=None)[source]

Instantiate a new Authenticator with authentication data from login.

Added in version v0.5.0.

Added in version v0.5.4: The serial argument The with_username argument

Parameters:

username (str) – The Amazon email address.
password (str) – The Amazon password.
locale (Union[str, Locale]) – The country_code or audible.localization.Locale instance for the marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
captcha_callback (Callable[[str], str] | None) – A custom callback to handle captcha requests during login.
otp_callback (Callable[[], str] | None) – A custom callback to handle one-time password requests during login.
cvf_callback (Callable[[], str] | None) – A custom callback to handle verify code requests during login.
approval_callback (Callable[[], Any] | None) – A custom Callable for handling approval alerts.

Return type:

Authenticator

Returns:

An Authenticator instance.

classmethod from_login_external(locale, serial=None, with_username=False, login_url_callback=None)[source]

Instantiate a new Authenticator from login with external browser.

Added in version v0.5.1.

Added in version v0.5.4: The serial argument The with_username argument

Parameters:

locale (Union[str, Locale]) – The country_code or audible.localization.Locale instance for the marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
login_url_callback (Callable[[str], str] | None) – A custom Callable for handling login with external browsers.

Return type:

Authenticator

Returns:

An Authenticator instance.

get_activation_bytes(filename=None, extract=True, force_refresh=False)[source]

Get Activation bytes from Audible.

Parameters:

filename (Union[Path, str, None]) – [Optional] filename to save the activation blob
extract (Literal[True, False]) – [Optional] if True, returns the extracted activation bytes otherwise the whole activation blob
force_refresh (bool) – [Optional] if True, existing activation bytes in auth file will be ignored and new activation bytes will be requested from server.

Return type:

str | bytes

Returns:

The activation bytes

Added in version 0.5.1: The force_refresh argument. Fetched activation bytes are now stored to Authententicator.activation_bytes.

locale: Optional[Locale] = None

refresh_access_token(force=False)[source]

Parameters:: force (bool)
Return type:: None

refresh_token: str | None = None

requires_request_body: bool = True

set_website_cookies_for_country(country_code)[source]

Parameters:: country_code (str)
Return type:: None

sign_request(request)[source]

Sign a request.

Deprecated since version 0.5.0: Use self._apply_signing_auth_flow() instead.

Parameters:: request (Request)
Return type:: None

store_authentication_cookie: dict[str, Any] | None = None

to_dict()[source]: Returns authentication data as dict. :rtype: dict[str, Any]

Added in version 0.7.1.

Added in version v0.8: The returned dict now contains the with_username attribute

to_file(filename=None, password=None, encryption='default', indent=4, set_default=True, **kwargs)[source]

Save authentication data to file.

Added in version 0.5.1: Save activation bytes to auth file

Added in version v0.8: The saved file now contains the with_username attribute

Parameters:

filename (Union[Path, str, None])
password (str | None)
encryption (bool | str)
indent (int)
set_default (bool)
kwargs (Any)

Return type:

None

user_profile()[source]

Return type:: dict[str, Any]

website_cookies: dict[str, Any] | None = None

with_username: bool | None = False

audible.auth.refresh_access_token(refresh_token, domain, with_username=False)[source]

Refreshes an access token.

Parameters:

refresh_token (str) – The refresh token obtained after a device registration.
domain (str) – The top level domain of the requested Amazon server (e.g. com).
with_username (bool) – If True uses audible domain instead of amazon.

Return type:

dict[str, Any]

Returns:

A dict with the new access token and expiration timestamp.

Note

The new access token is valid for 60 minutes.

Added in version v0.8: The with_username argument

audible.auth.refresh_website_cookies(refresh_token, domain, cookies_domain, with_username=False)[source]

Fetches website cookies for a specific domain.

Parameters:

refresh_token (str) – The refresh token obtained after a device registration.
domain (str) – The top level domain of the requested Amazon server (e.g. com, de, fr).
cookies_domain (str) – The top level domain scope for the cookies (e.g. com, de, fr).
with_username (bool) – If True uses audible domain instead of amazon.

Return type:

dict[str, str]

Returns:

The requested cookies for the Amazon and Audible website for the given cookies_domain scope.

Added in version v0.8: The with_username argument

audible.auth.sign_request(method, path, body, adp_token, private_key)[source]

Helper function who creates signed headers for http requests.

Parameters:

path (str) – The requested http url path and query.
method (str) – The http request method (GET, POST, DELETE, …).
body (bytes) – The http message body.
adp_token (str) – The adp token obtained after a device registration.
private_key (str) – The rsa key obtained after device registration.

Return type:

dict[str, str]

Returns:

A dict with the signed headers.

audible.auth.user_profile(access_token, domain)[source]

Returns user profile from Amazon.

Parameters:

access_token (str) – The valid access token for authentication.
domain (str) – The top level domain of the requested Amazon server (e.g. com, de, fr).

Return type:

dict[str, Any]

Returns:

The Amazon user profile for the authenticated user.

Raises:

Exception – If the user profile is malformed

audible.auth.user_profile_audible(access_token, domain)[source]

Returns user profile from Audible.

Parameters:

access_token (str) – The valid access token for authentication.
domain (str) – The top level domain of the requested Audible server (e.g. com, de, fr).

Return type:

dict[str, Any]

Returns:

The Audible user profile for the authenticated user.

Raises:

Exception – If the user profile is malformed

audible.client module

class audible.client.AsyncClient(auth, country_code=None, headers=None, timeout=10, response_callback=None, **session_kwargs)[source]

Bases: BaseClient[AsyncClient]

Parameters:

auth (Authenticator)
country_code (str | None)
headers (Union[Headers, Mapping[str, str], Mapping[bytes, bytes], Sequence[Tuple[str, str]], Sequence[Tuple[bytes, bytes]], None])
timeout (int)
response_callback (Callable[[Response], Any] | None)
session_kwargs (Any)

async close()[source]

Return type:: None

async delete(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async get(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async post(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

async put(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

class audible.client.BaseClient(auth, country_code=None, headers=None, timeout=10, response_callback=None, **session_kwargs)[source]

Bases: Generic[ClientT]

Parameters:

auth (Authenticator)
country_code (str | None)
headers (Union[Headers, Mapping[str, str], Mapping[bytes, bytes], Sequence[Tuple[str, str]], Sequence[Tuple[bytes, bytes]], None])
timeout (int)
response_callback (Callable[[Response], Any] | None)
session_kwargs (Any)

property auth: Authenticator

abstract delete(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

abstract get(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

get_user_profile()[source]

Return type:: dict[str, Any]

property marketplace: str

abstract post(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

abstract put(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

raw_request(method, url, *, stream=False, apply_auth_flow=False, apply_cookies=False, **kwargs)[source]

Sends a raw request with the underlying httpx Client.

This method ignores a set api_url and allows send request to custom hosts. The raw httpx response will be returned.

Parameters:

method (str) – The http request method.
url (str) – The url to make requests to.
stream (Literal[True, False]) – If True, streams the response
apply_auth_flow (bool) – If True, the Authenticator.auth_flow() will be applied to the request.
apply_cookies (bool) – If True, website cookies from Authenticator.website_cookies will be added to request headers.
**kwargs (Any) – keyword args supported by httpx.AsyncClient.stream, httpx.Client.stream, httpx.AsyncClient.request, httpx.Client.request.

Return type:

Response | Coroutine[Any, Any, Response] | AbstractContextManager[Response] | AbstractAsyncContextManager[Response]

Returns:

An unprepared httpx Response object.

Added in version v0.5.1.

switch_marketplace(country_code)[source]

Parameters:: country_code (str)
Return type:: None

switch_user(auth, switch_to_default_marketplace=False)[source]

Parameters:

auth (Authenticator)
switch_to_default_marketplace (bool)

Return type:

None

property user_name: str

class audible.client.Client(auth, country_code=None, headers=None, timeout=10, response_callback=None, **session_kwargs)[source]

Bases: BaseClient[Client]

Parameters:

auth (Authenticator)
country_code (str | None)
headers (Union[Headers, Mapping[str, str], Mapping[bytes, bytes], Sequence[Tuple[str, str]], Sequence[Tuple[bytes, bytes]], None])
timeout (int)
response_callback (Callable[[Response], Any] | None)
session_kwargs (Any)

close()[source]

Return type:: None

delete(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

get(path, response_callback=None, **kwargs)[source]

Parameters:

path (str)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

post(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

put(path, body, response_callback=None, **kwargs)[source]

Parameters:

path (str)
body (Any)
response_callback (Callable[[Response], Any] | None)
kwargs (dict[str, Any])

Return type:

Any

audible.client.convert_response_content(resp)[source]

Parameters:: resp (Response)
Return type:: Any

audible.client.default_response_callback(resp)[source]

Parameters:: resp (Response)
Return type:: Any

audible.client.raise_for_status(resp)[source]

Parameters:: resp (Response)
Return type:: None

audible.exceptions module

exception audible.exceptions.AudibleError[source]

Bases: Exception

Base class for all errors.

exception audible.exceptions.AuthFlowError[source]

Bases: AudibleError

Raised if no auth method available.

exception audible.exceptions.BadRequest(resp, data)[source]

Bases: StatusError

Raised when status code 400 is returned.

Typically, when at least one search parameter was not provided.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.FileEncryptionError[source]

Bases: AudibleError

Raised if something is wrong with file encryption.

exception audible.exceptions.NetworkError[source]

Bases: RequestError

Raised if there is an issue with the network (i.e. requests.ConnectionError).

exception audible.exceptions.NoRefreshToken[source]

Bases: AudibleError

Raised if refresh token is needed but not provided.

exception audible.exceptions.NotFoundError(resp, data)[source]

Bases: StatusError

Raised if no result is found.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.NotResponding[source]

Bases: RequestError

Raised if the API request timed out.

exception audible.exceptions.RatelimitError(resp, data)[source]

Bases: StatusError

Raised if ratelimit is hit.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.RequestError[source]

Bases: AudibleError

Base class for all request errors.

exception audible.exceptions.ServerError(resp, data)[source]

Bases: StatusError

Raised if the api service is having issues.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.StatusError(resp, data)[source]

Bases: RequestError

Base class for all errors except NotResponding and RatelimitDetectedError.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.Unauthorized(resp, data)[source]

Bases: StatusError

Raised if you passed invalid credentials.

Parameters:

resp (Response)
data (Any)

exception audible.exceptions.UnexpectedError(resp, data)[source]

Bases: StatusError

Raised if the error was not caught.

Parameters:

resp (Response)
data (Any)

audible.localization module

class audible.localization.Locale(country_code=None, domain=None, market_place_id=None)[source]

Bases: object

Adjustments for the different marketplaces who are provided by Audible.

You can try to autodetect_locale if your marketplace is not in templates`.

Parameters:

country_code (str | None)
domain (str | None)
market_place_id (str | None)

property country_code: str

property domain: str

property market_place_id: str

to_dict()[source]

Return type:: dict[str, str]

audible.localization.autodetect_locale(domain)[source]

Try to automatically detect correct settings for marketplace.

Needs the top level domain of the audible page to continue with (e.g. co.uk, co.jp) and returns results found.

Parameters:

domain (str) – The top level domain for the Audible marketplace to detect settings for (e.g. com).

Return type:

dict[str, str]

Returns:

The settings for the found Audible marketplace.

Raises:

ConnectError – If site does not exist or network error raises.
Exception – If marketplace or country code can’t be found.

audible.localization.search_template(key, value)[source]

Parameters:

key (str)
value (str)

Return type:

dict[str, str] | None

audible.login module

audible.login.build_client_id(serial)[source]

Parameters:: serial (str)
Return type:: str

audible.login.build_device_serial()[source]

Return type:: str

audible.login.build_init_cookies()[source]

Build initial cookies to prevent captcha in most cases.

Return type:: dict[str, str]

audible.login.build_oauth_url(country_code, domain, market_place_id, code_verifier, serial=None, with_username=False)[source]

Builds the url to login to Amazon as an Audible device.

Parameters:

country_code (str)
domain (str)
market_place_id (str)
code_verifier (bytes)
serial (str | None)
with_username (bool)

Return type:

tuple[str, str]

audible.login.check_for_approval_alert(soup)[source]

Checks a Amazon login page for an approval alert.

Parameters:: soup (BeautifulSoup)
Return type:: bool

audible.login.check_for_captcha(soup)[source]

Checks a Amazon login page for a captcha form.

Parameters:: soup (BeautifulSoup)
Return type:: bool

audible.login.check_for_choice_mfa(soup)[source]

Checks a Amazon login page for a MFA selection form.

Parameters:: soup (BeautifulSoup)
Return type:: bool

audible.login.check_for_cvf(soup)[source]

Parameters:: soup (BeautifulSoup)
Return type:: bool

audible.login.check_for_mfa(soup)[source]

Checks a Amazon login page for a multi-factor authentication form.

Parameters:: soup (BeautifulSoup)
Return type:: bool

audible.login.create_code_verifier(length=32)[source]

Parameters:: length (int)
Return type:: bytes

audible.login.create_s256_code_challenge(verifier)[source]

Parameters:: verifier (bytes)
Return type:: bytes

audible.login.default_approval_alert_callback()[source]

Helper function for handling approval alerts.

Return type:: None

audible.login.default_captcha_callback(captcha_url)[source]

Helper function for handling captcha.

Parameters:: captcha_url (str)
Return type:: str

audible.login.default_cvf_callback()[source]

Helper function for handling cvf verifys.

Amazon sends a verify code via Mail or SMS.

Return type:: str

audible.login.default_login_url_callback(url)[source]

Helper function for login with external browsers.

Parameters:: url (str)
Return type:: str

audible.login.default_otp_callback()[source]

Helper function for handling 2-factor authentication.

Return type:: str

audible.login.external_login(country_code, domain, market_place_id, serial=None, with_username=False, login_url_callback=None)[source]

Gives the url to login with external browser and prompt for result.

Note

If you are using MacOS and have trouble insert the login result url simply import the readline module in your script. See #34.

Parameters:

country_code (str) – The country code for the Audible marketplace to login.
domain (str) – The top level domain for the Audible marketplace to login.
market_place_id (str) – The id for the Audible marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
login_url_callback (Callable[[str], str] | None) – A custom Callable for handling login with external browsers. If None default_login_url_callback() is used.

Return type:

dict[str, Any]

Returns:

An authorization_code, a code_verifier and the device serial from the authorized Client.

audible.login.extract_captcha_url(soup)[source]

Returns the captcha url from a Amazon login page.

Parameters:: soup (BeautifulSoup)
Return type:: str

audible.login.extract_code_from_url(url)[source]

Extracts the access token from url query after login.

Parameters:: url (URL)
Return type:: str

audible.login.get_inputs_from_soup(soup, search_field=None)[source]

Extracts hidden form input fields from a Amazon login page.

Parameters:

soup (BeautifulSoup)
search_field (dict[str, str] | None)

Return type:

dict[str, str]

audible.login.get_next_action_from_soup(soup, search_field=None)[source]

Parameters:

soup (BeautifulSoup)
search_field (dict[str, str] | None)

Return type:

tuple[str, str]

audible.login.get_soup(resp, log_errors=True)[source]

Parameters:

resp (Response)
log_errors (bool)

Return type:

BeautifulSoup

audible.login.is_valid_email(obj)[source]

Parameters:: obj (str)
Return type:: bool

audible.login.login(username, password, country_code, domain, market_place_id, serial=None, with_username=False, captcha_callback=None, otp_callback=None, cvf_callback=None, approval_callback=None)[source]

Login to Audible by simulating an Audible App for iOS.

Parameters:

username (str) – The Amazon email address.
password (str) – The Amazon password.
country_code (str) – The country code for the Audible marketplace to login.
domain (str) – domain: The top level domain for the Audible marketplace to login.
market_place_id (str) – The id for the Audible marketplace to login.
serial (str | None) – The device serial. If None a custom one will be created.
with_username (bool) – If True login with Audible username instead of Amazon account.
captcha_callback (Callable[[str], str] | None) – A custom Callable for handling captcha requests. If None default_captcha_callback() is used.
otp_callback (Callable[[], str] | None) – A custom Callable for providing one-time passwords. If None default_otp_callback() is used.
cvf_callback (Callable[[], str] | None) – A custom Callable for providing the answer for a CVF code. If None default_cvf_callback() is used.
approval_callback (Callable[[], Any] | None) – A custom Callable for handling approval alerts. If None default_approval_alert_callback() is used.

Return type:

dict[str, Any]

Returns:

An authorization_code, a code_verifier and the device serial from the authorized Client.

Raises:

Exception – If authorization_code is not in response url.

audible.login.playwright_external_login_url_callback(url)[source]

Helper function for login using playwright.

Parameters:: url (str)
Return type:: str

audible.metadata module

class audible.metadata.XXTEA(key)[source]

Bases: object

XXTEA wrapper class.

Easy to use and compatible (by duck typing) with the Blowfish class.

Note

Partial copied from https://github.com/andersekbom/prycut and ported from PY2 to PY3

Parameters:: key (str | bytes)

decrypt(data)[source]

Decrypts and returns a block of data.

Parameters:: data (str | bytes)
Return type:: bytes

encrypt(data)[source]

Encrypts and returns a block of data.

Parameters:: data (str | bytes)
Return type:: bytes

exception audible.metadata.XXTEAException[source]: Bases: Exception

audible.metadata.decrypt_metadata(encrypted_metadata)[source]

Decrypts metadata for testing purposes only.

Parameters:: encrypted_metadata (str)
Return type:: str

audible.metadata.encrypt_metadata(metadata)[source]

Encrypts metadata to be used to log in to Amazon.

Parameters:: metadata (str)
Return type:: str

audible.metadata.meta_audible_app(user_agent, oauth_url)[source]

Returns json-formatted metadata to simulate sign-in from iOS audible app.

Parameters:

user_agent (str)
oauth_url (str)

Return type:

str

audible.metadata.now_to_unix_ms()[source]

Return type:: int

audible.metadata.raw_xxtea(v, n, k)[source]

Parameters:

v (list[int])
n (int)
k (list[int] | tuple[int, ...])

Return type:

int

audible.register module

audible.register.deregister(access_token, domain, deregister_all=False, with_username=False)[source]

Deregister a previous registered Audible device.

Note

Except of the access_token, all authentication data will lose validation immediately.

Parameters:

access_token (str) – The access token from the previous registered device which you want to deregister.
domain (str) – The top level domain of the requested Amazon server (e.g. com).
deregister_all (bool) – If True, deregister all Audible devices on Amazon.
with_username (bool) – If True uses audible domain instead of amazon.

Return type:

Any

Returns:

The response for the deregister request. Contains errors, if some occurs.

Raises:

Exception – If response status code is not 200.

Added in version v0.8: The with_username argument

audible.register.register(authorization_code, code_verifier, domain, serial, with_username=False)[source]

Registers a dummy Audible device.

Parameters:

authorization_code (str) – The code given after a successful authorization
code_verifier (bytes) – The verifier code from authorization
domain (str) – The top level domain of the requested Amazon server (e.g. com).
serial (str) – The device serial
with_username (bool) – If True uses audible domain instead of amazon.

Return type:

dict[str, Any]

Returns:

Additional authentication data needed for access Audible API.

Raises:

Exception – If response status code is not 200.

Added in version v0.7.1: The with_username argument

audible.utils module

class audible.utils.ElapsedTime[source]: Bases: object

audible.utils.test_convert(key, value)[source]

Helper function to check and convert values for specific keys.

Parameters:

key (str)
value (Any)

Return type:

Any