Add a base_url option to ClientSession

CHANGES/6013.feature

@@ -0,0 +1 @@
+Added ``base_url`` parameter to the initializer of :class:`~aiohttp.ClientSession`.

aiohttp/client.py

@@ -169,6 +169,7 @@ class ClientSession:
     """First-class interface for making HTTP requests."""
 
     __slots__ = (
+        "_base_url",
         "_source_traceback",
         "_connector",
         "_loop",
@@ -193,6 +194,7 @@ class ClientSession:
 
     def __init__(
         self,
+        base_url: Optional[StrOrURL] = None,
         *,
         connector: Optional[BaseConnector] = None,
         cookies: Optional[LooseCookies] = None,
@@ -216,6 +218,11 @@ def __init__(
         trace_configs: Optional[List[TraceConfig]] = None,
         read_bufsize: int = 2 ** 16,
     ) -> None:
+        if base_url is None or isinstance(base_url, URL):
+            self._base_url: Optional[URL] = base_url
+        else:
+            self._base_url = URL(base_url)
+
         loop = asyncio.get_running_loop()
 
         if connector is None:
@@ -304,6 +311,12 @@ def request(
         """Perform HTTP request."""
         return _RequestContextManager(self._request(method, url, **kwargs))
 
+    def _build_url(self, str_or_url: StrOrURL) -> URL:
+        if self._base_url is None:
+            return URL(str_or_url)
+        else:
+            return self._base_url.join(URL(str_or_url))
+
     async def _request(
         self,
         method: str,
@@ -363,7 +376,7 @@ async def _request(
         proxy_headers = self._prepare_headers(proxy_headers)
 
         try:
-            url = URL(str_or_url)
+            url = self._build_url(str_or_url)
         except ValueError as e:
             raise InvalidURL(str_or_url) from e
 

docs/client_quickstart.rst

@@ -55,6 +55,18 @@ Other HTTP methods are available as well::
     session.options('http://httpbin.org/get')
     session.patch('http://httpbin.org/patch', data=b'data')
 
+To make several requests to the same site more simple, the parameter ``base_url``
+of :class:`ClientSession` constructor can be used. For example to request different
+endpoints of ``http://httpbin.org`` can be used the following code::
+
+    async with aiohttp.ClientSession('http://httpbin.org') as session:
+        async with session.get('/get'):
+            pass
+        async with session.post('/post', data=b'data'):
+            pass
+        async with session.put('/put', data=b'data'):
+            pass
+
 .. note::
 
    Don't create a session per request. Most likely you need a session

docs/client_reference.rst

@@ -38,7 +38,8 @@ Usage example::
 
 The client session supports the context manager protocol for self closing.
 
-.. class:: ClientSession(*, connector=None, loop=None, cookies=None, \
+.. class:: ClientSession(base_url=None, *, \
+                         connector=None, cookies=None, \
                          headers=None, skip_auto_headers=None, \
                          auth=None, json_serialize=json.dumps, \
                          version=aiohttp.HttpVersion11, \
@@ -56,6 +57,11 @@ The client session supports the context manager protocol for self closing.
    The class for creating client sessions and making requests.
 
 
+   :param base_url: Base part of the URL (optional)
+      If set it allows to skip the base part in request calls.
+
+      .. versionadded:: 3.8
+
    :param aiohttp.BaseConnector connector: BaseConnector
       sub-class instance to support connection pooling.
 

tests/test_client_session.py

@@ -706,3 +706,73 @@ async def test_requote_redirect_url_default_disable() -> None:
     session = ClientSession(requote_redirect_url=False)
     assert not session.requote_redirect_url
     await session.close()
+
+
+@pytest.mark.parametrize(
+    ("base_url", "url", "expected_url"),
+    [
+        pytest.param(
+            None,
+            "http://example.com/test",
+            URL("http://example.com/test"),
+            id="base_url=None url='http://example.com/test'",
+        ),
+        pytest.param(
+            None,
+            URL("http://example.com/test"),
+            URL("http://example.com/test"),
+            id="base_url=None url=URL('http://example.com/test')",
+        ),
+        pytest.param(
+            "http://example.com",
+            "/test",
+            URL("http://example.com/test"),
+            id="base_url='http://example.com' url='/test'",
+        ),
+        pytest.param(
+            "http://example.com",
+            "test",
+            URL("http://example.com/test"),
+            id="base_url='http://example.com' url='test'",
+        ),
+        pytest.param(
+            URL("http://example.com"),
+            "/test",
+            URL("http://example.com/test"),
+            id="base_url=URL('http://example.com') url='/test'",
+        ),
+        pytest.param(
+            URL("http://example.com"),
+            "test",
+            URL("http://example.com/test"),
+            id="base_url=URL('http://example.com') url='test'",
+        ),
+    ],
+)
+async def test_build_url_returns_expected_url(
+    create_session, base_url, url, expected_url
+) -> None:
+    session = await create_session(base_url)
+    assert session._build_url(url) == expected_url
+
+
+async def test_request_uses_base_url_when_url_is_str(create_session) -> None:
+    request_class = mock.MagicMock()
+    session = await create_session("http://example.com", request_class=request_class)
+    with contextlib.suppress(Exception):
+        await session.get("/test")
+
+    args, _ = request_class.call_args
+    url = args[1]
+    assert url == URL("http://example.com/test")
+
+
+async def test_request_not_uses_base_url_when_url_is_URL(create_session) -> None:
+    request_class = mock.MagicMock()
+    session = await create_session("http://example.com", request_class=request_class)
+    with contextlib.suppress(Exception):
+        await session.get(URL("http://sample.com"))
+
+    args, _ = request_class.call_args
+    url = args[1]
+    assert url == URL("http://sample.com")