### Install storage3 via pip

Source: https://github.com/supabase/storage-py/blob/main/docs/index.rst

Use this command to install the library using the pip package manager.

```bash
pip install storage3
```

--------------------------------

### Install storage3 via poetry

Source: https://github.com/supabase/storage-py/blob/main/docs/index.rst

Use this command to add the library to your project using poetry.

```bash
poetry add storage3
```

--------------------------------

### Download File Examples

Source: https://context7.com/supabase/storage-py/llms.txt

Demonstrates downloading files from a Supabase Storage bucket. Supports basic downloads to bytes and includes options for applying image transformations like resizing and quality adjustments on-the-fly.

```python
from storage3 import AsyncStorageClient

async def download_file_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # Simple download
        content = await bucket.download("users/123/avatar.png")
        with open("/local/path/avatar.png", "wb") as f:
            f.write(content)

        # Download with image transformation
        thumbnail = await bucket.download(
            "users/123/avatar.png",
            options={
                "transform": {
                    "width": 100,
                    "height": 100,
                    "resize": "cover",
                    "quality": 80
                }
            }
        )

        return content
```

--------------------------------

### Upload File Examples

Source: https://context7.com/supabase/storage-py/llms.txt

Demonstrates uploading files to a Supabase Storage bucket. Supports uploads from file paths, bytes, and includes options for content-type, cache control, upsert, and custom metadata.

```python
from storage3 import AsyncStorageClient
from pathlib import Path

async def upload_file_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # Upload from file path
        result = await bucket.upload(
            path="users/123/avatar.png",
            file="/local/path/to/image.png",
            file_options={
                "content-type": "image/png",
                "cache-control": "3600"
            }
        )
        print(f"Uploaded: {result.path}, Key: {result.full_path}")

        # Upload from bytes
        image_bytes = b"binary image data here..."
        result = await bucket.upload(
            path="users/456/profile.jpg",
            file=image_bytes,
            file_options={"content-type": "image/jpeg"}
        )

        # Upload with upsert (overwrite if exists)
        result = await bucket.upload(
            path="users/123/avatar.png",
            file="/path/to/new-image.png",
            file_options={
                "content-type": "image/png",
                "upsert": "true"
            }
        )

        # Upload with custom metadata
        result = await bucket.upload(
            path="documents/report.pdf",
            file="/path/to/report.pdf",
            file_options={
                "content-type": "application/pdf",
                "metadata": {
                    "author": "John Doe",
                    "version": "1.0"
                }
            }
        )

        return result
```

--------------------------------

### Get File Info

Source: https://context7.com/supabase/storage-py/llms.txt

Retrieves metadata information for a specific file. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def get_file_info(file_path: str):
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        info = await bucket.info(file_path)
        print(f"File info: {info}")
        return info

# Example
info = await get_file_info("users/123/avatar.png")
```

--------------------------------

### GET /bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Retrieves a list of all storage buckets in the Supabase project.

```APIDOC
## GET /bucket

### Description
Retrieves all storage buckets in your Supabase project. Returns a list of bucket objects containing metadata like id, name, owner, and access settings.

### Method
GET

### Endpoint
/bucket

### Response
#### Success Response (200)
- **buckets** (list) - A list of bucket objects containing metadata.
```

--------------------------------

### Get File Info

Source: https://context7.com/supabase/storage-py/llms.txt

Retrieves metadata information for a specific file.

```APIDOC
## Get File Info

Retrieves metadata information for a specific file.

### Method
GET

### Endpoint
`/storage/v1/object/info/{bucketName}/{filePath}`

### Parameters
#### Path Parameters
- **filePath** (string) - Required - The full path to the file within the bucket.

### Response
#### Success Response (200)
- **info** (object) - An object containing the file's metadata, such as `name`, `id`, `updated_at`, `created_at`, `last_accessed_at`, `metadata`, etc.

### Request Example
```python
from storage3 import AsyncStorageClient

async def get_file_info(file_path: str):
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        info = await bucket.info(file_path)
        print(f"File info: {info}")
        return info

# Example
info = await get_file_info("users/123/avatar.png")
```
```

--------------------------------

### GET /bucket/{id}

Source: https://context7.com/supabase/storage-py/llms.txt

Retrieves details of a specific storage bucket by its unique identifier.

```APIDOC
## GET /bucket/{id}

### Description
Retrieves details of a specific storage bucket by its unique identifier. Returns a bucket object with complete metadata.

### Method
GET

### Endpoint
/bucket/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bucket.

### Response
#### Success Response (200)
- **bucket** (object) - The bucket object containing metadata.
```

--------------------------------

### Get Public URL for Files

Source: https://context7.com/supabase/storage-py/llms.txt

Generates a public URL for files in public buckets. Supports image transformations and download triggers. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def get_public_url_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("public-images")

        # Basic public URL
        public_url = await bucket.get_public_url("photos/landscape.jpg")
        print(f"Public URL: {public_url}")

        # Public URL with transformation
        thumbnail_url = await bucket.get_public_url(
            "photos/landscape.jpg",
            options={
                "transform": {
                    "width": 300,
                    "height": 200,
                    "resize": "cover",
                    "quality": 75,
                    "format": "avif"
                }
            }
        )

        # Public URL with download trigger
        download_url = await bucket.get_public_url(
            "files/document.pdf",
            options={"download": "my-document.pdf"}
        )

        return public_url
```

--------------------------------

### GET /get_public_url

Source: https://context7.com/supabase/storage-py/llms.txt

Generates a public URL for files in public buckets, supporting image transformations and download triggers.

```APIDOC
## GET /get_public_url

### Description
Generates a public URL for files in public buckets. Supports image transformations and download triggers.

### Parameters
#### Path Parameters
- **path** (string) - Required - The file path in the bucket

#### Query Parameters
- **options** (object) - Optional - Configuration for transformations or download
```

--------------------------------

### Client Initialization

Source: https://github.com/supabase/storage-py/blob/main/docs/api/client.rst

Documentation for creating a new storage client instance.

```APIDOC
## storage3.create_client

### Description
The entrypoint to the library. Use this function to create an instance of the storage client to interact with the Storage API.

### Method
Function Call

### Parameters
- **url** (str) - Required - The URL of the Supabase storage service.
- **headers** (dict) - Optional - Custom headers to include in requests.
```

--------------------------------

### Instantiate Storage Client

Source: https://context7.com/supabase/storage-py/llms.txt

Demonstrates creating synchronous and asynchronous clients using the factory function or direct class instantiation, including context manager usage.

```python
from storage3 import create_client, AsyncStorageClient, SyncStorageClient

# Configuration
url = "https://your-project.supabase.co/storage/v1"
key = "your-api-key"
headers = {"apiKey": key, "Authorization": f"Bearer {key}"}

# Create async client
async_client = create_client(url, headers, is_async=True)

# Create sync client
sync_client = create_client(url, headers, is_async=False)

# Or instantiate directly
async_storage = AsyncStorageClient(url, headers)
sync_storage = SyncStorageClient(url, headers)

# Using context manager for automatic cleanup
async with AsyncStorageClient(url, headers) as client:
    buckets = await client.list_buckets()

with SyncStorageClient(url, headers) as client:
    buckets = client.list_buckets()
```

--------------------------------

### Initialize AsyncStorageClient

Source: https://github.com/supabase/storage-py/blob/main/README.md

Configures the client with the Supabase storage URL and authentication headers.

```python3
from storage3 import AsyncStorageClient

url = "https://<your_supabase_id>.supabase.co/storage/v1"
key = "<your api key>"
headers = {"apiKey": key, "Authorization": f"Bearer {key}"}

storage_client = AsyncStorageClient(url, headers)

async def get_buckets():
  await storage_client.list_buckets()
```

--------------------------------

### Create New Storage Bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Initializes a new bucket with specific access controls and file constraints.

```python
from storage3 import AsyncStorageClient

async def create_new_bucket():
    async with AsyncStorageClient(url, headers) as client:
        # Create a public bucket with restrictions
        result = await client.create_bucket(
            id="user-uploads",
            name="User Uploads",
            options={
                "public": True,
                "file_size_limit": 5242880,  # 5MB in bytes
                "allowed_mime_types": ["image/png", "image/jpeg", "image/gif"]
            }
        )
        print(f"Created bucket: {result}")
        return result

# Create a private bucket with default settings
async def create_private_bucket():
    async with AsyncStorageClient(url, headers) as client:
        result = await client.create_bucket(
            id="private-documents",
            options={"public": False}
        )
        return result
```

--------------------------------

### POST /bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Creates a new storage bucket with configurable options.

```APIDOC
## POST /bucket

### Description
Creates a new storage bucket with configurable options including public/private access, file size limits, and allowed MIME types.

### Method
POST

### Endpoint
/bucket

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier for the bucket.
- **name** (string) - Optional - Display name for the bucket.
- **options** (object) - Optional - Configuration object containing public, file_size_limit, and allowed_mime_types.

### Response
#### Success Response (200)
- **result** (object) - The created bucket metadata.
```

--------------------------------

### Create Supabase Storage Client

Source: https://github.com/supabase/storage-py/blob/main/docs/api/client.rst

Instantiate the synchronous client to interact with the Supabase Storage API. Requires your Supabase URL and anon key.

```python
from storage3 import create_client

url = "YOUR_SUPABASE_URL"
anon_key = "YOUR_SUPABASE_ANON_KEY"

client = create_client(url, anon_key)
```

--------------------------------

### AsyncStorageClient

Source: https://github.com/supabase/storage-py/blob/main/docs/api/client.rst

Documentation for the AsyncStorageClient class and its members.

```APIDOC
## storage3.AsyncStorageClient

### Description
An asynchronous client class for interacting with Supabase Storage.

### Members
- Inherits all members from the base storage client implementation.
```

--------------------------------

### Supabase Storage Client Overview

Source: https://github.com/supabase/storage-py/blob/main/docs/api/index.rst

Overview of the Supabase Storage Python client structure and usage.

```APIDOC
## Supabase Storage Python Client

### Description
The library provides a consistent interface for interacting with Supabase Storage. Both synchronous and asynchronous clients are available, sharing the same method signatures.

### Modules
- **Client**: Core client initialization and configuration.
- **Bucket**: Methods for managing storage buckets.
- **Types**: Definitions for data structures used within the library.
```

--------------------------------

### AsyncBucketProxy API

Source: https://github.com/supabase/storage-py/blob/main/docs/api/bucket.rst

Documentation for the AsyncBucketProxy class, which acts as a proxy for bucket operations.

```APIDOC
## AsyncBucketProxy

### Description
Provides an asynchronous proxy interface for bucket-level operations within the Supabase storage system.

### Methods
- Inherits all members from the base storage file API classes.
```

--------------------------------

### AsyncBucket API

Source: https://github.com/supabase/storage-py/blob/main/docs/api/bucket.rst

Documentation for the AsyncBucket class, which provides methods for interacting with files in a specific storage bucket.

```APIDOC
## AsyncBucket

### Description
Represents an asynchronous interface for interacting with a specific storage bucket in Supabase.

### Methods
- Inherits all members from the base storage file API classes.
```

--------------------------------

### List Files in Bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Lists all files within a bucket. Supports filtering, pagination, and sorting. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def list_files_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # List all files in root
        files = await bucket.list()
        for file in files:
            print(f"File: {file.get('name')}, Size: {file.get('metadata', {}).get('size')}")

        # List files in a specific folder
        files = await bucket.list(path="users/123")

        # List with pagination and sorting
        files = await bucket.list(
            path="documents",
            options={
                "limit": 100,
                "offset": 0,
                "sortBy": {
                    "column": "created_at",
                    "order": "desc"
                },
                "search": "report"  # Filter by filename
            }
        )

        return files
```

--------------------------------

### Copy File

Source: https://context7.com/supabase/storage-py/llms.txt

Creates a copy of a file at a new path within the same bucket. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def copy_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        result = await bucket.copy(
            from_path="users/123/avatar.png",
            to_path="users/123/avatar-backup.png"
        )
        print(f"File copied: {result}")
        return result
```

--------------------------------

### List Storage Buckets

Source: https://context7.com/supabase/storage-py/llms.txt

Retrieves metadata for all buckets in the project using both asynchronous and synchronous methods.

```python
from storage3 import AsyncStorageClient

url = "https://your-project.supabase.co/storage/v1"
headers = {"apiKey": "your-key", "Authorization": "Bearer your-key"}

async def list_all_buckets():
    async with AsyncStorageClient(url, headers) as client:
        buckets = await client.list_buckets()
        for bucket in buckets:
            print(f"Bucket: {bucket.name}")
            print(f"  ID: {bucket.id}")
            print(f"  Public: {bucket.public}")
            print(f"  Created: {bucket.created_at}")
            print(f"  File size limit: {bucket.file_size_limit}")
            print(f"  Allowed MIME types: {bucket.allowed_mime_types}")
        return buckets

# Sync version
from storage3 import SyncStorageClient

def list_buckets_sync():
    with SyncStorageClient(url, headers) as client:
        return client.list_buckets()
```

--------------------------------

### Async Supabase Storage Client

Source: https://github.com/supabase/storage-py/blob/main/docs/api/client.rst

Use the AsyncStorageClient for asynchronous operations with the Supabase Storage API. Ensure you have your Supabase URL and anon key.

```python
from storage3 import AsyncStorageClient

url = "YOUR_SUPABASE_URL"
anon_key = "YOUR_SUPABASE_ANON_KEY"

async_client = AsyncStorageClient(url, anon_key)
```

--------------------------------

### Upload to Signed URL

Source: https://context7.com/supabase/storage-py/llms.txt

Uploads a file using a previously generated signed upload URL and token. Requires `AsyncStorageClient` and a local file path.

```python
from storage3 import AsyncStorageClient

async def upload_with_signed_url():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("uploads")

        # First, create the signed upload URL
        signed_upload = await bucket.create_signed_upload_url(
            path="users/123/avatar.png"
        )

        # Then upload using the token
        result = await bucket.upload_to_signed_url(
            path=signed_upload["path"],
            token=signed_upload["token"],
            file="/path/to/local/image.png",
            file_options={
                "content-type": "image/png",
                "cache-control": "3600"
            }
        )

        print(f"Uploaded: {result.path}")
        return result
```

--------------------------------

### Create Multiple Signed URLs

Source: https://context7.com/supabase/storage-py/llms.txt

Generates signed URLs for multiple files in a single request. Useful for batch access. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def create_multiple_signed_urls():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("private-files")

        signed_urls = await bucket.create_signed_urls(
            paths=[
                "documents/file1.pdf",
                "documents/file2.pdf",
                "images/photo.jpg"
            ],
            expires_in=3600,
            options={"download": True}
        )

        for item in signed_urls:
            if item["error"]:
                print(f"Error for {item['path']}: {item['error']}")
            else:
                print(f"URL for {item['path']}: {item['signedUrl']}")

        return signed_urls
```

--------------------------------

### Create Signed URL for Private Files

Source: https://context7.com/supabase/storage-py/llms.txt

Generates a time-limited URL for accessing private files. Supports download triggers and image transformations. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def create_signed_url_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("private-files")

        # Basic signed URL (1 hour expiry)
        signed = await bucket.create_signed_url(
            path="documents/secret.pdf",
            expires_in=3600  # seconds
        )
        print(f"Signed URL: {signed['signedUrl']}")

        # Signed URL with download trigger
        signed = await bucket.create_signed_url(
            path="documents/report.pdf",
            expires_in=3600,
            options={"download": True}
        )

        # Signed URL with custom download filename
        signed = await bucket.create_signed_url(
            path="documents/report.pdf",
            expires_in=3600,
            options={"download": "annual-report-2024.pdf"}
        )

        # Signed URL with image transformation
        signed = await bucket.create_signed_url(
            path="images/photo.jpg",
            expires_in=3600,
            options={
                "transform": {
                    "width": 200,
                    "height": 200,
                    "resize": "cover"
                }
            }
        )

        return signed
```

--------------------------------

### Copy File

Source: https://context7.com/supabase/storage-py/llms.txt

Creates a copy of a file at a new path within the same bucket.

```APIDOC
## Copy File

Creates a copy of a file at a new path within the same bucket.

### Method
POST

### Endpoint
`/storage/v1/object/copy/{bucketName}`

### Parameters
#### Request Body
- **from_path** (string) - Required - The path of the file to copy.
- **to_path** (string) - Required - The destination path for the copied file.

### Response
#### Success Response (200)
- **result** (object) - An object indicating the success of the operation, typically with a `Key` field.

### Request Example
```python
from storage3 import AsyncStorageClient

async def copy_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        result = await bucket.copy(
            from_path="users/123/avatar.png",
            to_path="users/123/avatar-backup.png"
        )
        print(f"File copied: {result}")
        return result
```
```

--------------------------------

### List Files in Bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Lists all files within a bucket with optional filtering, pagination, and sorting.

```APIDOC
## List Files in Bucket

Lists all files within a bucket with optional filtering, pagination, and sorting.

### Method
GET

### Endpoint
`/storage/v1/object/list/{bucketName}`

### Parameters
#### Query Parameters
- **path** (string) - Optional - The path to the folder within the bucket. Defaults to root.
- **limit** (integer) - Optional - The maximum number of files to return.
- **offset** (integer) - Optional - The number of files to skip before returning results.
- **sortBy** (object) - Optional - An object specifying the column and order for sorting.
  - **column** (string) - Required - The column to sort by (e.g., `name`, `created_at`).
  - **order** (string) - Required - The sort order (`asc` or `desc`).
- **search** (string) - Optional - A string to filter filenames by.

### Response
#### Success Response (200)
- **files** (array) - An array of file objects, each containing `name`, `metadata`, and other relevant information.

### Request Example
```python
from storage3 import AsyncStorageClient

async def list_files_examples():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # List all files in root
        files = await bucket.list()
        for file in files:
            print(f"File: {file.get('name')}, Size: {file.get('metadata', {}).get('size')}")

        # List files in a specific folder
        files = await bucket.list(path="users/123")

        # List with pagination and sorting
        files = await bucket.list(
            path="documents",
            options={
                "limit": 100,
                "offset": 0,
                "sortBy": {
                    "column": "created_at",
                    "order": "desc"
                },
                "search": "report"  # Filter by filename
            }
        )

        return files
```
```

--------------------------------

### Upload files to storage

Source: https://github.com/supabase/storage-py/blob/main/README.md

Uploads a file to a specified bucket, ensuring the correct mimetype is set via file_options.

```py
async def file_upload():
  await storage_client.from_("bucket").upload("/folder/file.png", file_object, {"content-type": "image/png"})
```

--------------------------------

### POST /create_multiple_signed_urls

Source: https://context7.com/supabase/storage-py/llms.txt

Creates signed URLs for multiple files in a single request.

```APIDOC
## POST /create_multiple_signed_urls

### Description
Creates signed URLs for multiple files in a single request.

### Parameters
#### Request Body
- **paths** (array) - Required - List of file paths
- **expires_in** (integer) - Required - Expiry time in seconds
- **options** (object) - Optional - Configuration for download
```

--------------------------------

### Create Signed Upload URL

Source: https://context7.com/supabase/storage-py/llms.txt

Generates a signed URL for uploading files without requiring direct authentication. Useful for client-side uploads. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def create_signed_upload_url():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("uploads")

        signed_upload = await bucket.create_signed_upload_url(
            path="users/123/new-file.png"
        )

        print(f"Upload URL: {signed_upload['signed_url']}")
        print(f"Token: {signed_upload['token']}")
        print(f"Path: {signed_upload['path']}")

        return signed_upload
```

--------------------------------

### POST /create_signed_url

Source: https://context7.com/supabase/storage-py/llms.txt

Creates a time-limited URL for accessing private files, supporting download triggers and image transformations.

```APIDOC
## POST /create_signed_url

### Description
Creates a time-limited URL for accessing private files. Supports download triggers and image transformations.

### Parameters
#### Request Body
- **path** (string) - Required - The file path in the bucket
- **expires_in** (integer) - Required - Expiry time in seconds
- **options** (object) - Optional - Configuration for download or transformations

### Response
#### Success Response (200)
- **signedUrl** (string) - The generated signed URL
```

--------------------------------

### Check File Exists

Source: https://context7.com/supabase/storage-py/llms.txt

Checks whether a file exists at the specified path in the bucket. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def check_file_exists(file_path: str):
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        exists = await bucket.exists(file_path)
        if exists:
            print(f"File {file_path} exists")
        else:
            print(f"File {file_path} does not exist")
        return exists

# Example
file_exists = await check_file_exists("users/123/avatar.png")
```

--------------------------------

### POST /upload_to_signed_url

Source: https://context7.com/supabase/storage-py/llms.txt

Uploads a file using a previously generated signed upload URL and token.

```APIDOC
## POST /upload_to_signed_url

### Description
Uploads a file using a previously generated signed upload URL and token.

### Parameters
#### Request Body
- **path** (string) - Required - The file path
- **token** (string) - Required - The upload token
- **file** (string) - Required - Local file path
- **file_options** (object) - Optional - Content-type and cache-control settings
```

--------------------------------

### POST /create_signed_upload_url

Source: https://context7.com/supabase/storage-py/llms.txt

Creates a signed URL for uploading files without requiring direct authentication.

```APIDOC
## POST /create_signed_upload_url

### Description
Creates a signed URL for uploading files without requiring direct authentication. Useful for client-side uploads.

### Parameters
#### Request Body
- **path** (string) - Required - The destination path for the upload

### Response
#### Success Response (200)
- **signed_url** (string) - The URL for the upload
- **token** (string) - The authorization token
- **path** (string) - The file path
```

--------------------------------

### Move File

Source: https://context7.com/supabase/storage-py/llms.txt

Moves a file to a new location within the same bucket, optionally renaming it. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def move_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        result = await bucket.move(
            from_path="users/123/old-avatar.png",
            to_path="users/123/avatar.png"
        )
        print(f"File moved: {result}")
        return result

# Move to different folder
async def reorganize_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("documents")

        result = await bucket.move(
            from_path="inbox/document.pdf",
            to_path="archive/2024/document.pdf"
        )
        return result
```

--------------------------------

### PUT /bucket/{id}

Source: https://context7.com/supabase/storage-py/llms.txt

Updates an existing bucket's configuration.

```APIDOC
## PUT /bucket/{id}

### Description
Updates an existing bucket's configuration including visibility and file constraints.

### Method
PUT

### Endpoint
/bucket/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the bucket.
#### Request Body
- **options** (object) - Required - Configuration object containing public, file_size_limit, and allowed_mime_types.

### Response
#### Success Response (200)
- **result** (object) - The updated bucket metadata.
```

--------------------------------

### Update Bucket Configuration

Source: https://context7.com/supabase/storage-py/llms.txt

Modifies the settings of an existing bucket, such as visibility or file size limits.

```python
from storage3 import AsyncStorageClient

async def update_bucket_settings(bucket_id: str):
    async with AsyncStorageClient(url, headers) as client:
        result = await client.update_bucket(
            id=bucket_id,
            options={
                "public": False,
                "file_size_limit": 10485760,  # 10MB
                "allowed_mime_types": ["image/*", "application/pdf"]
            }
        )
        print(f"Updated bucket: {result}")
        return result
```

--------------------------------

### Remove Files

Source: https://context7.com/supabase/storage-py/llms.txt

Deletes one or more files from the bucket. Requires `AsyncStorageClient`.

```python
from storage3 import AsyncStorageClient

async def remove_files():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # Remove single file
        result = await bucket.remove(["users/123/old-avatar.png"])

        # Remove multiple files
        result = await bucket.remove([
            "users/123/temp1.png",
            "users/123/temp2.png",
            "users/456/old-file.jpg"
        ])
        print(f"Removed files: {result}")
        return result
```

--------------------------------

### Retrieve Bucket Details

Source: https://context7.com/supabase/storage-py/llms.txt

Fetches metadata for a specific bucket by its unique identifier.

```python
from storage3 import AsyncStorageClient

async def get_bucket_details(bucket_id: str):
    async with AsyncStorageClient(url, headers) as client:
        bucket = await client.get_bucket(bucket_id)
        print(f"Name: {bucket.name}")
        print(f"Public: {bucket.public}")
        print(f"File size limit: {bucket.file_size_limit}")
        print(f"Allowed types: {bucket.allowed_mime_types}")
        return bucket

# Example usage
bucket = await get_bucket_details("avatars")
```

--------------------------------

### Check File Exists

Source: https://context7.com/supabase/storage-py/llms.txt

Checks whether a file exists at the specified path in the bucket.

```APIDOC
## Check File Exists

Checks whether a file exists at the specified path in the bucket.

### Method
HEAD

### Endpoint
`/storage/v1/object/exists/{bucketName}/{filePath}`

### Parameters
#### Path Parameters
- **filePath** (string) - Required - The full path to the file within the bucket.

### Response
#### Success Response (200)
- **exists** (boolean) - `true` if the file exists, `false` otherwise.

### Request Example
```python
from storage3 import AsyncStorageClient

async def check_file_exists(file_path: str):
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        exists = await bucket.exists(file_path)
        if exists:
            print(f"File {file_path} exists")
        else:
            print(f"File {file_path} does not exist")
        return exists

# Example
file_exists = await check_file_exists("users/123/avatar.png")
```
```

--------------------------------

### Storage Types

Source: https://github.com/supabase/storage-py/blob/main/docs/api/types.rst

This section describes the structures of data returned or required by various API calls within the Supabase Storage Python client.

```APIDOC
## Storage Types

### Description
This section describes the structures of data returned or required by various API calls.

### Types

- **SignedUploadURL**
- **CreateOrUpdateBucketOptions**
- **ListBucketFilesOptions**
- **TransformOptions**
- **URLOptions**
- **CreateSignedURLsOptions**
- **FileOptions**
- **_sortByType**
```

--------------------------------

### Move File

Source: https://context7.com/supabase/storage-py/llms.txt

Moves a file to a new location within the same bucket, optionally renaming it.

```APIDOC
## Move File

Moves a file to a new location within the same bucket, optionally renaming it.

### Method
POST

### Endpoint
`/storage/v1/object/move/{bucketName}`

### Parameters
#### Request Body
- **from_path** (string) - Required - The current path of the file to move.
- **to_path** (string) - Required - The new path for the file, including the new name if desired.

### Response
#### Success Response (200)
- **result** (object) - An object indicating the success of the operation, typically with a `Key` field.

### Request Example
```python
from storage3 import AsyncStorageClient

async def move_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        result = await bucket.move(
            from_path="users/123/old-avatar.png",
            to_path="users/123/avatar.png"
        )
        print(f"File moved: {result}")
        return result

# Move to different folder
async def reorganize_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("documents")

        result = await bucket.move(
            from_path="inbox/document.pdf",
            to_path="archive/2024/document.pdf"
        )
        return result
```
```

--------------------------------

### Safely Upload Files with Error Handling

Source: https://context7.com/supabase/storage-py/llms.txt

Implement a safe upload function that catches `StorageApiError` during file uploads. Returns a success status and data on success, or an error dictionary on failure.

```python
# Example error response handling
async def safe_upload(bucket_id: str, path: str, file_path: str):
    async with AsyncStorageClient(url, headers) as client:
        try:
            bucket = client.from_(bucket_id)
            result = await bucket.upload(
                path=path,
                file=file_path,
                file_options={"content-type": "image/png"}
            )
            return {"success": True, "data": result}
        except StorageApiError as e:
            return {"success": False, "error": e.to_dict()}
```

--------------------------------

### Delete Bucket Safely

Source: https://context7.com/supabase/storage-py/llms.txt

Deletes an existing bucket after ensuring it is empty. Use this to safely remove a bucket and all its contents.

```python
from storage3 import AsyncStorageClient

async def delete_bucket_safely(bucket_id: str):
    async with AsyncStorageClient(url, headers) as client:
        # First empty the bucket
        await client.empty_bucket(bucket_id)
        print(f"Emptied bucket: {bucket_id}")

        # Then delete it
        result = await client.delete_bucket(bucket_id)
        print(f"Deleted bucket: {result}")
        return result
```

--------------------------------

### Handle Storage API Errors

Source: https://context7.com/supabase/storage-py/llms.txt

Catch `StorageApiError` to gracefully handle API-related issues like file not found. Access error details such as message, status code, and a dictionary representation.

```python
from storage3 import AsyncStorageClient
from storage3.exceptions import StorageApiError
from storage3.utils import StorageException

async def handle_storage_errors():
    async with AsyncStorageClient(url, headers) as client:
        try:
            bucket = client.from_("avatars")
            await bucket.download("nonexistent/file.png")
        except StorageApiError as e:
            print(f"API Error: {e.message}")
            print(f"Status: {e.status}")
            print(f"Code: {e.code}")
            error_dict = e.to_dict()
            print(f"Error details: {error_dict}")
        except StorageException as e:
            print(f"Storage exception: {e}")
```

--------------------------------

### Remove Files

Source: https://context7.com/supabase/storage-py/llms.txt

Deletes one or more files from the bucket.

```APIDOC
## Remove Files

Deletes one or more files from the bucket.

### Method
DELETE

### Endpoint
`/storage/v1/object/{bucketName}`

### Parameters
#### Request Body
- **paths** (array of strings) - Required - An array of file paths to delete.

### Response
#### Success Response (200)
- **result** (array of objects) - An array of objects, each indicating the success or failure of deleting a specific file.

### Request Example
```python
from storage3 import AsyncStorageClient

async def remove_files():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        # Remove single file
        result = await bucket.remove(["users/123/old-avatar.png"])

        # Remove multiple files
        result = await bucket.remove([
            "users/123/temp1.png",
            "users/123/temp2.png",
            "users/456/old-file.jpg"
        ])
        print(f"Removed files: {result}")
        return result
```
```

--------------------------------

### Update Existing File

Source: https://context7.com/supabase/storage-py/llms.txt

Updates the content of an existing file in a Supabase Storage bucket. This operation replaces the file's content while keeping the same path and metadata unless specified otherwise.

```python
from storage3 import AsyncStorageClient

async def update_existing_file():
    async with AsyncStorageClient(url, headers) as client:
        bucket = client.from_("avatars")

        result = await bucket.update(
            path="users/123/avatar.png",
            file="/path/to/updated-image.png",
            file_options={
                "content-type": "image/png",
                "cache-control": "3600"
            }
        )
        print(f"Updated file: {result.path}")
        return result
```

--------------------------------

### Empty Bucket

Source: https://context7.com/supabase/storage-py/llms.txt

Removes all objects within a specified bucket without deleting the bucket itself. Useful for clearing contents before re-uploading or for resetting data.

```python
from storage3 import AsyncStorageClient

async def clear_bucket(bucket_id: str):
    async with AsyncStorageClient(url, headers) as client:
        result = await client.empty_bucket(bucket_id)
        print(f"Bucket emptied: {result}")
        return result
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.