arraylake 1.0.0__tar.gz → 1.0.2__tar.gz

{arraylake-1.0.0 → arraylake-1.0.2}/.gitignore

@@ -146,3 +146,6 @@ client/arraylake/_version.py
 
 # claude
 **/.claude/
+!/.claude/
+/.claude/*
+!/.claude/skills/

{arraylake-1.0.0 → arraylake-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arraylake
-Version: 1.0.0
+Version: 1.0.2
 Summary: Python client for ArrayLake
 Project-URL: Documentation, https://docs.earthmover.io/
 Project-URL: Changelog, https://docs.earthmover.io/changelog
@@ -16,10 +16,10 @@ Requires-Dist: donfig<1.0,>=0.7
 Requires-Dist: httpx<0.29,>=0.23
 Requires-Dist: icechunk<3.0.0,>=2.0.1
 Requires-Dist: numpy<3.0,>=1.23
-Requires-Dist: packaging<26.0,>=23.0
+Requires-Dist: packaging<27.0,>=23.0
 Requires-Dist: pydantic[email]<3.0,>=2.9
 Requires-Dist: python-dateutil<3.0,>=2.8
-Requires-Dist: rich<15.0,>=12.6
+Requires-Dist: rich<16.0,>=12.6
 Requires-Dist: ruamel-yaml<1.0,>=0.17
 Requires-Dist: structlog<26.0,>=24.1
 Requires-Dist: typer<1.0,>=0.12.0
@@ -27,6 +27,8 @@ Requires-Dist: zarr<4.0,>=3.1.0
 Provides-Extra: maximal
 Requires-Dist: cf-xarray>=0.10.4; extra == 'maximal'
 Requires-Dist: xarray[accel,etc,io,parallel]>=2024.10.0; extra == 'maximal'
+Provides-Extra: obstore
+Requires-Dist: obstore>=0.9.2; extra == 'obstore'
 Provides-Extra: xarray
 Requires-Dist: cf-xarray>=0.10.4; extra == 'xarray'
 Requires-Dist: xarray>=2024.10.0; extra == 'xarray'

{arraylake-1.0.0 → arraylake-1.0.2}/arraylake/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.0'
-__version_tuple__ = version_tuple = (1, 0, 0)
+__version__ = version = '1.0.2'
+__version_tuple__ = version_tuple = (1, 0, 2)
 
 __commit_id__ = commit_id = None

{arraylake-1.0.0 → arraylake-1.0.2}/arraylake/api_utils.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import asyncio
+import functools
 import json
 import os
 import random
+import uuid
 import warnings
 import weakref
 from collections.abc import AsyncGenerator, Callable, Generator, Mapping
@@ -82,6 +84,19 @@ def _get_proxy_from_env() -> str | None:
     return None
 
 
+@functools.cache
+def _get_session_id() -> str:
+    """Session ID for this Python process.
+
+    Propagated as the ``arraylake-session-id`` header on every outbound request and
+    baked into ``ArraylakeHttpClient._default_headers`` at construction time, so it
+    rides along to dask workers via the existing pickle path on the client.
+    """
+    session_id = str(uuid.uuid4())
+    logger.info("arraylake session id: %s", session_id)
+    return session_id
+
+
 # this is a hashable key to use for the global client cache
 # we only need one client for each key
 @dataclass(eq=True, frozen=True)
@@ -302,6 +317,7 @@ class ArraylakeHttpClient:
             # technically we don't enforce this, for now it's for debugging purposes
             "client-name": "arraylake-python-client",
             "client-version": arraylake.__version__,
+            "arraylake-session-id": _get_session_id(),
         }
 
         self._async_lock = asyncio.Lock()

{arraylake-1.0.0 → arraylake-1.0.2}/arraylake/cli/auth.py

@@ -101,14 +101,7 @@ def token():
         raise typer.Exit(code=1)
     try:
         token_value = handler.tokens.id_token.get_secret_value()
-        rich_console.print(
-            Panel(
-                f"[dim]{token_value}[/dim]",
-                title="id_token",
-                subtitle=f"[link=https://jwt.io/#id_token={token_value}][blue]:link: Inspect with JWT.io[/blue][/link]",
-                subtitle_align="right",
-            )
-        )
+        typer.echo(token_value)
     except (AuthException, AttributeError):
         rich_console.print(Align(f"[yellow]{NOT_LOGGED_IN_MESSAGE}[/yellow]", align="center"))
         raise typer.Exit(code=1)

{arraylake-1.0.0 → arraylake-1.0.2}/arraylake/client.py

@@ -18,7 +18,7 @@ import warnings
 from collections.abc import AsyncGenerator, Callable, Generator, Mapping
 from datetime import UTC
 from functools import partial
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 from urllib.parse import urlparse
 from uuid import UUID
 
@@ -83,6 +83,9 @@ from arraylake.types import (
 )
 from arraylake.types import Repo as RepoModel
 
+if TYPE_CHECKING:
+    import obstore as obs
+
 logger = get_logger(__name__)
 
 _VALID_NAME = r"(\w[\w\.\-_]+)"
@@ -243,52 +246,67 @@ class AsyncClient:
         azure_creds = await mstore.get_azure_container_credentials_from_repo(repo_name)
         return azure_creds
 
-    async def _get_s3_delegated_credentials_from_bucket(self, org: OrgName, nickname: BucketNickname) -> S3Credentials:
-        """Get delegated credentials for a S3 bucket. These credentials are scoped
-        to read-only.
+    async def _get_s3_delegated_credentials_from_bucket(
+        self, org: OrgName, nickname: BucketNickname, access: Literal["read", "write"] = "read"
+    ) -> S3Credentials:
+        """Get delegated credentials for an S3 bucket.
+
+        Defaults to read-only credentials. Pass ``access="write"`` to request read+write
+        credentials; the caller must have ``CAN_MANAGE_USERS`` on the org.
 
         Args:
             org: Name of the organization that the bucket belongs to.
             nickname: Nickname of the bucket.
+            access: ``"read"`` (default) or ``"write"``.
 
         Returns:
             S3Credentials: Temporary credentials for the S3 bucket.
         """
         mstore = self._metastore_for_org(org)
         bucket_id = await self._bucket_id_for_nickname(mstore, nickname)
-        s3_creds = await mstore.get_s3_bucket_credentials_from_bucket(bucket_id)
+        s3_creds = await mstore.get_s3_bucket_credentials_from_bucket(bucket_id, access=access)
         return s3_creds
 
-    async def _get_gcs_delegated_credentials_from_bucket(self, org: RepoName, nickname: BucketNickname) -> GSCredentials:
-        """Get delegated credentials for a GCS bucket. These credentials are scoped
-        to read-only.
+    async def _get_gcs_delegated_credentials_from_bucket(
+        self, org: RepoName, nickname: BucketNickname, access: Literal["read", "write"] = "read"
+    ) -> GSCredentials:
+        """Get delegated credentials for a GCS bucket.
+
+        Defaults to read-only credentials. Pass ``access="write"`` to request read+write
+        credentials; the caller must have ``CAN_MANAGE_USERS`` on the org.
 
         Args:
             org: Name of the organization that the bucket belongs to.
             nickname: Nickname of the bucket.
+            access: ``"read"`` (default) or ``"write"``.
 
         Returns:
             GSCredentials: Temporary credentials for the GCS bucket.
         """
         mstore = self._metastore_for_org(org)
         bucket_id = await self._bucket_id_for_nickname(mstore, nickname)
-        gcs_creds = await mstore.get_gs_bucket_credentials_from_bucket(bucket_id)
+        gcs_creds = await mstore.get_gs_bucket_credentials_from_bucket(bucket_id, access=access)
         return gcs_creds
 
-    async def _get_azure_delegated_credentials_from_bucket(self, org: RepoName, nickname: BucketNickname) -> AzureCredentials:
-        """Get delegated credentials for an Azure Blob Storage container. These credentials are scoped
-        to read-only.
+    async def _get_azure_delegated_credentials_from_bucket(
+        self, org: RepoName, nickname: BucketNickname, access: Literal["read", "write"] = "read"
+    ) -> AzureCredentials:
+        """Get delegated credentials for an Azure Blob Storage container.
+
+        Defaults to read-only credentials. Pass ``access="write"`` to request read+write
+        credentials; the caller must have ``CAN_MANAGE_USERS`` on the org.
 
         Args:
             org: Name of the organization that the bucket belongs to.
             nickname: Nickname of the bucket.
+            access: ``"read"`` (default) or ``"write"``.
 
         Returns:
             AzureCredentials: Temporary credentials for the Azure Blob Storage container.
         """
         mstore = self._metastore_for_org(org)
         bucket_id = await self._bucket_id_for_nickname(mstore, nickname)
-        azure_creds = await mstore.get_azure_container_credentials_from_bucket(bucket_id)
+        azure_creds = await mstore.get_azure_container_credentials_from_bucket(bucket_id, access=access)
         return azure_creds
 
     def _get_icechunk_s3_credentials_refresh_function_for_repo(self, org: OrgName, repo_name: RepoName) -> icechunk.S3StaticCredentials:
@@ -394,28 +412,32 @@ class AsyncClient:
         bucket: BucketResponse,
         org: OrgName,
         repo_name: RepoName | None,
+        bucket_access: Literal["read", "write"] = "read",
     ) -> TempCredentials | None:
         """Checks if the bucket is configured for delegated or HMAC credentials and gets the
         credentials if it is configured.
 
         Returns None if delegated or HMAC credentials are not configured for the bucket.
+
+        ``bucket_access`` only applies when ``repo_name`` is None (the bucket-scoped path);
+        repo-scoped credential fetches always inherit the caller's permissions on the repo.
         """
         if _use_delegated_credentials(bucket):
             if bucket.platform == "s3" or _is_r2_bucket(bucket):
                 if repo_name:
                     return await self._get_s3_delegated_credentials_from_repo(org, repo_name)
                 else:
-                    return await self._get_s3_delegated_credentials_from_bucket(org, bucket.nickname)
+                    return await self._get_s3_delegated_credentials_from_bucket(org, bucket.nickname, access=bucket_access)
             elif bucket.platform == "gs":
                 if repo_name:
                     return await self._get_gcs_delegated_credentials_from_repo(org, repo_name)
                 else:
-                    return await self._get_gcs_delegated_credentials_from_bucket(org, bucket.nickname)
+                    return await self._get_gcs_delegated_credentials_from_bucket(org, bucket.nickname, access=bucket_access)
             elif bucket.platform == "azure":
                 if repo_name:
                     return await self._get_azure_delegated_credentials_from_repo(org, repo_name)
                 else:
-                    return await self._get_azure_delegated_credentials_from_bucket(org, bucket.nickname)
+                    return await self._get_azure_delegated_credentials_from_bucket(org, bucket.nickname, access=bucket_access)
             else:
                 raise ValueError(f"Unsupported platform for delegated credentials: {bucket.platform}")
         elif _use_hmac_credentials(bucket):
@@ -558,16 +580,17 @@ class AsyncClient:
             if response.virtual_chunk_credentials:
                 credentials_map: dict[str, icechunk.AnyS3Credential | icechunk.AnyGcsCredential | icechunk.AnyAzureCredential | None] = {}
                 for vcc_prefix, vcc_creds in response.virtual_chunk_credentials.items():
-                    # Handle runtime VCCs (e.g., filtered subscriptions) - create VCC on the fly
+                    # Create VCC objects for all server-provided VCCs, not just runtime ones,
+                    # because icechunk's config merge replaces virtual_chunk_containers
+                    # rather than extending them.
+                    store_config = vcc_creds.to_vcc_store_config(user_id=UUID(response.principal_id))
+                    container = icechunk.VirtualChunkContainer(
+                        url_prefix=vcc_prefix,
+                        store=store_config,
+                    )
                     if vcc_creds.runtime_vcc_name is not None:
-                        bucket_config = await self.get_bucket_config(org=vcc_creds.org, nickname=vcc_creds.bucket_nickname)
-                        store_config = bucket_config.to_vcc_store_config(user_id=UUID(response.principal_id))
-                        container = icechunk.VirtualChunkContainer(
-                            url_prefix=vcc_prefix,
-                            store=store_config,
-                        )
                         container.name = vcc_creds.runtime_vcc_name
-                        config.set_virtual_chunk_container(container)
+                    config.set_virtual_chunk_container(container)
 
                     # TODO: build refresh closures here using vcc_creds.org, vcc_creds.bucket_nickname,
                     # and vcc_creds.platform so that credentials can be refreshed when they expire. (See https://github.com/earth-mover/arraylake/issues/5122)
@@ -1264,13 +1287,42 @@ class AsyncClient:
             raise BucketNotFoundError(nickname)
         return bucket_id
 
-    def _make_bucket_config(self, *, nickname: BucketNickname, uri: str, extra_config: dict | None, auth_config: dict | None) -> dict:
+    def _make_bucket_config(
+        self,
+        *,
+        nickname: BucketNickname,
+        uri: str,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        use_ssl: bool | None = None,
+        force_path_style: bool | None = None,
+        extra_config: dict | None = None,
+        auth_config: dict | None = None,
+    ) -> dict:
         if not nickname:
             raise ValueError("nickname must be specified if uri is provided.")
 
+        # Build extra_config from explicit parameters, with extra_config dict as fallback
+        # for backwards compatibility. Explicit parameters take precedence.
+        merged_extra_config: dict[str, str | bool] = {}
+        if extra_config is not None:
+            warnings.warn(
+                "Passing 'extra_config' as a dict is deprecated. "
+                "Use the explicit keyword arguments instead: region_name, endpoint_url, use_ssl, force_path_style.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+            merged_extra_config.update(extra_config)
+        if region_name is not None:
+            merged_extra_config["region_name"] = region_name
+        if endpoint_url is not None:
+            merged_extra_config["endpoint_url"] = endpoint_url
+        if use_ssl is not None:
+            merged_extra_config["use_ssl"] = use_ssl
+        if force_path_style is not None:
+            merged_extra_config["force_path_style"] = force_path_style
+
         # unpack optionals
-        if extra_config is None:
-            extra_config = {}
         if auth_config is None:
             auth_config = {"method": "anonymous"}
 
@@ -1279,7 +1331,7 @@ class AsyncClient:
         platform: Literal["s3", "gs", "s3-compatible", "azure"] | None = (
             "s3" if res.scheme == "s3" else "gs" if res.scheme == "gs" else "azure" if res.scheme == "az" else None
         )
-        if platform == "s3" and extra_config.get("endpoint_url"):
+        if platform == "s3" and merged_extra_config.get("endpoint_url"):
             platform = "s3-compatible"
         if platform not in ["s3", "gs", "s3-compatible", "azure"]:
             raise ValueError(f"Invalid platform {platform} for uri {uri}")
@@ -1313,26 +1365,62 @@ class AsyncClient:
             name=name,
             prefix=prefix,
             nickname=nickname,
-            extra_config=extra_config,
+            extra_config=merged_extra_config,
             auth_config=auth_config,
         )
 
     async def create_bucket_config(
-        self, *, org: OrgName, nickname: BucketNickname, uri: URI, extra_config: dict | None = None, auth_config: dict | None = None
+        self,
+        *,
+        org: OrgName,
+        nickname: BucketNickname,
+        uri: URI,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        use_ssl: bool | None = None,
+        force_path_style: bool | None = None,
+        extra_config: dict | None = None,
+        auth_config: dict | None = None,
     ) -> BucketResponse:
-        """Create a new bucket config entry
+        """Create a new bucket config entry.
 
         NOTE: This does not create any actual buckets in the object store.
 
         Args:
-            org: Name of the org
-            nickname: bucket nickname (example: ours3-bucket`)
+            org: Name of the org.
+            nickname: Bucket nickname (e.g. ``"my-s3-bucket"``).
             uri: The URI of the object store, of the form
-                platform://bucket_name[/prefix].
-            extra_config: dictionary of additional config to set on bucket config
-            auth_config: dictionary of auth parameters, must include "method" key, default is `{"method": "anonymous"}`
-        """
-        validated = NewBucket(**self._make_bucket_config(nickname=nickname, uri=uri, extra_config=extra_config, auth_config=auth_config))
+                ``platform://bucket_name[/prefix]`` (e.g. ``"s3://my-bucket/prefix"``).
+            region_name: Cloud region for the bucket (e.g. ``"us-west-2"``).
+                Required for S3 buckets.
+            endpoint_url: Custom endpoint URL for S3-compatible storage
+                (e.g. ``"https://account-id.r2.cloudflarestorage.com"``).
+                Setting this automatically marks the bucket as S3-compatible.
+            use_ssl: Whether to use HTTPS for storage connections.
+                Defaults to ``True``. Set to ``False`` for local or insecure endpoints.
+                Only applies to S3-type buckets.
+            force_path_style: Use path-style URLs (``endpoint/bucket``) instead of
+                virtual-hosted style (``bucket.endpoint``). Defaults to ``False`` when
+                ``use_ssl=True``, ``True`` when ``use_ssl=False``. Often required for
+                S3-compatible storage. Only applies to S3-type buckets.
+            extra_config: Dictionary of additional config options. Prefer using the
+                explicit parameters above when possible. Keys set here are overridden
+                by any explicit parameters that are also provided.
+            auth_config: Dictionary of auth parameters. Must include a ``"method"`` key.
+                Defaults to ``{"method": "anonymous"}``.
+        """
+        validated = NewBucket(
+            **self._make_bucket_config(
+                nickname=nickname,
+                uri=uri,
+                region_name=region_name,
+                endpoint_url=endpoint_url,
+                use_ssl=use_ssl,
+                force_path_style=force_path_style,
+                extra_config=extra_config,
+                auth_config=auth_config,
+            )
+        )
         mstore = self._metastore_for_org(org)
         bucket = await mstore.create_bucket_config(validated)
         return bucket
@@ -1359,6 +1447,42 @@ class AsyncClient:
         bucket = await mstore.get_bucket_config(bucket_id)
         return bucket
 
+    async def get_obstore_for_bucket(
+        self, *, org: OrgName, nickname: BucketNickname, access: Literal["read", "write"] = "read"
+    ) -> obs.store.ObjectStore:
+        """Get an obstore ObjectStore for the named bucket.
+
+        Resolves the bucket nickname, fetches scoped credentials, and returns an
+        ``obstore.store.S3Store``, ``GCSStore``, or ``AzureStore`` ready for use.
+
+        Defaults to read-only credentials. Pass ``access="write"`` to request a
+        read+write store; that variant requires ``CAN_MANAGE_USERS`` on the org.
+
+        Requires the optional ``obstore`` extra (``pip install arraylake[obstore]``).
+
+        Args:
+            org: Name of the org that owns the bucket.
+            nickname: Nickname of the bucket config.
+            access: ``"read"`` (default) or ``"write"``.
+
+        Returns:
+            An obstore ObjectStore scoped to the bucket and its configured prefix.
+
+        Raises:
+            ImportError: If the optional ``obstore`` extra is not installed.
+        """
+        # Fail fast before making any API calls if obstore isn't available.
+        try:
+            import obstore  # noqa: F401
+        except ImportError as e:
+            raise ImportError(
+                "The 'obstore' package is required for this functionality but is not installed. "
+                "Install it with: pip install 'arraylake[obstore]'"
+            ) from e
+        bucket = await self.get_bucket_config(org=org, nickname=nickname)
+        creds = await self._maybe_get_credentials_for_icechunk(bucket, org, repo_name=None, bucket_access=access)
+        return bucket.as_obstore_store(creds)
+
     async def list_bucket_configs(self, org: OrgName) -> list[BucketResponse]:
         """List all bucket config entries
 
@@ -1906,22 +2030,56 @@ class Client:
         return sync(self.aclient.delete_repo, name, imsure=imsure, imreallysure=imreallysure)
 
     def create_bucket_config(
-        self, *, org: OrgName, nickname: BucketNickname, uri: URI, extra_config: dict | None = None, auth_config: dict | None = None
+        self,
+        *,
+        org: OrgName,
+        nickname: BucketNickname,
+        uri: URI,
+        region_name: str | None = None,
+        endpoint_url: str | None = None,
+        use_ssl: bool | None = None,
+        force_path_style: bool | None = None,
+        extra_config: dict | None = None,
+        auth_config: dict | None = None,
     ) -> BucketResponse:
-        """Create a new bucket config entry
+        """Create a new bucket config entry.
 
         NOTE: This does not create any actual buckets in the object store.
 
         Args:
-            org: Name of the org
-            nickname: bucket nickname (example: our-s3-bucket)
+            org: Name of the org.
+            nickname: Bucket nickname (e.g. ``"my-s3-bucket"``).
             uri: The URI of the object store, of the form
-                platform://bucket_name[/prefix].
-            extra_config: dictionary of additional config to set on bucket config
-            auth_config: dictionary of auth parameters, must include "method" key, default is `{"method": "anonymous"}`
+                ``platform://bucket_name[/prefix]`` (e.g. ``"s3://my-bucket/prefix"``).
+            region_name: Cloud region for the bucket (e.g. ``"us-west-2"``).
+                Required for S3 buckets.
+            endpoint_url: Custom endpoint URL for S3-compatible storage
+                (e.g. ``"https://account-id.r2.cloudflarestorage.com"``).
+                Setting this automatically marks the bucket as S3-compatible.
+            use_ssl: Whether to use HTTPS for storage connections.
+                Defaults to ``True``. Set to ``False`` for local or insecure endpoints.
+                Only applies to S3-type buckets.
+            force_path_style: Use path-style URLs (``endpoint/bucket``) instead of
+                virtual-hosted style (``bucket.endpoint``). Defaults to ``False`` when
+                ``use_ssl=True``, ``True`` when ``use_ssl=False``. Often required for
+                S3-compatible storage. Only applies to S3-type buckets.
+            extra_config: Dictionary of additional config options. Prefer using the
+                explicit parameters above when possible. Keys set here are overridden
+                by any explicit parameters that are also provided.
+            auth_config: Dictionary of auth parameters. Must include a ``"method"`` key.
+                Defaults to ``{"method": "anonymous"}``.
         """
         return sync(
-            self.aclient.create_bucket_config, org=org, nickname=nickname, uri=uri, extra_config=extra_config, auth_config=auth_config
+            self.aclient.create_bucket_config,
+            org=org,
+            nickname=nickname,
+            uri=uri,
+            region_name=region_name,
+            endpoint_url=endpoint_url,
+            use_ssl=use_ssl,
+            force_path_style=force_path_style,
+            extra_config=extra_config,
+            auth_config=auth_config,
         )
 
     def set_default_bucket_config(self, *, org: OrgName, nickname: BucketNickname) -> None:
@@ -1942,6 +2100,26 @@ class Client:
         """
         return sync(self.aclient.get_bucket_config, org=org, nickname=nickname)
 
+    def get_obstore_for_bucket(
+        self, *, org: OrgName, nickname: BucketNickname, access: Literal["read", "write"] = "read"
+    ) -> obs.store.ObjectStore:
+        """Get an obstore ObjectStore for the named bucket.
+
+        Defaults to read-only credentials. Pass ``access="write"`` to request a
+        read+write store; that variant requires ``CAN_MANAGE_USERS`` on the org.
+
+        Requires the optional ``obstore`` extra (``pip install arraylake[obstore]``).
+
+        Args:
+            org: Name of the org that owns the bucket.
+            nickname: Nickname of the bucket config.
+            access: ``"read"`` (default) or ``"write"``.
+
+        Returns:
+            An obstore ObjectStore scoped to the bucket and its configured prefix.
+        """
+        return sync(self.aclient.get_obstore_for_bucket, org=org, nickname=nickname, access=access)
+
     def list_bucket_configs(self, org: OrgName) -> list[BucketResponse]:
         """List all buckets for the specified org
 

{arraylake-1.0.0 → arraylake-1.0.2}/arraylake/metastore/http_metastore.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field
-from typing import Any
+from typing import Any, Literal
 from uuid import UUID
 
 from pydantic import TypeAdapter
@@ -300,21 +300,32 @@ class HttpMetastore(ArraylakeHttpClient, Metastore):
         handle_response(response)
         return AzureCredentials.model_validate_json(response.content)
 
-    async def get_s3_bucket_credentials_from_bucket(self, bucket_id: UUID) -> S3Credentials:
-        """Gets the S3 credentials for a bucket. Credentials will be scoped to read-only."""
-        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials")
+    async def get_s3_bucket_credentials_from_bucket(self, bucket_id: UUID, access: Literal["read", "write"] = "read") -> S3Credentials:
+        """Gets the S3 credentials for a bucket.
+
+        Defaults to read-only credentials; pass ``access="write"`` for read+write.
+        """
+        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials", params={"access": access})
         handle_response(response)
         return S3Credentials.model_validate_json(response.content)
 
-    async def get_gs_bucket_credentials_from_bucket(self, bucket_id: UUID) -> GSCredentials:
-        """Gets the GCS credentials for a bucket. Credentials will be scoped to read-only."""
-        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials")
+    async def get_gs_bucket_credentials_from_bucket(self, bucket_id: UUID, access: Literal["read", "write"] = "read") -> GSCredentials:
+        """Gets the GCS credentials for a bucket.
+
+        Defaults to read-only credentials; pass ``access="write"`` for read+write.
+        """
+        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials", params={"access": access})
         handle_response(response)
         return GSCredentials.model_validate_json(response.content)
 
-    async def get_azure_container_credentials_from_bucket(self, bucket_id: UUID) -> AzureCredentials:
-        """Gets the Azure credentials for a bucket. Credentials will be scoped to read-only."""
-        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials")
+    async def get_azure_container_credentials_from_bucket(
+        self, bucket_id: UUID, access: Literal["read", "write"] = "read"
+    ) -> AzureCredentials:
+        """Gets the Azure credentials for a bucket.
+
+        Defaults to read-only credentials; pass ``access="write"`` for read+write.
+        """
+        response = await self._request("GET", f"/orgs/{self._config.org}/buckets/{bucket_id}/credentials", params={"access": access})
         handle_response(response)
         return AzureCredentials.model_validate_json(response.content)