From 05e8f682fb602f13e4940675b835cd20c2a0deb2 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Thu, 21 Mar 2019 14:18:33 +0000
Subject: [PATCH] Update README

---
 README.md | 48 ++++++++++++++++++++++++++++++++++++------------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index fa2a37d..a65b22b 100644
--- a/README.md
+++ b/README.md
@@ -14,21 +14,13 @@ Brings support for `async`/`await` syntax to Python's fabulous `requests` librar
 </a>
 </p>
 
-**This is just a first-pass right now.**
-
-Next set of things to deal with:
-
-* https support, and certificate checking.
-* streaming support for uploads and downloads.
-* connection pooling.
-* async cookie persistence, for on-disk cookie stores.
-* timeouts
+**Contributions towards closing off our [outstanding issues][issues] would be very welcome!** ✨ 🍰 ✨
 
 ## Requirements
 
 * Python 3.6, 3.7.
 
-## Installation:
+## Installation
 
 ```shell
 $ pip install requests-async
@@ -36,13 +28,45 @@ $ pip install requests-async
 
 ## Usage:
 
-Just use the standard requests API, but use `await` for making requests.
+Just use *the standard requests API*, but use `await` for making requests.
+
+**Note**: Use `ipython` to try this from the console, since it supports `await`.
 
 ```python
 import requests_async as requests
 
 
-response = await requests.get('http://example.org')
+response = await requests.get('https://example.org')
 print(response.status_code)
 print(response.text)
 ```
+
+Or use explicit sessions.
+
+```python
+import requests_async as requests
+
+
+with requests.Session() as session:
+    response = await requests.get('https://example.org')
+    print(response.status_code)
+    print(response.text)
+```
+
+The `requests_async` package subclasses `requests`, so you're getting all the
+standard behavior and API you'd expect.
+
+## Limitations
+
+* Streaming uploads and downloads are unsupported.
+* SSL verification is not currently enabled.
+* No timeout support yet.
+
+See the [issues list][issues] for more details.
+
+## Alternatives
+
+The [`aiohttp` package][aiohttp] provides an alternative client for making async HTTP requests.
+
+[issues]: https://github.com/encode/requests-async/issues
+[aiohttp]: https://docs.aiohttp.org/en/stable/client.html