From bbc5fd5c0b2eef28b54c81e1514029ccc759cd66 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Fri, 13 Jun 2025 15:35:13 +0100
Subject: [PATCH 1/2] Docs

---
 docs/requests.md  | 91 ++++++++++++++++++++++++++++++++++++++++++++---
 docs/responses.md | 71 +++++++++++++++++++++++++++++++++---
 2 files changed, 154 insertions(+), 8 deletions(-)

diff --git a/docs/requests.md b/docs/requests.md
index 982c3b7..9481472 100644
--- a/docs/requests.md
+++ b/docs/requests.md
@@ -1,14 +1,97 @@
 # Requests
 
+The core elements of an HTTP request are the `method`, `url`, `headers` and `body`.
+
+```python
+>>> req = httpx.Request('GET', 'https://www.example.com/')
+>>> req
+<Request [GET 'https://www.example.com/']>
+>>> req.method
+'GET'
+>>> req.url
+<URL 'https://www.example.com/'>
+>>> req.headers
+<Headers {'Host': 'www.example.com'}>
+>>> req.body
+b''
+```
+
+## Working with the request headers
+
+The following headers have automatic behavior with `Requests` instances...
+
+* `Host` - A `Host` header must always be included on a request. This header is automatically populated from the `url`, using the `url.netloc` property.
+* `Content-Length` - Requests including a request body must always include either a `Content-Length` header or a `Transfer-Encoding: chunked` header. This header is automatically populated if `content` is not `None` and the content is a known size.
+* `Transfer-Encoding` - Requests automatically include a `Transfer-Encoding: chunked` header if `content` is not `None` and the content is an unkwown size.
+* `Content-Type` - Requests automatically include a `Content-Type` header if `content` is set using the [Content Type] API.
+
+## Working with the request body
+
+Including binary data directly...
+
+```python
+>>> headers = {'Content-Type': 'application/json'}
+>>> content = json.dumps(...)
+>>> httpx.Request('POST', 'https://echo.encode.io/', content=content)
+```
+
+## Working with content types
+
+Including JSON request content...
+
+```python
+>>> data = httpx.JSON(...)
+>>> httpx.Request('POST', 'https://echo.encode.io/', content=data)
+```
+
+Including form encoded request content...
+
+```python
+>>> data = httpx.Form(...)
+>>> httpx.Request('PUT', 'https://echo.encode.io/', content=data)
+```
+
+Including multipart file uploads...
+
+```python
+>>> form = httpx.MultiPart(form={...}, files={...})
+>>> with Request('POST', 'https://echo.encode.io/', content=form) as req:
+>>>     req.headers
+{...}
+>>>     req.stream
+<MultiPartStream [0% of ...MB]>
+```
+
+Including direct file uploads...
+
+```python
+>>> file = httpx.File('upload.json')
+>>> with Request('POST', 'https://echo.encode.io/', content=file) as req:
+>>>     req.headers
+{...}
+>>>     req.stream
+<FileStream [0% of ...MB]>
+```
+
+## Accessing request content...
+
 ...
 
----
+```python
+>>> data = request.json()
+```
 
-## Request
+...
 
-`<Request [GET “https://www.example.com”]>`
+```python
+>>> form = request.form()
+```
+
+...
 
-*TODO*
+```python
+>>> files = request.files()
+```
 
 ---
 
diff --git a/docs/responses.md b/docs/responses.md
index 009310d..516edd5 100644
--- a/docs/responses.md
+++ b/docs/responses.md
@@ -1,14 +1,77 @@
 # Responses
 
+The core elements of an HTTP response are the `status_code`, `headers` and `body`.
+
+```python
+>>> resp = httpx.Response(200, headers={'Content-Type': 'text/plain'}, content=b'hello, world')
+>>> resp
+<Response [200 OK]>
+>>> resp.status_code
+200
+>>> resp.headers
+<Headers {'Content-Type': 'text/html'}>
+>>> resp.body
+b'hello, world'
+```
+
+## Working with the response headers
+
+The following headers have automatic behavior with `Response` instances...
+
+* `Content-Length` - Responses including a response body must always include either a `Content-Length` header or a `Transfer-Encoding: chunked` header. This header is automatically populated if `content` is not `None` and the content is a known size.
+* `Transfer-Encoding` - Responses automatically include a `Transfer-Encoding: chunked` header if `content` is not `None` and the content is an unkwown size.
+* `Content-Type` - Responses automatically include a `Content-Type` header if `content` is set using the [Content Type] API.
+
+## Working with content types
+
+Including HTML content...
+
+```python
+>>> content = httpx.HTML('<html><head>...</head><body>...</body></html>')
+>>> response = httpx.Response(200, content=content)
+```
+
+Including plain text content...
+
+```python
+>>> content = httpx.Text('hello, world')
+>>> response = httpx.Response(200, content=content)
+```
+
+Including JSON data...
+
+```python
+>>> content = httpx.JSON({'message': 'hello, world'})
+>>> response = httpx.Response(200, content=content)
+```
+
+Including content from a file...
+
+```python
+>>> content = httpx.File('index.html')
+>>> response = httpx.Response(200, content=content)
+```
+
+## Accessing response content...
+
 ...
 
----
+```
+>>> content = response.body
+```
 
-## Response
+...
 
-`<Response [200 OK]>`
+```
+>>> text = response.text()
+...
+```
+
+...
 
-*TODO*
+```
+>>> data = response.json()
+```
 
 ---
 

From c370f8d5b5a108c9c3994494a5c67d65ab43c8a6 Mon Sep 17 00:00:00 2001
From: Tom Christie <tom@tomchristie.com>
Date: Fri, 13 Jun 2025 15:37:10 +0100
Subject: [PATCH 2/2] Docs

---
 docs/requests.md  | 2 +-
 docs/responses.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/requests.md b/docs/requests.md
index 9481472..fd143d0 100644
--- a/docs/requests.md
+++ b/docs/requests.md
@@ -73,7 +73,7 @@ Including direct file uploads...
 <FileStream [0% of ...MB]>
 ```
 
-## Accessing request content...
+## Accessing request content
 
 ...
 
diff --git a/docs/responses.md b/docs/responses.md
index 516edd5..cda0fb0 100644
--- a/docs/responses.md
+++ b/docs/responses.md
@@ -52,7 +52,7 @@ Including content from a file...
 >>> response = httpx.Response(200, content=content)
 ```
 
-## Accessing response content...
+## Accessing response content
 
 ...