Use async/await in the readme example

[twm]

Fixes #382.

[adiroiban]

Thanks for the update.

Only a minor comments about the links in the README

I think that treq is an important library.
I would love to have it integrated in twisted/twisted

[adiroiban]

I think that this is needed...as otherwise the links are not working

I was testing with https://github.com/twisted/treq/tree/382-async-await-readme?tab=readme-ov-file

see as a playground https://rsted.info.ucl.ac.be/?theme=basic&n=8fd54317743434ab9a96c339c7862241

[twm]

Hmmm, I was trying to get rid of the underscores GitHub shows on current trunk:

But actually, the links there don't work either. I'll see if I can get that working — I'm a bit rusty on reST.

[adiroiban]

It looks like a bug in GitHub... I see the same problem with twisted/twisted

For twisted/towncrier we don't use the substitution ... maybe update treq to just use the image directive

.. image:: https://img.shields.io/pypi/v/towncrier
   :alt: PyPI release
   :target: https://pypi.org/project/towncrier/

[twm]

The substitution seems to work, the key is to make it a link with :target: as you suggested. I guess the link targets .. _calver: were picked up implicitly by docutils? Or maybe this never worked.

[twm]

Thank you for the review @adiroiban!

I would love to have it integrated in twisted/twisted

There are certainly parts of it that could live in twisted/twisted:

• RequestTraversalAgent (I've often taken a treq dep just for this)
• The body helpers in treq.content
• A better version of treq.auth
• MultiPartProducer (if its bugs were fixed)

Some parts that are iffy:

• HTTPClient
  • the interface is large, which makes it annoying to wrap (contrast with Agent)
  • all the methods here have heavily-overloaded arguments which is a very different style from Twisted proper (and parameter types are nearly incomprehensible because of that overloading)

• The "augmented" _Response type duplicates treq.content API surface and also buffers the response by default

Finally there some parts that I'd never put in twisted/twisted:

• Functions with global state (treq.request(), treq.get(), etc.)
• The requests dependency
• Treating header values as UTF-8 is simply wrong
• StubTreq (this should be a helper function that returns an appropriately-configured HTTPClient)

[twm]

Thanks again Adi!

[adiroiban]

Thanks for the info related to having treq code in twisted/twisted

I think merging parts of treq into twisted/twisted is a better approach.