From: Trim21 <trim21.me@gmail.com>
Date: Thu, 13 Jul 2023 12:55:41 +0000 (+0800)
Subject: docs: upload progress (#2725)
X-Git-Tag: 0.25.0~22
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f115ce4e097576c0089f3169b448e26af688e85c;p=thirdparty%2Fhttpx.git

docs: upload progress (#2725)

* upload progress

* typo

* typo

* Update docs/advanced.md

* Update advanced.md

* Update docs/advanced.md

Co-authored-by: Kar Petrosyan <92274156+karosis88@users.noreply.github.com>

---------

Co-authored-by: Tom Christie <tom@tomchristie.com>
Co-authored-by: Kar Petrosyan <92274156+karosis88@users.noreply.github.com>
---

diff --git a/docs/advanced.md b/docs/advanced.md
index d01b4350..2a477966 100644
--- a/docs/advanced.md
+++ b/docs/advanced.md
@@ -426,6 +426,38 @@ with tempfile.NamedTemporaryFile() as download_file:
 
 ![rich progress bar](img/rich-progress.gif)
 
+## Monitoring upload progress
+
+If you need to monitor upload progress of large responses, you can use request content generator streaming.
+
+For example, showing a progress bar using the [`tqdm`](https://github.com/tqdm/tqdm) library.
+
+```python
+import io
+import random
+
+import httpx
+from tqdm import tqdm
+
+
+def gen():
+    """
+    this is a complete example with generated random bytes.
+    you can replace `io.BytesIO` with real file object.
+    """
+    total = 32 * 1024 * 1024  # 32m
+    with tqdm(ascii=True, unit_scale=True, unit='B', unit_divisor=1024, total=total) as bar:
+        with io.BytesIO(random.randbytes(total)) as f:
+            while data := f.read(1024):
+                yield data
+                bar.update(len(data))
+
+
+httpx.post("https://httpbin.org/post", content=gen())
+```
+
+![tqdm progress bar](img/tqdm-progress.gif)
+
 ## .netrc Support
 
 HTTPX can be configured to use [a `.netrc` config file](https://everything.curl.dev/usingcurl/netrc) for authentication.