Documenting the network backend API

[tomchristie]

This pull request adds the network backends as public API.

This will help our users understand the architecture of httpcore, allow for more in depth debugging, and allow for complex use cases such as network record/replay or custom DNS handling.

The documentation I'm adding here doesn't follow the existing (internal) class names, but instead takes a docs-first approach to

TODO:

• Add documentation
• Change the naming as described in the API here.
• Ensure UDS case raises a descriptive warning if not implemented. - Already has a NotImplementedError.
• Link from the "network_stream" extension to the relevant part of the backends docs.
• httpcore.backends can become private.
• Make top-level httpcore.<...> classes available, with conditionals for async cases if needed.
• Tests should import from public API wherever possible.
• Add to CHANGELOG

---

Notes to self:

• Add docstring'ed API reference.
• Change start_tls to in-place? (Would also need a docs update in extensions.md)
• Drop sleep from the existing interface.
• Add AutoBackend?
• I've had to add SOCKET_OPTIONS to the public API, because of the interface here.
• We might want to reconsider a AsyncIOBackend now.

Closes #695

[tomchristie]

This is ready for review from a docs-first perspective.

[tomchristie]

I've now updated the API in this pull request, in line with the docs so it's possible to properly work through the examples...

Documentation: https://github.com/encode/httpcore/blob/network-backends-api/docs/network-backends.md

Install from this branch in order to work through...

$ python -m venv venv
$ venv/bin/pip install git+https://github.com/encode/httpcore.git@network-backends-api
$ venv/bin/python

[tomchristie]

I've bumped a bunch of items into possible follow-ons.

[tomchristie]

I have bumped out the following conversations on the back of this...

• Adding `httpcore.AsyncIOBackend()`. #712
• Should we reconsider `<NetworkBackend>.sleep()`? #711
• Should `<NetworkingBackend>.start_tls()` be an in-place interface? #710

[tomchristie]

Okay, let's have it.

Thanks all for the review time on this. 😊