Repository: encode/httpx
Pull request: Add docs on request instances to Requests compatibility guide
* Add prepare_request equivalent of httpx to compatibility document

* Add difference b/w httpx.Request and requests.Request arguments to compatibility document

Fixes #795, fixes #794

Problem statement:
httpx.Request don't take the same arguments
the `httpx.Request` takes `(method, url, [params], [data], [json], [headers], [cookies])`
and the `requests.Request` takes `(method=None, url=None, headers=None, files=None, data={}, params={}, auth=None, cookies=None, hooks=None)`

this should be pointed out in the documentation or implemented

httpx.Client misses the prepare_request method

Hints from issue discussion:
Happy to review any PRs that document which parameters aren’t present on our `Request` class compared to Requests. :)

From what I can see these are:

- `files` (I believe this is handled via `data`, isn’t it?)
- `hooks`
`files` is there, but `auth` isn't.
https://github.com/encode/httpx/blob/82dc6f32f864d26677df8fc61249a7fc74c687e8/httpx/_models.py#L591-L604

However, `auth` is available on the `request` method: https://github.com/encode/httpx/blob/82dc6f32f864d26677df8fc61249a7fc74c687e8/httpx/_api.py#L18-L34

Hooks are discussed here: https://github.com/encode/httpx/issues/790
> but `auth` isn't

Not immediately obvious to me that this was a deliberate design choice, or just the way things ended up being implemented. (We're passing `auth` in `Client.send()`, but we probably could very well move it onto a `request.auth` attribute.) As a matter of fact, we do support per-request auth, so… Maybe there's room for retro-fitting to the Requests API here?
> Not immediately obvious to me that this was a deliberate design choice, or just the way things ended up being implemented. (We're passing auth in Client.send(), but we probably could very well move it onto a request.auth attribute.) As a matter of fact, we do support per-request auth, so… Maybe there's room for retro-fitting to the Requests API here?

I think we proabably want to keep things as they are. When I started out the "Requests Compatability" the intention was to document anything that differed across the Basic and Advanced usage guides, rather than that lower level bits of API would match all the way through.

It makes sense to me that our `auth` parameter would be on the `send()` method, since it's *not* something that we can always just call into to build some extra headers on the request method, it actually alters the sending flow.

I think we might be okay with a slightly general "Not all stuff in the lower level bits of API might match up exactly", giving a couple of examples? Or else perhaps a section for low level API differences, where we briefly list any notable cases. (Eg. I also haven't reviewed how our `build_request`/`send` compares to the `requests` equivelent.)
Agreed, I think it was only top-level compatibility (`httpx.HTTP_VERB`) that was shot for, and other things have come along naturally as they made sense to include.
This is intended, as any « preparation » of parameters is done inside the `Request` constructor directly. Happy to review a PR that adds this difference to our Requests compatibility guide.
We have `build_request` and `send`  We will want to document this pair in the advanced section, yup.

Commit message: Update docs/compatibility.md

* Add prepare_request equivalent of httpx to compatibility document

* Add difference b/w httpx.Request and requests.Request arguments to compatibility document

Patch to review:
diff --git a/docs/compatibility.md b/docs/compatibility.md
index 89235b1262..833066bb40 100644
--- a/docs/compatibility.md
+++ b/docs/compatibility.md
@@ -64,6 +64,20 @@ is generally equivalent to
 client = httpx.Client(**kwargs)
 ```
 
+The HTTPX equivalent of `prepare_request` of `requests.Session` instance is `build_request` of `httpx.Client`.
+
+## Request arguments
+
+The `Request` class of `httpx` takes the arguments
+
+`(method, url, params=None, headers=None, cookies=None, data=None, files=None, json=None, stream=None)`
+
+where as `requests.Request` takes the arguments
+
+`(method, url, params=None, data=None, json=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, verify=True, stream=None, cert=None)`
+
+The list of arguments that are not present in `httpx.Request` class are `auth`, `timeout`, `allow_redirects`, `proxies`, `verify` and `cert` however these are available in `httpx.request`, `httpx.get`, `httpx.post` etc.
+
 ## Mocking
 
 If you need to mock HTTPX the same way that test utilities like `responses` and `requests-mock` does for `requests`, see [RESPX](https://github.com/lundberg/respx).


Code review comments:
diff_hunk: @@ -64,6 +64,20 @@ is generally equivalent to
 client = httpx.Client(**kwargs)
 ```
 
+The HTTPX equivalent of `prepare_request` of `requests.Session` instance is `build_request` of `httpx.Client`.
path: docs/compatibility.md
text: @user1:
I’m not sure these are strictly equivalent. I remember `.prepare_request` mutates à request object in place, while `.build_request()` is mostly a convenience helper for applying client defaults.

So maybe we can present it like this...

- There’s no need for `prepare_request()` in HTTPX: request objects are ready to be sent across the wire as soon as they are instantiated, e.g. `Request("GET", "https://example.org")`.
- If you need to build a request while applying client defaults, see <link to existing docs on `build_requests` in the advanced docs>.

I guess both pieces of info can be moved to a « Request instantiation » section, together with the contents of request arguments below?

@author:
True, they are not strictly equivalent. we can only send `PreparedRequest` to `.send()` in `requests`. And having separate section Request instantiation also makes it clear.

diff_hunk: @@ -64,6 +64,20 @@ is generally equivalent to
 client = httpx.Client(**kwargs)
 ```
 
+The HTTPX equivalent of `prepare_request` of `requests.Session` instance is `build_request` of `httpx.Client`.
+
+## Request arguments
+
+The `Request` class of `httpx` takes the arguments
path: docs/compatibility.md
text: @user1:
IMO we should avoid duplicating this information and instead link to the Developer Interface docs for `Request`.

@author:
agree.