Shinier documentation

CHANGELOG.rst

@@ -26,7 +26,7 @@ Features
 --------
 
 - treq now ships type annotations. (`#366 <https://github.com/twisted/treq/issues/366>`__)
-- The new :mod:`treq.cookies` module provides helper functions for working with `http.cookiejar.Cookie` and `CookieJar` objects. (`#384 <https://github.com/twisted/treq/issues/384>`__)
+- The new :mod:`treq.cookies` module provides helper functions for working with `http.cookiejar.Cookie` and :class:`~http.cookiejar.CookieJar` objects. (`#384 <https://github.com/twisted/treq/issues/384>`__)
 - Python 3.13 is now supported. (`#391 <https://github.com/twisted/treq/issues/391>`__)
 
 
@@ -40,7 +40,7 @@ Deprecations and Removals
 -------------------------
 
 - Mixing the *json* argument with *files* or *data* now raises `TypeError`. (`#297 <https://github.com/twisted/treq/issues/297>`__)
-- Passing non-string (`str` or `bytes`) values as part of a dict to the *headers* argument now results in a `TypeError`, as does passing any collection other than a `dict` or `Headers` instance. (`#302 <https://github.com/twisted/treq/issues/302>`__)
+- Passing non-string (`str` or `bytes`) values as part of a dict to the *headers* argument now results in a `TypeError`, as does passing any collection other than a `dict` or :class:`~twisted.web.http.http_headers.Headers` instance. (`#302 <https://github.com/twisted/treq/issues/302>`__)
 - Support for Python 3.7 and PyPy 3.8, which have reached end of support, has been dropped. (`#378 <https://github.com/twisted/treq/issues/378>`__)
 
 

README.rst

@@ -24,8 +24,8 @@ treq: High-level Twisted HTTP Client API
 
 ``treq`` is an HTTP library inspired by
 `requests <https://requests.readthedocs.io/>`_ but written on top of
-`Twisted <https://www.twistedmatrix.com>`_'s
-`Agents <https://twistedmatrix.com/documents/current/api/twisted.web.client.Agent.html>`_.
+`Twisted <https://twisted.org/>`_'s
+`Agents <https://docs.twisted.org/en/stable/api/twisted.web.client.Agent.html>`_.
 
 It provides a simple, higher level API for making HTTP requests when
 using Twisted.

changelog.d/409.doc.rst

@@ -0,0 +1 @@
+Update documentation to use `async`/`await` syntax

docs/conf.py

@@ -26,13 +26,18 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ["sphinx.ext.viewcode", "sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
+extensions = [
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_rtd_theme",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
@@ -92,12 +97,15 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "default"
+html_theme = "sphinx_rtd_theme"
+
+# https://docs.readthedocs.com/platform/stable/intro/sphinx.html#set-the-canonical-url
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {"flyout_display": "attached"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

docs/examples/_utils.py

@@ -1,10 +1,7 @@
-from __future__ import print_function
-
 import treq
 
 
-def print_response(response):
+async def print_response(response):
     print(response.code, response.phrase)
     print(response.headers)
-
-    return treq.text_content(response).addCallback(print)
+    print(await treq.text_content(response))

docs/examples/basic_auth.py

@@ -1,15 +1,15 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get(
-        'https://httpbin.org/basic-auth/treq/treq',
-        auth=('treq', 'treq')
+async def basic_auth(reactor):
+    resp = await treq.get(
+        "https://httpbin.org/basic-auth/treq/treq",
+        auth=("treq", "treq"),
     )
-    d.addCallback(print_response)
-    return d
+    await print_response(resp)
+
 
-react(main, [])
+react(basic_auth)

docs/examples/basic_get.py

@@ -1,12 +1,13 @@
 from twisted.internet.task import react
-from _utils import print_response
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get('https://httpbin.org/get')
-    d.addCallback(print_response)
-    return d
+async def basic_get(reactor):
+    resp = await treq.get("https://httpbin.org/get")
+    print(resp.code, resp.phrase)
+    print(resp.headers)
+    print(await resp.text())
 
-react(main, [])
+
+react(basic_get)

docs/examples/basic_post.py

@@ -1,13 +1,15 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor):
-    d = treq.post("https://httpbin.org/post",
-                  data={"form": "data"})
-    d.addCallback(print_response)
-    return d
+def basic_post(reactor):
+    resp = await treq.post(
+        "https://httpbin.org/post",
+        data={"form": "data"},
+    )
+    await print_response(resp)
+
 
-react(main, [])
+react(basic_post)

docs/examples/basic_url.py

@@ -1,17 +1,18 @@
-# -*- encoding: utf-8 -*-
+from _utils import print_response
 from hyperlink import DecodedURL
 from twisted.internet.task import react
-from _utils import print_response
 
 import treq
 
-def main(reactor):
+
+async def basic_url(reactor):
     url = (
-        DecodedURL.from_text(u"https://httpbin.org")
-        .child(u"get")      # add path /get
-        .add(u"foo", u"&")  # add query ?foo=%26
+        DecodedURL.from_text("https://httpbin.org")
+        .child("get")  # add path /get
+        .add("foo", "&")  # add query ?foo=%26
     )
     print(url.to_text())
-    return treq.get(url).addCallback(print_response)
+    await print_response(await treq.get(url))
+
 
-react(main, [])
+react(basic_url)

docs/examples/custom_agent.py

@@ -1,19 +1,18 @@
-from treq.client import HTTPClient
 from _utils import print_response
 from twisted.internet.task import react
 from twisted.web.client import Agent
 
-def make_custom_agent(reactor):
-    return Agent(reactor, connectTimeout=42)
+from treq.client import HTTPClient
+
 
-def main(reactor, *args):
-    agent = make_custom_agent(reactor)
-    http_client = HTTPClient(agent)
-    d = http_client.get(
-        'https://secure.example.net/area51',
-        auth=('admin', "you'll never guess!"))
-    d.addCallback(print_response)
-    return d
+async def custom_agent(reactor):
+    my_agent = Agent(reactor, connectTimeout=42)
+    http_client = HTTPClient(my_agent)
+    resp = await http_client.get(
+        "https://secure.example.net/area51",
+        auth=("admin", "you'll never guess!"),
+    )
+    await print_response(resp)
 
-react(main, [])
 
+react(custom_agent)

docs/examples/disable_redirects.py

@@ -1,12 +1,15 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get('https://httpbin.org/redirect/1', allow_redirects=False)
-    d.addCallback(print_response)
-    return d
+async def disable_redirects(reactor):
+    resp = await treq.get(
+        "https://httpbin.org/redirect/1",
+        allow_redirects=False,
+    )
+    await print_response(resp)
+
 
-react(main, [])
+react(disable_redirects)

docs/examples/download_file.py

@@ -3,11 +3,10 @@
 import treq
 
 
-def download_file(reactor, url, destination_filename):
-    destination = open(destination_filename, 'wb')
-    d = treq.get(url, unbuffered=True)
-    d.addCallback(treq.collect, destination.write)
-    d.addBoth(lambda _: destination.close())
-    return d
-
-react(download_file, ['https://httpbin.org/get', 'download.txt'])
+async def download_file(reactor, url, destination_filename):
+    with open(destination_filename, "wb") as destination:
+        response = await treq.get(url, unbuffered=True)
+        await treq.collect(response, destination.write)
+
+
+react(download_file, ["https://httpbin.org/get", "download.txt"])

docs/examples/json_post.py

@@ -1,18 +1,17 @@
 from pprint import pprint
 
-from twisted.internet import defer
 from twisted.internet.task import react
 
 import treq
 
 
-@defer.inlineCallbacks
-def main(reactor):
-    response = yield treq.post(
-        'https://httpbin.org/post',
+async def json_post(reactor):
+    response = await treq.post(
+        "https://httpbin.org/post",
         json={"msg": "Hello!"},
     )
-    data = yield response.json()
+    data = await response.json()
     pprint(data)
 
-react(main, [])
+
+react(json_post)

docs/examples/query_params.py

@@ -1,39 +1,37 @@
 from twisted.internet.task import react
-from twisted.internet.defer import inlineCallbacks
 
 import treq
 
 
-@inlineCallbacks
-def main(reactor):
-    print('List of tuples')
-    resp = yield treq.get('https://httpbin.org/get',
-                          params=[('foo', 'bar'), ('baz', 'bax')])
-    content = yield resp.text()
-    print(content)
-
-    print('Single value dictionary')
-    resp = yield treq.get('https://httpbin.org/get',
-                          params={'foo': 'bar', 'baz': 'bax'})
-    content = yield resp.text()
-    print(content)
-
-    print('Multi value dictionary')
-    resp = yield treq.get('https://httpbin.org/get',
-                          params={b'foo': [b'bar', b'baz', b'bax']})
-    content = yield resp.text()
-    print(content)
-
-    print('Mixed value dictionary')
-    resp = yield treq.get('https://httpbin.org/get',
-                          params={'foo': [1, 2, 3], 'bax': b'quux', b'bar': 'foo'})
-    content = yield resp.text()
-    print(content)
-
-    print('Preserved query parameters')
-    resp = yield treq.get('https://httpbin.org/get?foo=bar',
-                          params={'baz': 'bax'})
-    content = yield resp.text()
-    print(content)
-
-react(main, [])
+async def query_params(reactor):
+    print("List of tuples")
+    resp = await treq.get(
+        "https://httpbin.org/get", params=[("foo", "bar"), ("baz", "bax")]
+    )
+    print(await resp.text())
+
+    print("Single value dictionary")
+    resp = await treq.get(
+        "https://httpbin.org/get", params={"foo": "bar", "baz": "bax"}
+    )
+    print(await resp.text())
+
+    print("Multi value dictionary")
+    resp = await treq.get(
+        "https://httpbin.org/get", params={b"foo": [b"bar", b"baz", b"bax"]}
+    )
+    print(await resp.text())
+
+    print("Mixed value dictionary")
+    resp = await treq.get(
+        "https://httpbin.org/get",
+        params={"foo": [1, 2, 3], "bax": b"quux", b"bar": "foo"},
+    )
+    print(await resp.text())
+
+    print("Preserved query parameters")
+    resp = await treq.get("https://httpbin.org/get?foo=bar", params={"baz": "bax"})
+    print(await resp.text())
+
+
+react(query_params)

docs/examples/redirects.py

@@ -1,12 +1,12 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get('https://httpbin.org/redirect/1')
-    d.addCallback(print_response)
-    return d
+async def redirects(reactor):
+    resp = await treq.get("https://httpbin.org/redirect/1")
+    await print_response(resp)
+
 
-react(main, [])
+react(redirects)

docs/examples/response_history.py

@@ -1,18 +1,14 @@
-from twisted.internet.task import react
 from _utils import print_response
+from twisted.internet.task import react
 
 import treq
 
 
-def main(reactor, *args):
-    d = treq.get('https://httpbin.org/redirect/1')
-
-    def cb(response):
-        print('Response history:')
-        print(response.history())
-        return print_response(response)
+async def response_history(reactor):
+    resp = await treq.get("https://httpbin.org/redirect/1")
+    print("Response history:")
+    print(resp.history())
+    await print_response(resp)
 
-    d.addCallback(cb)
-    return d
 
-react(main, [])
+react(response_history)