Tweaks (#89)

* Close redirect responses

* History should not be reverse-order

* History should not be reverse-order

* Docs updates

docs/compatibility.md

@@ -4,4 +4,18 @@ HTTP3 aims to be compatible with the `requests` API wherever possible.
 
 This documentation outlines places where the API differs...
 
-**TODO**
+## QuickStart
+
+Pretty much all the API mentioned in the `requests` QuickStart should be identical
+to the API in our own documentation. The following exceptions apply:
+
+* `Response.url` - Returns a `URL` instance, rather than a string. Use `str(response.url)` if you need a string instance.
+* `Response.status_code` - Returns an integer, which may be a `StatusCode` IntEnum. This has the same behaviour as any other integer, except that it provides more information in the instance representation.
+* `http3.codes` - In our documentation we prefer the uppercased versions, such as `codes.NOT_FOUND`,
+but also provide lower-cased versions for API compatibility with `requests`.
+* `stream=True`. - Streaming responses provide the `.stream()` and `.raw()` byte iterator interfaces, rather than the `.iter_content()` method and the `.raw` socket interface.
+
+## Advanced Usage
+
+!!! warning
+    TODO

docs/quickstart.md

@@ -289,7 +289,7 @@ To include cookies in an outgoing request, use the `cookies` parameter:
 ```
 
 Cookies are returned in a `Cookies` instance, which is a dict-like data structure
-but with additional API for accessing cookies by their domain or path.
+with additional API for accessing cookies by their domain or path.
 
 ```python
 >>> cookies = http3.Cookies()
@@ -299,3 +299,56 @@ but with additional API for accessing cookies by their domain or path.
 >>> r.json()
 {'cookies': {'cookie_on_domain': 'hello, there!'}}
 ```
+
+## Redirection and History
+
+By default HTTP3 will follow redirects for anything except `HEAD` requests.
+
+The `history` property of the response can be used to inspect any followed redirects.
+It contains a list of all any redirect responses that were followed, in the order
+in which they were made.
+
+For example, GitHub redirects all HTTP requests to HTTPS.
+
+```python
+>>> r = http3.get('http://github.com/')
+>>> r.url
+URL('https://github.com/')
+>>> r.status_code
+<StatusCode.OK: 200>
+>>> r.history
+[<Response [301]>]
+```
+
+You can modify the default redirection handling with the allow_redirects parameter:
+
+```python
+>>> r = http3.get('http://github.com/', allow_redirects=False)
+>>> r.status_code
+301
+>>> r.history
+[]
+```
+
+If you’re making a `HEAD` request, you can use this to enable redirection:
+
+```python
+>>> r = http3.head('http://github.com/', allow_redirects=True)
+>>> r.url
+'https://github.com/'
+>>> r.history
+[<Response [301]>]
+```
+
+## Timeouts
+
+HTTP3 defaults to including reasonable timeouts for all network operations,
+meaning that if a connection is not properly established then it should always
+raise an error rather than hanging indefinitely.
+
+The default timeout for network inactivity is five seconds. You can modify the
+value to be more or less strict:
+
+```python
+>>> http3.get('https://github.com/', timeout=0.001)
+```

http3/client.py

@@ -149,7 +149,7 @@ class BaseClient:
                 assert isinstance(response, AsyncResponse)
                 response.history = list(history)
                 self.cookies.extract_cookies(response)
-                history = [response] + history
+                history = history + [response]
 
                 if allow_redirects and response.is_redirect:
                     request = self.build_redirect_request(request, response)

tests/client/test_redirects.py

@@ -168,6 +168,10 @@ async def test_multiple_redirects():
     assert response.status_code == codes.OK
     assert response.url == URL("https://example.org/multiple_redirects")
     assert len(response.history) == 20
+    assert response.history[0].url == URL("https://example.org/multiple_redirects?count=20")
+    assert response.history[1].url == URL("https://example.org/multiple_redirects?count=19")
+    assert len(response.history[0].history) == 0
+    assert len(response.history[1].history) == 1
 
 
 @pytest.mark.asyncio