feat: allow injection of httpx client (#363)

Author: silentworks

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
           version: latest
 
       - name: Start Supabase local development setup
-        run: supabase start --workdir infra -x studio,gotrue,postgrest,inbucket,realtime,edge-runtime,logflare,vector,pgbouncer,pg_prove
+        run: supabase start --workdir infra -x studio,gotrue,postgrest,mailpit,realtime,edge-runtime,logflare,vector,supavisor
 
       - name: Run Tests
         run: make run_tests

Makefile

@@ -11,7 +11,7 @@ tests_pre_commit:
 	poetry run pre-commit run --all-files
 
 run_infra:
-	npx supabase --workdir infra start -x studio,gotrue,postgrest,inbucket,realtime,edge-runtime,logflare,vector,pgbouncer,pg_prove
+	npx supabase --workdir infra start -x studio,gotrue,postgrest,mailpit,realtime,edge-runtime,logflare,vector,supavisor
 
 stop_infra:
 	npx supabase --workdir infra stop
@@ -27,6 +27,8 @@ build_sync:
 	poetry run unasync storage3 tests
 	sed -i '0,/SyncMock, /{s/SyncMock, //}' tests/_sync/test_bucket.py tests/_sync/test_client.py
 	sed -i 's/SyncMock/Mock/g' tests/_sync/test_bucket.py tests/_sync/test_client.py
+	sed -i 's/SyncClient/Client/g' storage3/_sync/client.py storage3/_sync/bucket.py storage3/_sync/file_api.py tests/_sync/test_bucket.py tests/_sync/test_client.py
+	sed -i 's/self\.session\.aclose/self\.session\.close/g' storage3/_sync/client.py
 
 sleep:
 	sleep 2

README.md

@@ -10,21 +10,22 @@ As it takes some effort to get the headers. We suggest that you use the storage
 
 
 ```python3
-from storage3 import create_client
+from storage3 import AsyncStorageClient
 
 url = "https://<your_supabase_id>.supabase.co/storage/v1"
 key = "<your api key>"
 headers = {"apiKey": key, "Authorization": f"Bearer {key}"}
 
-# pass in is_async=True to create an async client
-storage_client = create_client(url, headers, is_async=False)
+storage_client = AsyncStorageClient(url, headers)
 
-storage_client.list_buckets()
+async def get_buckets():
+  await storage_client.list_buckets()
 ```
 
 ### Uploading files
 When uploading files, make sure to set the correct mimetype by using the `file_options` argument:
 ```py
-storage_client.from_("bucket").upload("/folder/file.png", file_object, {"content-type": "image/png"})
+async def file_upload():
+  await storage_client.from_("bucket").upload("/folder/file.png", file_object, {"content-type": "image/png"})
 ```
 If no mime type is given, the default `text/plain` will be used.

poetry.lock

@@ -25,8 +25,9 @@ version = "0.11.3" # {x-release-please-version}
 httpx = {version = ">=0.26,<0.29", extras = ["http2"]}
 python = "^3.9"
 python-dateutil = "^2.8.2"
+deprecation = "^2.1.0"
 
-[tool.poetry.dev-dependencies]
+[tool.poetry.group.dev.dependencies]
 black = "^25.1.0"
 isort = "^6.0.1"
 pre-commit = "^4.2.0"
@@ -38,13 +39,14 @@ Sphinx = "^7.1.2"
 sphinx-press-theme = "^0.9.1"
 unasync-cli = "^0.0.9"
 coveralls = "^1.8.0"
-
-[tool.poetry.group.dev.dependencies]
 sphinx-toolbox = "^3.4.0"
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 addopts = "tests"
+filterwarnings = [
+    "ignore::DeprecationWarning", # ignore deprecation warnings globally
+]
 
 [build-system]
 build-backend = "poetry.core.masonry.api"

pyproject.toml

@@ -2,11 +2,10 @@
 
 from typing import Any, Optional
 
-from httpx import HTTPStatusError, Response
+from httpx import AsyncClient, HTTPStatusError, Response
 
 from ..exceptions import StorageApiError
 from ..types import CreateOrUpdateBucketOptions, RequestMethod
-from ..utils import AsyncClient
 from .file_api import AsyncBucket
 
 __all__ = ["AsyncStorageBucketAPI"]

storage3/_async/bucket.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from typing import Optional
+from warnings import warn
+
+from httpx import AsyncClient
 
 from storage3.constants import DEFAULT_TIMEOUT
 
-from ..utils import AsyncClient
 from ..version import __version__
 from .bucket import AsyncStorageBucketAPI
 from .file_api import AsyncBucketProxy
@@ -21,15 +23,46 @@ def __init__(
         self,
         url: str,
         headers: dict[str, str],
-        timeout: int = DEFAULT_TIMEOUT,
-        verify: bool = True,
+        timeout: Optional[int] = None,
+        verify: Optional[bool] = None,
         proxy: Optional[str] = None,
+        http_client: Optional[AsyncClient] = None,
     ) -> None:
         headers = {
             "User-Agent": f"supabase-py/storage3 v{__version__}",
             **headers,
         }
-        self.session = self._create_session(url, headers, timeout, verify, proxy)
+
+        if timeout is not None:
+            warn(
+                "The 'timeout' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if verify is not None:
+            warn(
+                "The 'verify' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if proxy is not None:
+            warn(
+                "The 'proxy' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        self.verify = bool(verify) if verify is not None else True
+        self.timeout = int(abs(timeout)) if timeout is not None else DEFAULT_TIMEOUT
+
+        self.session = self._create_session(
+            base_url=url,
+            headers=headers,
+            timeout=self.timeout,
+            verify=self.verify,
+            proxy=proxy,
+            http_client=http_client,
+        )
         super().__init__(self.session)
 
     def _create_session(
@@ -39,13 +72,19 @@ def _create_session(
         timeout: int,
         verify: bool = True,
         proxy: Optional[str] = None,
+        http_client: Optional[AsyncClient] = None,
     ) -> AsyncClient:
+        if http_client is not None:
+            http_client.base_url = base_url
+            http_client.headers.update({**headers})
+            return http_client
+
         return AsyncClient(
             base_url=base_url,
             headers=headers,
             timeout=timeout,
             proxy=proxy,
-            verify=bool(verify),
+            verify=verify,
             follow_redirects=True,
             http2=True,
         )
@@ -54,9 +93,6 @@ async def __aenter__(self) -> AsyncStorageClient:
         return self
 
     async def __aexit__(self, exc_type, exc, tb) -> None:
-        await self.aclose()
-
-    async def aclose(self) -> None:
         await self.session.aclose()
 
     def from_(self, id: str) -> AsyncBucketProxy:

storage3/_async/client.py

@@ -8,7 +8,7 @@
 from pathlib import Path
 from typing import Any, Literal, Optional, Union, cast
 
-from httpx import HTTPStatusError, Response
+from httpx import AsyncClient, HTTPStatusError, Response
 
 from ..constants import DEFAULT_FILE_OPTIONS, DEFAULT_SEARCH_OPTIONS
 from ..exceptions import StorageApiError
@@ -26,7 +26,7 @@
     UploadResponse,
     URLOptions,
 )
-from ..utils import AsyncClient, StorageException
+from ..utils import StorageException
 
 __all__ = ["AsyncBucket"]
 

storage3/_async/file_api.py

@@ -2,11 +2,10 @@
 
 from typing import Any, Optional
 
-from httpx import HTTPStatusError, Response
+from httpx import Client, HTTPStatusError, Response
 
 from ..exceptions import StorageApiError
 from ..types import CreateOrUpdateBucketOptions, RequestMethod
-from ..utils import SyncClient
 from .file_api import SyncBucket
 
 __all__ = ["SyncStorageBucketAPI"]
@@ -15,7 +14,7 @@
 class SyncStorageBucketAPI:
     """This class abstracts access to the endpoint to the Get, List, Empty, and Delete operations on a bucket"""
 
-    def __init__(self, session: SyncClient) -> None:
+    def __init__(self, session: Client) -> None:
         self._client = session
 
     def _request(

storage3/_sync/bucket.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
 from typing import Optional
+from warnings import warn
+
+from httpx import Client
 
 from storage3.constants import DEFAULT_TIMEOUT
 
-from ..utils import SyncClient
 from ..version import __version__
 from .bucket import SyncStorageBucketAPI
 from .file_api import SyncBucketProxy
@@ -21,15 +23,46 @@ def __init__(
         self,
         url: str,
         headers: dict[str, str],
-        timeout: int = DEFAULT_TIMEOUT,
-        verify: bool = True,
+        timeout: Optional[int] = None,
+        verify: Optional[bool] = None,
         proxy: Optional[str] = None,
+        http_client: Optional[Client] = None,
     ) -> None:
         headers = {
             "User-Agent": f"supabase-py/storage3 v{__version__}",
             **headers,
         }
-        self.session = self._create_session(url, headers, timeout, verify, proxy)
+
+        if timeout is not None:
+            warn(
+                "The 'timeout' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if verify is not None:
+            warn(
+                "The 'verify' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if proxy is not None:
+            warn(
+                "The 'proxy' parameter is deprecated. Please configure it in the http client instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        self.verify = bool(verify) if verify is not None else True
+        self.timeout = int(abs(timeout)) if timeout is not None else DEFAULT_TIMEOUT
+
+        self.session = self._create_session(
+            base_url=url,
+            headers=headers,
+            timeout=self.timeout,
+            verify=self.verify,
+            proxy=proxy,
+            http_client=http_client,
+        )
         super().__init__(self.session)
 
     def _create_session(
@@ -39,13 +72,19 @@ def _create_session(
         timeout: int,
         verify: bool = True,
         proxy: Optional[str] = None,
-    ) -> SyncClient:
-        return SyncClient(
+        http_client: Optional[Client] = None,
+    ) -> Client:
+        if http_client is not None:
+            http_client.base_url = base_url
+            http_client.headers.update({**headers})
+            return http_client
+
+        return Client(
             base_url=base_url,
             headers=headers,
             timeout=timeout,
             proxy=proxy,
-            verify=bool(verify),
+            verify=verify,
             follow_redirects=True,
             http2=True,
         )
@@ -54,10 +93,7 @@ def __enter__(self) -> SyncStorageClient:
         return self
 
     def __exit__(self, exc_type, exc, tb) -> None:
-        self.aclose()
-
-    def aclose(self) -> None:
-        self.session.aclose()
+        self.session.close()
 
     def from_(self, id: str) -> SyncBucketProxy:
         """Run a storage file operation.