Metadata-Version: 2.4
Name: rse-files-core
Version: 0.2.3
Summary: RSE standard file storage helpers with Vault-backed configuration and GCS support.
Author: RSE Team
Requires-Python: >=3.12,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: google-cloud-storage (>=2.19.0,<3.0.0)
Requires-Dist: hvac (>=2.4.0,<3.0.0)
Description-Content-Type: text/markdown

# rse-files-core

RSE standard file storage package for Python APIs.

Features:

- GCS upload/download helpers
- storage configuration from local environment or HashiCorp Vault
- filename and storage key sanitization
- SHA-256 checksums
- PDF/content-type/max-size validation
- standardized metadata and exceptions

## Usage

```python
from rse_files import (
    build_storage_key,
    create_file_storage,
    validate_pdf_bytes,
)

storage = create_file_storage()

validate_pdf_bytes(content)

storage_key = build_storage_key(
    namespace="nc",
    owner_type="action-plan-evidence",
    owner_id=123,
    filename="evidencia.pdf",
)

metadata = storage.upload_bytes(
    content=content,
    storage_key=storage_key,
    content_type="application/pdf",
    filename="evidencia.pdf",
)

public_url = storage.get_public_url(storage_key)
```

`get_public_url` only builds the canonical public GCS URL for a valid storage key.
It does not change bucket IAM, object ACLs, signed URL settings, or CDN settings.
Public access must be configured explicitly in the target bucket infrastructure.

## Local Configuration

When `RSE_ENV=local`, the package reads regular environment variables:

```text
RSE_FILES_STORAGE_PROVIDER=gcs
RSE_FILES_BUCKET=my-bucket
RSE_FILES_PREFIX=uploads
```

## Vault

When `RSE_ENV` is `stg` or `prd`, the package reads Vault using:

- `RSE_ENV` as the KV v2 mount point
- `RSE_VAULT_HOST` as the Vault URL
- `RSE_VAULT_TOKEN` as the Vault token
- `RSE_FILES_VAULT_PATH` as the secret path, defaulting to `shared`

Expected keys:

```text
rse_files_storage_provider
rse_files_bucket
rse_files_prefix
```

Fallback keys are also accepted for compatibility:

```text
document_storage_provider
gcs_documents_bucket
gcs_documents_prefix
```

Example:

```text
stg/shared.rse_files_storage_provider = gcs
stg/shared.rse_files_bucket = rse-documents-stg
stg/shared.rse_files_prefix = files
```

