Metadata-Version: 2.5
Name: storage-kernel-provider-gcp-storage
Version: 0.1.0a1
Summary: GCP Storage provider package for Storage Kernel.
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: google-cloud-storage
Requires-Dist: storage-kernel-contracts<0.2.0,>=0.1.0a1
Requires-Dist: storage-kernel-core<0.2.0,>=0.1.0a1
Description-Content-Type: text/markdown

# storage-kernel-provider-gcp-storage

GCP Cloud Storage provider for Storage Kernel.

This provider maps `StorageLocation.bucket` to a Cloud Storage bucket and
`StorageLocation.prefix` to an object-name namespace.

## Install

```bash
uv add storage-kernel-contracts storage-kernel-provider-gcp-storage
```

## Usage

```python
from storage_kernel.contracts import StorageClientOptions, StorageLocation, StoragePath
from storage_kernel.provider_gcp_storage import (
    GcpStorageProviderOptions,
    create_gcp_storage_client,
)

storage = create_gcp_storage_client(
    StorageClientOptions(location=StorageLocation(bucket="my-bucket", prefix="prod")),
    GcpStorageProviderOptions(project_id="my-project"),
)

await storage.send_content(StoragePath("docs/readme.txt"), "Hello")
```

The provider uses `google-cloud-storage` behind the provider boundary. When
`credentials` and `client` are omitted, authentication follows Google
Application Default Credentials. An injected client is caller-owned and may be
used for custom SDK configuration or tests.

## Provider Options

| Option | Purpose |
| --- | --- |
| `project_id` | GCP project used by the SDK factory |
| `credentials` | Explicit credentials dictionary passed to the SDK factory |
| `public_base_url` | Optional CDN/custom base URL for `get_public_url` |
| `client` | Optional caller-owned Google Storage client |

## Capabilities

- full binary and text reads/writes
- blob read streams
- resumable writable upload streams
- prefix-based directory listing and recursive deletion
- same-provider native copy
- Cloud Storage signed URLs
- public URLs through `public_base_url` or the blob public URL

Provider SDK errors are normalized into Storage Kernel errors such as path not
found, permission denied and provider error.
