Extra docs on in-depth interface bits.

[tomchristie]

• URLs - Document the four-tuple, explain why userauth isn't present, and that the querystring is just part of the path.
• Timeouts - Document what we're expecting in those timeout dicts.
• ByteStreams - Document closing byte streams, use try...finally everywhere (change the example in the readme/homepage) explain that user code ought to typically wrap any streaming responses up in a context managed interface.
• Headers - Document whatever header casing constraints we opt for. Document any headers that may be automatically included, eg. auto-include Host header. Document expected behaviors around Content-Length, Transfer-Encoding, and request body.

[simonw]

From the code, the timeout dictionary has four supported keys:

• pool
• read
• write
• connect

These values are all floating point number of seconds.

[tomchristie]

Closed via the neatly spec'ed Transport API in #1522.

I think docstring for BaseTransport covers the interface sufficiently now.

httpx/httpx/_transports/base.py

Lines 30 to 92 in 1a6e254

	"""
	Send a single HTTP request and return a response.
	At this layer of API we're simply using plain primitives. No `Request` or
	`Response` models, no fancy `URL` or `Header` handling. This strict point
	of cut-off provides a clear design seperation between the HTTPX API,
	and the low-level network handling.
	Developers shouldn't typically ever need to call into this API directly,
	since the Client class provides all the higher level user-facing API
	niceties.
	Example usage:
	with httpx.HTTPTransport() as transport:
	status_code, headers, stream, extensions = transport.handle_request(
	method=b'GET',
	url=(b'https', b'www.example.com', 443, b'/'),
	headers=[(b'Host', b'www.example.com')],
	stream=[],
	extensions={}
	)
	try:
	body = b''.join([part for part in stream])
	finally:
	if 'close' in extensions:
	extensions['close']()
	print(status_code, headers, body)
	Arguments:
	method: The request method as bytes. Eg. b'GET'.
	url: The components of the request URL, as a tuple of `(scheme, host, port, target)`.
	The target will usually be the URL path, but also allows for alternative
	formulations, such as proxy requests which include the complete URL in
	the target portion of the HTTP request, or for "OPTIONS *" requests, which
	cannot be expressed in a URL string.
	headers: The request headers as a list of byte pairs.
	stream: The request body as a bytes iterator.
	extensions: An open ended dictionary, including optional extensions to the
	core request/response API. Keys may include:
	timeout: A dictionary of str:Optional[float] timeout values.
	May include values for 'connect', 'read', 'write', or 'pool'.
	Returns a tuple of:
	status_code: The response status code as an integer. Should be in the range 1xx-5xx.
	headers: The response headers as a list of byte pairs.
	stream: The response body as a bytes iterator.
	extensions: An open ended dictionary, including optional extensions to the
	core request/response API. Keys are plain strings, and may include:
	reason_phrase: The reason-phrase of the HTTP response, as bytes. Eg b'OK'.
	HTTP/2 onwards does not include a reason phrase on the wire.
	When no key is included, a default based on the status code may
	be used. An empty-string reason phrase should not be substituted
	for a default, as it indicates the server left the portion blank
	eg. the leading response bytes were b"HTTP/1.1 200 <CRLF>".
	http_version: The HTTP version, as bytes. Eg. b"HTTP/1.1".
	When no http_version key is included, HTTP/1.1 may be assumed.
	close: A callback which should be invoked to release any network
	resources.
	aclose: An async callback which should be invoked to release any
	network resources.