Repository: encode/httpx

Issue:
Version 0.10.0
Let's get squared away what we need for Version 0.10.0.

The key here is we need to make sure we've sorted out any API that'd block us from reintroducing the sync API, so...

* [x] Let's drop `.read()` from `Request` - It's not documented anywhere, not *actually* required by users, and the content is available on `request.stream` if absolutely needed. #679
* [x] We need `Response.read()` and `Response.close()` to be `Response.aread()` and `Response.aclose()`. The only point where this is relevant is users performing conditional reads inside a `with httpx.stream(method, url) as response` block. #674
* [x] We ought to have `Client.close()` become `Client.aclose()` for consistency. #675
* [x] Good point to get #617 in.
* [x] We'll need to change `response.next()`. We could *either* underspecify the return type, and allow it to be either sync or async depending on the context, *or* we use `response.anext()` and `response.next()`. #676
* [ ] ~Good point to address~ #656.
* [x] *Potentially* we could introduce an `httpx.AsyncClient` synonm for `httpx.Client`, and advise our users to switch towards that usage, so that there's no breaking changes for them once we fully reintroduce a sync API all the way through. #680


Discussion:
> We need `Response.read()` and `Response.close()` to be `Response.aread()` and `Response.aclose()`.

> We ought to have `Client.close()` become `Client.aclose()` for consistency.

I assume we want these changes to be backwards-compatible for 0.10, right? (Or should they error on usage?)

> *or* we use `response.anext()` and `response.next()`

Keen on this, as it reflects `gen.__next__()` and `async_gen.__anext__()`. :+1:
Regarding `.aclose()` — I think we probably want to switch to that naming for all our other `.close()` operations too, if only for consistency.

In particular, this would be consistent with the overall convention in the async ecosystem — e.g. [`AsyncExitStack`](https://docs.python.org/3/library/contextlib.html#contextlib.AsyncExitStack.aclose), `async_generator`'s [`aclosing`](https://github.com/python-trio/async_generator/blob/9f0e08c762dc2b9e18a38e8dd714790a319ed836/async_generator/_util.py#L6) (async equivalent of [`contextlib.closing`](https://docs.python.org/3/library/contextlib.html#contextlib.closing)), etc.
Pragmatically I think we probably just want to make the response/request changes and document them. If we don’t do that we’ll be blocked from reintroducing the sync API. They only affect anyone using conditional reads in streaming responses, and we’ve got clear messaging about pinning versions.
> If we don’t do that we’ll be blocked from reintroducing the sync API.

Yes, that's a good point. Same for `Client`, then, yes?
Probably yes.
I'm dropping the `.origin` issue for now.
We have PRs for all of these except the possible `AsyncClient` synonm, which we can probably also drop?

I'd suggest we issue a Version update pull request, with CHANGELOG and version update, just to allow a final once-over, then look at merge each of those 5 pull requests in and then issuing the release.
> We have PRs for all of these except the possible AsyncClient synonm, which we can probably also drop?

Well, I guess that depends what we'd like the final API to be like:

1. `httpx.AsyncClient()` / `httpx.SyncClient()`?
1. `httpx.Client()` / `httpx.SyncClient()`?

I think 1) is more natural, so I'd say bringing back `AsyncClient` as a synonym for `Client` does make sense for 0.10?
I pushed a PR for the `AsyncClient` renaming, so at least we've got it ready if we want it to land in 0.10 (and I think we should?).
Milestoned everything that we think is going into this.
I thin we prep the release notes *before* we merge, just to give us a final once over.
(I'd like them to also note the motivation for the changes here)

Resolving patch:
diff --git a/httpx/__version__.py b/httpx/__version__.py
--- a/httpx/__version__.py
+++ b/httpx/__version__.py
@@ -1,3 +1,3 @@
 __title__ = "httpx"
 __description__ = "A next generation HTTP client, for Python 3."
-__version__ = "0.9.5"
+__version__ = "0.10.0"


Test patch: