feat(async): introduce async module

README.md

@@ -53,9 +53,9 @@ The package is published on
 
     pip install deezer-python
 
-## Basic Use
+## Basic Use (synchronous)
 
-Easily query the Deezer API from you Python code. The data returned by the Deezer
+Easily query the Deezer API from your Python code. The data returned by the Deezer
 API is mapped to python resources:
 
 ```pycon
@@ -64,8 +64,46 @@ API is mapped to python resources:
 'Monkey Business'
 ```
 
+## Async usage
+
+An asynchronous client is also available, built on top of `httpx.AsyncClient`.
+It mirrors the public API of the synchronous `deezer.Client`, but all network
+calls must be awaited and the client must be used in an async context.
+
+```python
+import asyncio
+from async_deezer import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        album = await client.get_album(680407)
+        print(album.title)
+
+
+asyncio.run(main())
+```
+
+You can work with paginated endpoints using `AsyncPaginatedList` and `async for`:
+
+```python
+from async_deezer import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        tracks = client.get_user_tracks()  # AsyncPaginatedList
+        async for track in tracks:
+            print(track.title)
+```
+
+Notes:
+
+- The async client lives in the separate `async_deezer` package inside this
+  project so it does not change the public API of `deezer-python`.
+
 Ready for more? Look at our whole [documentation](http://deezer-python.readthedocs.io/)
-on Read The Docs or have a play in pre-populated Jupyter notebook
+on Read The Docs or have a play in a pre-populated Jupyter notebook
 [on Binder](https://mybinder.org/v2/gh/browniebroke/deezer-python/main?filepath=demo.ipynb).
 
 ## Contributors

docs/usage.md

@@ -15,7 +15,66 @@ with deezer.Client() as client:
     ...
 ```
 
-This is [the recommended way to use it by `httpx`](https://www.python-httpx.org/advanced/clients/#usage, which is the library we use under the hood.
+This is [the recommended way to use it by `httpx`](https://www.python-httpx.org/advanced/clients/#usage), which is the library we use under the hood.
+
+## Async client
+
+If you are writing an asynchronous application, you can use the async client
+provided by the `async_deezer` package. It closely mirrors the public API of
+{class}`Client <deezer.client.Client>`, but:
+
+- it is built on top of {class}`httpx.AsyncClient`, and
+- methods that perform network I/O are declared as `async` and must be awaited.
+
+### First steps with the async client
+
+Instantiate and use the async client inside an async function and context
+manager:
+
+```python
+import asyncio
+
+from async_deezer import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        album = await client.get_album(680407)
+        print(album.title)
+
+
+asyncio.run(main())
+```
+
+The same recommendations from the synchronous client apply: using it as a
+context manager ensures that network resources are cleaned up properly.
+
+### Async pagination
+
+Endpoints that return multiple items, such as `get_user_tracks()` or the
+various `search*` methods, return an {class}`AsyncPaginatedList
+<async_deezer.pagination.AsyncPaginatedList>` when using the async client.
+You can iterate over it with `async for`:
+
+```python
+from async_deezer import AsyncClient
+
+
+async def main() -> None:
+    async with AsyncClient() as client:
+        tracks = client.get_user_tracks()
+        async for track in tracks:
+            print(track.title)
+```
+
+For random access into the list, use the explicit async helpers instead of
+`__getitem__`:
+
+```python
+track = await tracks.aget(0)
+first_five = await tracks.aslice(0, 5)
+total = await tracks.get_total()
+```
 
 From there, you can search for some terms:
 

src/async_deezer/__init__.py

@@ -0,0 +1,3 @@
+from async_deezer.client import AsyncClient
+
+__all__ = ["AsyncClient"]