Add top-level request() method
MODIFY
CONTRIBUTORS.txt
CONTRIBUTORS.txt
@@ -306,5 +306,8 @@ In chronological order:
* [Ezzeri Esa] <https://github.com/savarin>
* Ports and extends on types from typeshed
+* [Franciszek Magiera] <https://github.com/franekmagiera>
+ * Add top-level request method.
+
* [Your name or handle] <[email or website]>
* [Brief summary of your changes]

MODIFY
docs/user-guide.rst
docs/user-guide.rst
@@ -55,6 +55,13 @@ HTTP verb:
The :ref:`request_data` section covers sending other kinds of requests data,
including JSON, files, and binary data.
+.. note:: For quick scripts and experiments you can also use a top-level ``urllib3.request()``.
+ It uses a module-global ``PoolManager`` instance.
+ Because of that, its side effects could be shared across dependencies relying on it.
+ To avoid side effects, create a new ``PoolManager`` instance and use it instead.
+ In addition, the method does not accept the low-level ``**urlopen_kw`` keyword arguments.
+ System CA certificates are loaded on default.
+
.. _response_content:
Response Content

MODIFY
src/urllib3/__init__.py
src/urllib3/__init__.py
@@ -37,6 +37,7 @@ __all__ = (
"get_host",
"make_headers",
"proxy_from_url",
+ "request",
)
logging.getLogger(__name__).addHandler(NullHandler())
@@ -80,3 +81,17 @@ def disable_warnings(category=exceptions.HTTPWarning):
Helper for quickly disabling all urllib3 warnings.
"""
warnings.simplefilter("ignore", category)
+
+
+_DEFAULT_POOL = PoolManager()
+
+
+def request(method, url, fields=None, headers=None):
+ """
+ A convenience, top-level request method. It uses a module-global ``PoolManager`` instance.
+ Therefore, its side effects could be shared across dependencies relying on it.
+ To avoid side effects create a new ``PoolManager`` instance and use it instead.
+ The method does not accept low-level ``**urlopen_kw`` keyword arguments.
+ """
+
+ return _DEFAULT_POOL.request(method, url, fields=fields, headers=headers)

MODIFY
test/with_dummyserver/test_poolmanager.py
test/with_dummyserver/test_poolmanager.py
@@ -5,6 +5,7 @@ import pytest
from dummyserver.server import HAS_IPV6
from dummyserver.testcase import HTTPDummyServerTestCase, IPv6HTTPDummyServerTestCase
+from urllib3 import request
from urllib3.connectionpool import port_by_scheme
from urllib3.exceptions import MaxRetryError, URLSchemeUnknown
from urllib3.poolmanager import PoolManager
@@ -362,6 +363,11 @@ class TestPoolManager(HTTPDummyServerTestCase):
r = http.request("GET", url)
assert r.data == expected_target
+ def test_top_level_request(self):
+ r = request("GET", f"{self.base_url}/")
+ assert r.status == 200
+ assert r.data == b"Dummy server!"
+
@pytest.mark.skipif(not HAS_IPV6, reason="IPv6 is not supported on this system")
class TestIPv6PoolManager(IPv6HTTPDummyServerTestCase):

Add top-level request() method