V0.8.0dev (#89)

* fully support pre-Amazon accounts

The `Authenticator` now holds the `with_username` attribute and other
stuff for pre-Amazon accounts.

Auth data saved with v0.8 or later can not be loaded with versions
less than v0.8!
If an auth file for an 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.

* setdefault `with_username` to `False` when instantiate an Authenticator

* rework setdefault `with_username`

* Update client.py

- `Client` and `AsynClient` now accepts session kwargs which are bypassed to the underlying httpx Client
- rename (and rework) `Client._split_kwargs` to `Client._prepare_params`

* Update CHANGELOG.md

* Add `response_callback` to `Client` and `AsyncClient`

This allows to set a custom response callback like:

```python
def custom_response_callback(resp):
    return resp
```

This returns the unprepared `httpx.Response` object for further purposes (e.g. accessing respopnse headers).

* remove trailing newlines

* Update activation_bytes.py

* remove whitspaces

* work on docs and docstring

* Update CHANGELOG.md

* Create example to get and analyse listening statistics

Include an example that authenticates using the browser and goes on to extract aggregate per month listening time since account creation (currently hardcoded to 2013) to the current month. 

Then the script uses time-series analysis to find trends and seasonalities in the listening pattern.

* Create download_bookmarks.py

Create an example to download all bookmarks for all books in the library and store them in a json file 'books.json'.

* rework `_prepare_api_path` method of client classes

- absolute url paths are passed through without preparation
- query params for a given url will be keep intact

* Update CHANGELOG.md

Co-authored-by: Botty Dimanov <bottydim@users.noreply.github.com>

Author: mkb79

.github/workflows/pypi-publish-test.yml

@@ -7,7 +7,7 @@ jobs:
   build-n-publish:
     name: Build and publish Audible to TestPyPI
     runs-on: ubuntu-18.04
-    
+
     steps:
       - uses: actions/checkout@master
       - name: Set up Python 3.9

.github/workflows/pypi-publish.yml

@@ -7,7 +7,7 @@ jobs:
   build-n-publish:
     name: Build and publish Audible to PyPI
     runs-on: ubuntu-18.04
-    
+
     steps:
       - uses: actions/checkout@master
       - name: Set up Python 3.9

CHANGELOG.md

@@ -6,7 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased
 
--
+### Added
+
+- full support of pre-Amazon accounts (e.g. refresh access token, deregister device)
+- `Client` and `AsynClient` now accepts session kwargs which are bypassed to the underlying httpx Client
+- a `respone_callback` can now be set to `Client` and `AsyncClient` class to allow custom preparation of response output
+- An absolut url (e.g. https://cde-ta-g7g.amazon.com/FionaCDEServiceEngine/sidecar) can now be passed to a client `get`, `post`, `delete` and `put` method as the `path` arg. So in most cases the client `raw_request` method is not needed anymore.
+
+### Changed
+
+- rename (and rework) `Client._split_kwargs` to `Client._prepare_params`
 
 ## [0.7.2] - 2022-03-27
 

docs/source/auth/authentication.rst

@@ -25,7 +25,9 @@ Sign request method
 With the sign request method you gain unrestricted access to the Audible API.
 To use this method, you need the RSA private key and the adp_token from a
 *device registration*. This method is used by the Audible apps for iOS and
-Android too.
+Android too. A device registration is done automatically with
+:meth:`audible.Authenticator.from_login` or
+:meth:`audible.Authenticator.from_login_external`
 
 Request signing is fairly straight-forward and uses a signed SHA256 digest.
 Headers look like::
@@ -37,8 +39,8 @@ Headers look like::
 Bearer method
 -------------
 
-API requests with the bearer method are restricted. Some API call like the
-:http:post:`/1.0/content/(string:asin)/licenserequest` doesn't work. To use
+API requests with the bearer method have some restrictions. Some API call, like
+the :http:post:`/1.0/content/(string:asin)/licenserequest`, doesn't work. To use
 the bearer method you need an access token and a client id. You receive the
 token after a device registration. Which values are valid for the client-id 
 is unknown but 0 does work. An access token expires after 60 minutes. It 

docs/source/auth/authorization.rst

@@ -148,7 +148,7 @@ To handle the login with a external browser or program logic you can do the foll
    auth = audible.Authenticator.from_login_external(locale=COUNTRY_CODE)
 
 By default, this code print out the login url for the selected country code. Now you have
-to copy and paste this code into a webbrowser (or a custom program) and authorize yourself. 
+to copy and paste this code into a web browser (or a custom program) and authorize yourself.
 You have to enter your credentials two times (because of missing init cookies). 
 On first time, the password can be a random one.
 On second time, you have to solve a captcha before you can submit the login form with your 
@@ -158,6 +158,11 @@ Please copy the url from the address bar from your browser and paste the url to
 field of the python code. This url looks like 
 "https://www.amazon.{domain}/ap/maplanding?...&openid.oa2.authorization_code=..."
 
+.. note::
+   If you have `playwright <https://pypi.org/project/playwright/>`_ installed and
+   use the default ``login_url_callback``, a new browser is opened, where you can
+   authorize to your account,
+
 .. note::
 
    If you are using MacOS and have trouble insert the login result url, simply import the 

docs/source/auth/register.rst

@@ -17,6 +17,8 @@ To authorize and register a new device you can do::
        with_username=False,
    )
 
+This will authorize you to your account and register an Audible device.
+
 .. important::
 
    Every device registration will be shown on the Amazon devices list. So only

docs/source/intro/getting_started.rst

@@ -13,10 +13,10 @@ First Audible device
 ====================
 
 Before you can communicate with the non-publicly Audible Api, you need to
-authorize (login) yourself to Audible with your Audible username or Amazon
-account and register a new "virtual" Audible device. Please make sure to
-select the correct Audible marketplace. An overview about all known Audible
-marketplaces and associated country codes be found at :ref:`country_codes`.
+authorize (login) yourself to Amazon (or Audible) and register a new "virtual"
+Audible device. Please make sure to select the correct Audible marketplace.
+An overview about all known Audible marketplaces and associated country codes
+be found at :ref:`country_codes`.
 
 .. code-block::
 
@@ -30,7 +30,7 @@ marketplaces and associated country codes be found at :ref:`country_codes`.
        with_username=False
    )
    
-   # Save credendtials to file
+   # Save credentials to file
    auth.to_file(FILENAME)
 
 .. important::
@@ -42,11 +42,12 @@ marketplaces and associated country codes be found at :ref:`country_codes`.
 .. note::
 
    If you have activated 2-factor-authentication for your Amazon account, you
-   can append the current OTP to the password.
+   can append the current OTP to your password. This eliminates the need for a
+   new OTP prompt.
 
 .. note::
 
-   Set `with_username=True` to login with a pre-Amazon account (for US, UK or
+   Set `with_username=True` to login with your pre-Amazon account (for US, UK or
    DE marketplace only).
 
 .. note::
@@ -76,8 +77,8 @@ your first API call. To fetch and print out all books from your Audible library
 
 .. note::
 
-   The information provided by the API depends on the requested `response_groups`.
-   The response from the example above are very minimized. Please take a look at
+   The information returned by the API depends on the requested `response_groups`.
+   The response for the example above are very minimized. Please take a look at
    :http:get:`/1.0/library` for all known `response_groups` and other parameter
    for the library endpoint.
 

docs/source/intro/install.rst

@@ -30,7 +30,7 @@ development version::
     cd Audible
     pip install .
 
-Alternatively, install directly from the GitHub repository::
+Alternatively, install it directly from the GitHub repository::
 
     pip install git+https://github.com/mkb79/audible.git
 

docs/source/misc/advanced.rst

@@ -7,24 +7,36 @@ Client classes
 
 Here are some information about the ``Client`` and  the ``AsyncClient`` classes.
 
-Both client classes have the following methods to send requests 
+Instantiate a client
+--------------------
+
+A client needs at least an :class:`audible.Authenticator` at instantiation. The
+following args and kwargs can be passed to the client instantiation:
+
+* country_code (overrides the country code set in :class:`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
-- patch
-
-Make API requests
------------------
+- 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 separat keyword argument or you can
+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)
@@ -52,6 +64,27 @@ and output them as a Python dict.
 
    For all known API endpoints take a look at :ref:`api_endpoints`.
 
+Client responses
+----------------
+
+.. versionadded:: 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 :func:`audible.client.raise_for_status` and try to convert
+the response with :func:`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
 -----------------------
 

docs/source/misc/load_save.rst

@@ -80,11 +80,16 @@ The following data will be stored:
 - device_info data
 - customer_info data
 - activation_bytes
+- with_username (``True`` for pre-Amazon accounts else ``False``)
 
 .. versionadded:: 0.5.1
 
    Stores ``activation_bytes`` to file (if they where fetched before).
 
+.. versionadded:: v0.8.0
+
+   The ``with_username`` value
+
 Advanced use of encryption/decryption
 =====================================
 
@@ -135,3 +140,4 @@ unencrypted. If the `Authenticator` can't load your data, you can try::
        decrypted_file=FILENAME,
        password=PASSWORD_FOR_ENCRYPTED_FILE
    )
+