Advanced Usage
Client classes
Here are some information about the Client
and the AsyncClient
classes.
Instantiate a client
A client needs at least an audible.Authenticator
at instantiation. The
following args and kwargs can be passed to the client instantiation:
country_code (overrides the country code set in
audible.Authenticator
)headers (will be bypassed to the underlying httpx client)
timeout (will be bypassed to the underlying httpx client)
response_callback (custom response preparation - read more below)
all other kwargs (will be bypassed to the underlying httpx client)
Make API requests
Both client classes have the following methods to send requests to the external API:
get
post
delete
put
The external Audible API offers currently two API versions, 0.0 and 1.0. The Client use the 1.0 by default. So both terms are equal:
resp = client.get("library")
resp = client.get("1.0/library")
Each query parameter can be written as a separate keyword argument or you can merge them as a dict to the params keyword. So both terms are equal:
resp = client.get("library", response_groups="...", num_results=20)
resp = client.get(
"library",
params={
"response_groups"="...",
"num_results"=20
}
)
The external Audible API awaits a request body in JSON format. You have to provide the body as a dict to the Client. The Client converts and sends them in JSON style to the API. You can send them like so:
resp = client.post(
"wishlist",
body={"asin": ASIN_OF_BOOK_TO_ADD}
)
The Audible API responses are in JSON format. The client converts them to a and output them as a Python dict.
Note
For all known API endpoints take a look at API Endpoints.
Client responses
Added in version v0.8.0: The response_callback
kwarg to client __init__, get, post, delete and put methods.
By default requesting the API with the client get, post, delete and put methods
will call audible.client.raise_for_status()
and try to convert
the response with audible.client.convert_response_content()
to a Python dict,
which is finally returned.
If you want to implement your own response preparation, you can do:
def own_response_callback(resp):
return resp
client = audible.Client(auth=..., response_callback=own_response_callback)
This will return the unprepared response (include headers).
Show/Change Marketplace
The currently selected marketplace can be shown with:
client.marketplace
The marketplace can be changed with:
client.switch_marketplace(COUNTRY_CODE)
Username/Userprofile
To get the profile for the user, which authentication data are used you can do this:
user_profile = client.get_user_profile()
# or from an Authenticator instance
auth.refresh_access_token()
user_profile = auth.user_profile()
To get the username only:
user_name = client.user_name
Switch User
If you work with multiple users you can do this:
# instantiate 1st user
auth = audible.Authenticator.from_file(FILENAME)
# instantiate 2nd user
auth2 = audible.Authenticator.from_file(FILENAME2)
# instantiate client with 1st user
client = audible.AudibleAPI(auth)
print(client.user_name)
# now change user with auth2
client.switch_user(auth2)
print(client.user_name)
# optional set default marketplace from 2nd user
client.switch_user(auth2, switch_to_default_marketplace=True)
Misc
The underlying Authenticator can be accessed via the auth attribute.
Authenticator classes
Deprecated since version v0.5.0: The LoginAuthenticator
and the FileAuthenticator
Changed in version v0.6.0.
The LoginAuthenticator
and the FileAuthenticator
are removed from the
Audible package.
Added in version v0.5.0: The Authenticator
with the classmethods from_file
and
from_login
The Authenticator.from_login()
classmethod is used to authorize
an user and then authenticate requests with the received data. The
Authenticator.from_file()
classmethod is used to load
previous saved authentication data.
With an Authenticator you can:
Save credentials to file with
auth.to_file()
Deregister a previously registered device with
auth.deregister_device()
.Refresh an access token from a previously registered device with
auth.refresh_access_token()
.Get user profile with
auth.user_profile()
. Needs a valid access token.
To check if a access token is expired you can call:
auth.access_token_expired
Or to check the time left before token expires:
auth.access_token_expires
Activation Bytes
Added in version v0.4.0: Get activation bytes
Added in version v0.5.0: the extract
param
To retrieve activation bytes an authentication Authenticator
is needed.
The Activation bytes can be obtained like so:
activation_bytes = auth.get_activation_bytes()
# the whole activation blob can fetched with
auth.get_activation_bytes(extract=False)
The activation blob can be saved to file too:
activation_bytes = auth.get_activation_bytes(FILENAME)
Attention
Please only use this for gaining full access to your own audiobooks for archiving / converson / convenience. DeDRMed audiobooks should not be uploaded to open servers, torrents, or other methods of mass distribution. No help will be given to people doing such things. Authors, retailers, and publishers all need to make a living, so that they can continue to produce audiobooks for us to hear, and enjoy. Don’t be a parasite.
PDF Url
PDF urls received by the Audible API don’t work anymore. Authentication data are missing in the provided link. As a workaround you can do:
import audible
import httpx
asin = ASIN_FROM_BOOK
auth = audible.Authenticator.from_file(...) # or Authenticator.from_login
tld = auth.locale.domain
with httpx.Client(auth=auth) as client:
resp = client.head(
f"https://www.audible.{tld}/companion-file/{asin}"
)
url = resp.url
Decrypting license
Responses from the POST /1.0/content/(string:asin)/licenserequest
endpoint contains the encrypted license (voucher).
To decrypt the license response you can do:
from audible.aescipher import decrypt_voucher_from_licenserequest
auth = YOUR_AUTH_INSTANCE
lr = RESPONSE_FROM_LICENSEREQUEST_ENPOINT
dlr = decrypt_voucher_from_licenserequest(auth, lr)
Attention
Please only use this for gaining full access to your own audiobooks for archiving / converson / convenience. DeDRMed audiobooks should not be uploaded to open servers, torrents, or other methods of mass distribution. No help will be given to people doing such things. Authors, retailers, and publishers all need to make a living, so that they can continue to produce audiobooks for us to hear, and enjoy. Don’t be a parasite.