Add top-level request() method

4 files changed, 31 insertions, 0 deletions

diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 51bbc2b2..7b96269c 100644
--- a/CONTRIBUTORS.txt
+++ b/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]
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 0bfe5bf0..53464d6a 100644
--- a/docs/user-guide.rst
+++ b/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
diff --git a/src/urllib3/__init__.py b/src/urllib3/__init__.py
index 067e40a6..6199e333 100644
--- a/src/urllib3/__init__.py
+++ b/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)
diff --git a/test/with_dummyserver/test_poolmanager.py b/test/with_dummyserver/test_poolmanager.py
index 9f313934..56bcd134 100644
--- a/test/with_dummyserver/test_poolmanager.py
+++ b/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):