The Fix
Fixes documentation according to set guidelines, including removing pycon references and adding print comments.
Based on closed urllib3/urllib3 issue #2223 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -32,12 +32,13 @@ urllib3 is powerful and easy to use:
.. code-block:: pycon
- >>> import urllib3
- >>> resp = urllib3.request("GET", "https://httpbin.org/robots.txt")
- >>> resp.status
Option A — Apply the official fix\nFixes documentation according to set guidelines, including removing pycon references and adding print comments.\nWhen NOT to use: This fix should not be used if the examples require specific formatting for legacy systems.\n\n
Why This Fix Works in Production
- Trigger: Users faced difficulties copying and running code examples due to formatting issues.
- Mechanism: Documentation examples were inconsistent and did not follow the new guidelines
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Documentation examples were inconsistent and did not follow the new guidelines
- Production symptom (often without a traceback): Users faced difficulties copying and running code examples due to formatting issues.
Proof / Evidence
- GitHub issue: #2223
- Fix PR: https://github.com/urllib3/urllib3/pull/2294
- Reproduced locally: No (not executed)
- Last verified: 2026-02-12
- Confidence: 0.60
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.82
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“We should make it amply clear that using urllib3.request(...) _will_ reuse connections behind the scenes, that it's using a module-global default PoolManager”
“A _copy button_ would be a great improvement. Right now copying lines from the code examples is painful.”
“Added guidance on code comments, imports, and displaying results to users via print.”
“I've prepared some pull requests, which hopefully tackle the items in the above list individually, to avoid a huge MR. I hope this is ok.”
Failure Signature (Search String)
- Users faced difficulties copying and running code examples due to formatting issues.
Copy-friendly signature
Failure Signature
-----------------
Users faced difficulties copying and running code examples due to formatting issues.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Users faced difficulties copying and running code examples due to formatting issues.
What Broke
Users faced difficulties copying and running code examples due to formatting issues.
Why It Broke
Documentation examples were inconsistent and did not follow the new guidelines
Fix Options (Details)
Option A — Apply the official fix
Fixes documentation according to set guidelines, including removing pycon references and adding print comments.
Fix reference: https://github.com/urllib3/urllib3/pull/2294
Last verified: 2026-02-12. Validate in your environment.
When NOT to Use This Fix
- This fix should not be used if the examples require specific formatting for legacy systems.
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
- Upgrade behind a canary and run integration tests against the canary before 100% rollout.
- Track RSS + object counts after deployments; alert on monotonic growth and GC pressure.
- Add a long-running test that repeats the failing call path and asserts stable memory.
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.