kiarina-lib-google-cloud-storage 1.6.1__tar.gz → 1.6.2__tar.gz

{kiarina_lib_google_cloud_storage-1.6.1 → kiarina_lib_google_cloud_storage-1.6.2}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.2] - 2025-10-10
+
+### Changed
+- **Improved blob name handling**: Replaced `blob_name_prefix` and `blob_name` with `blob_name_pattern`
+  - `blob_name_pattern` supports both fixed names and template patterns with placeholders
+  - `get_blob()` now accepts `placeholders` parameter for pattern formatting
+  - `blob_name` parameter in `get_blob()` now always represents the full blob path
+  - Pattern examples: `"data.json"` (fixed), `"files/{basename}"` (single placeholder), `"web/{user_id}/{agent_id}/files/{basename}"` (multiple placeholders)
+  - Priority: explicit `blob_name` → `blob_name_pattern` with `placeholders` → `blob_name_pattern` without placeholders
+  - Enhanced error messages for missing placeholders
+
 ## [1.6.1] - 2025-10-10
 
 ### Changed

{kiarina_lib_google_cloud_storage-1.6.1 → kiarina_lib_google_cloud_storage-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiarina-lib-google-cloud-storage
-Version: 1.6.1
+Version: 1.6.2
 Summary: Google Cloud Storage client library for kiarina namespace
 Project-URL: Homepage, https://github.com/kiarina/kiarina-python
 Project-URL: Repository, https://github.com/kiarina/kiarina-python
@@ -32,7 +32,7 @@ A Python client library for Google Cloud Storage that separates infrastructure c
 
 ## Design Philosophy
 
-This library follows the principle of **separating infrastructure concerns from application logic**.
+This library follows the principle of **separating infrastructure concerns from application logic**, with special emphasis on **security rule alignment** and **path structure management**.
 
 ### The Problem
 
@@ -58,17 +58,22 @@ blob = bucket.blob("v2/users/data.json")  # Hard-coded path structure
 - Hard to support multiple environments (dev, staging, production)
 - Challenging to implement multi-tenancy
 - Credentials management is error-prone
+- **Path structures are coupled with application code, making security rule changes difficult**
 
-### The Solution
+### The Solution: Blob Name Patterns
 
-This library externalizes all infrastructure configuration:
+This library externalizes all infrastructure configuration, including path structures:
 
 ```python
-# ✅ Application code only knows logical names
+# ✅ Application code only provides variables
 from kiarina.lib.google.cloud_storage import get_blob
 
-# All infrastructure details are managed externally
-blob = get_blob(blob_name="user_data.json")
+# Path structure is managed in configuration
+blob = get_blob(placeholders={
+    "user_id": user_id,
+    "agent_id": agent_id,
+    "basename": file_name
+})
 blob.upload_from_string(json.dumps(data))
 ```
 
@@ -78,6 +83,122 @@ blob.upload_from_string(json.dumps(data))
 - **Multi-tenant ready**: Different configurations for different tenants
 - **Secure**: Credentials managed through kiarina-lib-google-auth
 - **Maintainable**: Infrastructure changes don't require code changes
+- **Security-aligned**: Path structures match GCS security rules, managed together
+
+### Why Blob Name Patterns Matter
+
+**The Core Problem**: GCS security rules define path structures, and application code must align with them.
+
+#### Without Blob Name Patterns (Tight Coupling)
+
+```python
+# Application code constructs paths
+blob_name = f"users/{user_id}/files/{file_name}"
+blob = get_blob(blob_name=blob_name)
+```
+
+**GCS Security Rules:**
+```javascript
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /users/{user_id}/files/{basename} {
+      allow read, write: if request.auth.uid == user_id;
+    }
+  }
+}
+```
+
+**What happens when security requirements change?**
+
+New requirement: Add agent-level isolation for multi-tenancy.
+
+**Updated Security Rules:**
+```javascript
+match /web/{user_id}/{agent_id}/files/{basename} {
+  allow read, write: if request.auth.uid == user_id 
+                     && request.auth.token.agent_id == agent_id;
+}
+```
+
+**Problem**: You must now update **every place** in your application code that constructs these paths:
+```python
+# Must change all of these
+blob_name = f"web/{user_id}/{agent_id}/files/{file_name}"  # Changed!
+blob_name = f"web/{user_id}/{agent_id}/thumbnails/{file_name}"  # Changed!
+blob_name = f"web/{user_id}/{agent_id}/exports/{file_name}"  # Changed!
+# ... and many more
+```
+
+#### With Blob Name Patterns (Loose Coupling)
+
+**Configuration (Infrastructure Concern):**
+```yaml
+# config/production.yaml
+google_cloud_storage:
+  default:
+    bucket_name: "my-app-data"
+    blob_name_pattern: "web/{user_id}/{agent_id}/files/{basename}"
+```
+
+**GCS Security Rules (Infrastructure Concern):**
+```javascript
+match /web/{user_id}/{agent_id}/files/{basename} {
+  allow read, write: if request.auth.uid == user_id 
+                     && request.auth.token.agent_id == agent_id;
+}
+```
+
+**Application Code (Business Logic):**
+```python
+# Application only provides variables - no path knowledge
+blob = get_blob(placeholders={
+    "user_id": current_user.id,
+    "agent_id": current_agent.id,
+    "basename": uploaded_file.name
+})
+blob.upload_from_string(file_content)
+```
+
+**When security rules change**: Only update the configuration file. Application code remains unchanged.
+
+#### Real-World Example: Multi-Environment Security
+
+Different environments often have different security requirements:
+
+**Production** (strict isolation):
+```yaml
+blob_name_pattern: "v2/production/{tenant_id}/{user_id}/{agent_id}/files/{basename}"
+```
+
+**Staging** (relaxed for testing):
+```yaml
+blob_name_pattern: "v2/staging/{user_id}/files/{basename}"
+```
+
+**Development** (flat structure):
+```yaml
+blob_name_pattern: "dev/{basename}"
+```
+
+**Application code** (same for all environments):
+```python
+blob = get_blob(placeholders={
+    "tenant_id": tenant.id,
+    "user_id": user.id,
+    "agent_id": agent.id,
+    "basename": file.name
+})
+```
+
+Missing placeholders are simply ignored if not present in the pattern.
+
+### Design Principles
+
+1. **Infrastructure defines "where"**: Path structures, bucket names, security rules
+2. **Application defines "what"**: Data content, business logic, variables
+3. **Configuration is the contract**: Placeholders define the interface between infrastructure and application
+4. **Security rules and path patterns are managed together**: Both are infrastructure concerns
 
 ## Features
 
@@ -106,14 +227,17 @@ from kiarina.lib.google.cloud_storage import get_blob, settings_manager
 settings_manager.user_config = {
     "default": {
         "bucket_name": "my-app-data",
-        "blob_name_prefix": "production/v1"
+        "blob_name_pattern": "production/v1/{basename}"
     }
 }
 
 # Application code - clean and simple
-blob = get_blob(blob_name="user_data.json")
+blob = get_blob(placeholders={"basename": "user_data.json"})
 # Actual path: gs://my-app-data/production/v1/user_data.json
 
+# Or use direct blob name (full path)
+blob = get_blob(blob_name="production/v1/user_data.json")
+
 # Use native google-cloud-storage API
 blob.upload_from_string("Hello, World!")
 content = blob.download_as_text()
@@ -339,8 +463,7 @@ This library uses [pydantic-settings-manager](https://github.com/kiarina/pydanti
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `bucket_name` | `str \| None` | Yes* | Google Cloud Storage bucket name |
-| `blob_name_prefix` | `str \| None` | No | Prefix for blob names (e.g., "production/v1") |
-| `blob_name` | `str \| None` | No | Default blob name (rarely used) |
+| `blob_name_pattern` | `str \| None` | No | Blob name pattern with placeholders (e.g., "users/{user_id}/files/{basename}") |
 
 *Required when using `get_bucket()` or `get_blob()`
 
@@ -501,6 +624,7 @@ Get a Google Cloud Storage blob.
 def get_blob(
     blob_name: str | None = None,
     *,
+    placeholders: dict[str, Any] | None = None,
     config_key: str | None = None,
     auth_config_key: str | None = None,
     **kwargs: Any
@@ -508,7 +632,8 @@ def get_blob(
 ```
 
 **Parameters:**
-- `blob_name`: Blob name (default: None uses settings.blob_name)
+- `blob_name`: Full blob name (path). If provided, this takes precedence.
+- `placeholders`: Placeholders for blob_name_pattern formatting.
 - `config_key`: Configuration key for storage settings (default: None uses active key)
 - `auth_config_key`: Configuration key for authentication (default: None uses active key)
 - `**kwargs`: Additional arguments passed to `get_bucket()`
@@ -517,21 +642,40 @@ def get_blob(
 - `storage.Blob`: Google Cloud Storage blob
 
 **Raises:**
-- `ValueError`: If `blob_name` is not provided and not set in settings
+- `ValueError`: If blob_name cannot be determined or pattern formatting fails
+
+**Priority:**
+1. Explicit `blob_name` parameter (full path)
+2. `blob_name_pattern` with `placeholders`
+3. `blob_name_pattern` without placeholders (fixed name)
 
 **Example:**
 ```python
-# Basic usage
-blob = get_blob(blob_name="data.json")
-
-# With blob_name_prefix in settings
-# If blob_name_prefix="production/v1" and blob_name="data.json"
-# Actual blob name will be "production/v1/data.json"
-blob = get_blob(blob_name="data.json")
+# Direct blob name (full path)
+blob = get_blob(blob_name="production/v1/data.json")
+
+# Using pattern with placeholders
+# If blob_name_pattern="users/{user_id}/files/{basename}"
+blob = get_blob(placeholders={"user_id": "123", "basename": "profile.json"})
+# Actual: gs://bucket/users/123/files/profile.json
+
+# Using fixed pattern from settings
+# If blob_name_pattern="data/fixed.json"
+blob = get_blob()
+# Actual: gs://bucket/data/fixed.json
+
+# Complex pattern
+# If blob_name_pattern="web/{user_id}/{agent_id}/files/{basename}"
+blob = get_blob(placeholders={
+    "user_id": "user123",
+    "agent_id": "agent456",
+    "basename": "document.pdf"
+})
+# Actual: gs://bucket/web/user123/agent456/files/document.pdf
 
 # With custom configurations
 blob = get_blob(
-    blob_name="data.json",
+    placeholders={"basename": "data.json"},
     config_key="production",
     auth_config_key="prod_auth"
 )

{kiarina_lib_google_cloud_storage-1.6.1 → kiarina_lib_google_cloud_storage-1.6.2}/README.md

@@ -4,7 +4,7 @@ A Python client library for Google Cloud Storage that separates infrastructure c
 
 ## Design Philosophy
 
-This library follows the principle of **separating infrastructure concerns from application logic**.
+This library follows the principle of **separating infrastructure concerns from application logic**, with special emphasis on **security rule alignment** and **path structure management**.
 
 ### The Problem
 
@@ -30,17 +30,22 @@ blob = bucket.blob("v2/users/data.json")  # Hard-coded path structure
 - Hard to support multiple environments (dev, staging, production)
 - Challenging to implement multi-tenancy
 - Credentials management is error-prone
+- **Path structures are coupled with application code, making security rule changes difficult**
 
-### The Solution
+### The Solution: Blob Name Patterns
 
-This library externalizes all infrastructure configuration:
+This library externalizes all infrastructure configuration, including path structures:
 
 ```python
-# ✅ Application code only knows logical names
+# ✅ Application code only provides variables
 from kiarina.lib.google.cloud_storage import get_blob
 
-# All infrastructure details are managed externally
-blob = get_blob(blob_name="user_data.json")
+# Path structure is managed in configuration
+blob = get_blob(placeholders={
+    "user_id": user_id,
+    "agent_id": agent_id,
+    "basename": file_name
+})
 blob.upload_from_string(json.dumps(data))
 ```
 
@@ -50,6 +55,122 @@ blob.upload_from_string(json.dumps(data))
 - **Multi-tenant ready**: Different configurations for different tenants
 - **Secure**: Credentials managed through kiarina-lib-google-auth
 - **Maintainable**: Infrastructure changes don't require code changes
+- **Security-aligned**: Path structures match GCS security rules, managed together
+
+### Why Blob Name Patterns Matter
+
+**The Core Problem**: GCS security rules define path structures, and application code must align with them.
+
+#### Without Blob Name Patterns (Tight Coupling)
+
+```python
+# Application code constructs paths
+blob_name = f"users/{user_id}/files/{file_name}"
+blob = get_blob(blob_name=blob_name)
+```
+
+**GCS Security Rules:**
+```javascript
+rules_version = '2';
+service firebase.storage {
+  match /b/{bucket}/o {
+    match /users/{user_id}/files/{basename} {
+      allow read, write: if request.auth.uid == user_id;
+    }
+  }
+}
+```
+
+**What happens when security requirements change?**
+
+New requirement: Add agent-level isolation for multi-tenancy.
+
+**Updated Security Rules:**
+```javascript
+match /web/{user_id}/{agent_id}/files/{basename} {
+  allow read, write: if request.auth.uid == user_id 
+                     && request.auth.token.agent_id == agent_id;
+}
+```
+
+**Problem**: You must now update **every place** in your application code that constructs these paths:
+```python
+# Must change all of these
+blob_name = f"web/{user_id}/{agent_id}/files/{file_name}"  # Changed!
+blob_name = f"web/{user_id}/{agent_id}/thumbnails/{file_name}"  # Changed!
+blob_name = f"web/{user_id}/{agent_id}/exports/{file_name}"  # Changed!
+# ... and many more
+```
+
+#### With Blob Name Patterns (Loose Coupling)
+
+**Configuration (Infrastructure Concern):**
+```yaml
+# config/production.yaml
+google_cloud_storage:
+  default:
+    bucket_name: "my-app-data"
+    blob_name_pattern: "web/{user_id}/{agent_id}/files/{basename}"
+```
+
+**GCS Security Rules (Infrastructure Concern):**
+```javascript
+match /web/{user_id}/{agent_id}/files/{basename} {
+  allow read, write: if request.auth.uid == user_id 
+                     && request.auth.token.agent_id == agent_id;
+}
+```
+
+**Application Code (Business Logic):**
+```python
+# Application only provides variables - no path knowledge
+blob = get_blob(placeholders={
+    "user_id": current_user.id,
+    "agent_id": current_agent.id,
+    "basename": uploaded_file.name
+})
+blob.upload_from_string(file_content)
+```
+
+**When security rules change**: Only update the configuration file. Application code remains unchanged.
+
+#### Real-World Example: Multi-Environment Security
+
+Different environments often have different security requirements:
+
+**Production** (strict isolation):
+```yaml
+blob_name_pattern: "v2/production/{tenant_id}/{user_id}/{agent_id}/files/{basename}"
+```
+
+**Staging** (relaxed for testing):
+```yaml
+blob_name_pattern: "v2/staging/{user_id}/files/{basename}"
+```
+
+**Development** (flat structure):
+```yaml
+blob_name_pattern: "dev/{basename}"
+```
+
+**Application code** (same for all environments):
+```python
+blob = get_blob(placeholders={
+    "tenant_id": tenant.id,
+    "user_id": user.id,
+    "agent_id": agent.id,
+    "basename": file.name
+})
+```
+
+Missing placeholders are simply ignored if not present in the pattern.
+
+### Design Principles
+
+1. **Infrastructure defines "where"**: Path structures, bucket names, security rules
+2. **Application defines "what"**: Data content, business logic, variables
+3. **Configuration is the contract**: Placeholders define the interface between infrastructure and application
+4. **Security rules and path patterns are managed together**: Both are infrastructure concerns
 
 ## Features
 
@@ -78,14 +199,17 @@ from kiarina.lib.google.cloud_storage import get_blob, settings_manager
 settings_manager.user_config = {
     "default": {
         "bucket_name": "my-app-data",
-        "blob_name_prefix": "production/v1"
+        "blob_name_pattern": "production/v1/{basename}"
     }
 }
 
 # Application code - clean and simple
-blob = get_blob(blob_name="user_data.json")
+blob = get_blob(placeholders={"basename": "user_data.json"})
 # Actual path: gs://my-app-data/production/v1/user_data.json
 
+# Or use direct blob name (full path)
+blob = get_blob(blob_name="production/v1/user_data.json")
+
 # Use native google-cloud-storage API
 blob.upload_from_string("Hello, World!")
 content = blob.download_as_text()
@@ -311,8 +435,7 @@ This library uses [pydantic-settings-manager](https://github.com/kiarina/pydanti
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `bucket_name` | `str \| None` | Yes* | Google Cloud Storage bucket name |
-| `blob_name_prefix` | `str \| None` | No | Prefix for blob names (e.g., "production/v1") |
-| `blob_name` | `str \| None` | No | Default blob name (rarely used) |
+| `blob_name_pattern` | `str \| None` | No | Blob name pattern with placeholders (e.g., "users/{user_id}/files/{basename}") |
 
 *Required when using `get_bucket()` or `get_blob()`
 
@@ -473,6 +596,7 @@ Get a Google Cloud Storage blob.
 def get_blob(
     blob_name: str | None = None,
     *,
+    placeholders: dict[str, Any] | None = None,
     config_key: str | None = None,
     auth_config_key: str | None = None,
     **kwargs: Any
@@ -480,7 +604,8 @@ def get_blob(
 ```
 
 **Parameters:**
-- `blob_name`: Blob name (default: None uses settings.blob_name)
+- `blob_name`: Full blob name (path). If provided, this takes precedence.
+- `placeholders`: Placeholders for blob_name_pattern formatting.
 - `config_key`: Configuration key for storage settings (default: None uses active key)
 - `auth_config_key`: Configuration key for authentication (default: None uses active key)
 - `**kwargs`: Additional arguments passed to `get_bucket()`
@@ -489,21 +614,40 @@ def get_blob(
 - `storage.Blob`: Google Cloud Storage blob
 
 **Raises:**
-- `ValueError`: If `blob_name` is not provided and not set in settings
+- `ValueError`: If blob_name cannot be determined or pattern formatting fails
+
+**Priority:**
+1. Explicit `blob_name` parameter (full path)
+2. `blob_name_pattern` with `placeholders`
+3. `blob_name_pattern` without placeholders (fixed name)
 
 **Example:**
 ```python
-# Basic usage
-blob = get_blob(blob_name="data.json")
-
-# With blob_name_prefix in settings
-# If blob_name_prefix="production/v1" and blob_name="data.json"
-# Actual blob name will be "production/v1/data.json"
-blob = get_blob(blob_name="data.json")
+# Direct blob name (full path)
+blob = get_blob(blob_name="production/v1/data.json")
+
+# Using pattern with placeholders
+# If blob_name_pattern="users/{user_id}/files/{basename}"
+blob = get_blob(placeholders={"user_id": "123", "basename": "profile.json"})
+# Actual: gs://bucket/users/123/files/profile.json
+
+# Using fixed pattern from settings
+# If blob_name_pattern="data/fixed.json"
+blob = get_blob()
+# Actual: gs://bucket/data/fixed.json
+
+# Complex pattern
+# If blob_name_pattern="web/{user_id}/{agent_id}/files/{basename}"
+blob = get_blob(placeholders={
+    "user_id": "user123",
+    "agent_id": "agent456",
+    "basename": "document.pdf"
+})
+# Actual: gs://bucket/web/user123/agent456/files/document.pdf
 
 # With custom configurations
 blob = get_blob(
-    blob_name="data.json",
+    placeholders={"basename": "data.json"},
     config_key="production",
     auth_config_key="prod_auth"
 )

{kiarina_lib_google_cloud_storage-1.6.1 → kiarina_lib_google_cloud_storage-1.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiarina-lib-google-cloud-storage"
-version = "1.6.1"
+version = "1.6.2"
 description = "Google Cloud Storage client library for kiarina namespace"
 readme = "README.md"
 license = "MIT"

kiarina_lib_google_cloud_storage-1.6.2/src/kiarina/lib/google/cloud_storage/_get_blob.py

@@ -0,0 +1,78 @@
+from typing import Any
+
+from google.cloud import storage  # type: ignore[import-untyped]
+
+from ._get_bucket import get_bucket
+from .settings import settings_manager
+
+
+def get_blob(
+    blob_name: str | None = None,
+    *,
+    placeholders: dict[str, Any] | None = None,
+    config_key: str | None = None,
+    auth_config_key: str | None = None,
+    **kwargs: Any,
+) -> storage.Blob:
+    """
+    Get a Google Cloud Storage blob.
+
+    Args:
+        blob_name: Full blob name (path). If provided, this takes precedence.
+        placeholders: Placeholders for blob_name_pattern formatting.
+        config_key: Configuration key for storage settings.
+        auth_config_key: Configuration key for authentication.
+        **kwargs: Additional arguments passed to get_bucket().
+
+    Returns:
+        Google Cloud Storage blob.
+
+    Raises:
+        ValueError: If blob_name cannot be determined or pattern formatting fails.
+
+    Examples:
+        # Direct blob name
+        blob = get_blob(blob_name="data/file.json")
+
+        # Using pattern with placeholders
+        blob = get_blob(placeholders={"user_id": "123", "basename": "profile.json"})
+        # With pattern "users/{user_id}/{basename}" -> "users/123/profile.json"
+
+        # Using default pattern from settings
+        blob = get_blob()  # Uses settings.blob_name_pattern without placeholders
+    """
+    settings = settings_manager.get_settings_by_key(config_key)
+
+    # Priority 1: Explicit blob_name
+    if blob_name is not None:
+        final_blob_name = blob_name
+
+    # Priority 2: Pattern with placeholders
+    elif placeholders is not None:
+        if settings.blob_name_pattern is None:
+            raise ValueError(
+                "placeholders provided but blob_name_pattern is not set in settings"
+            )
+
+        try:
+            final_blob_name = settings.blob_name_pattern.format(**placeholders)
+        except KeyError as e:
+            raise ValueError(
+                f"Missing placeholder {e} in blob_name_pattern: "
+                f"{settings.blob_name_pattern}. "
+                f"Available placeholders: {list(placeholders.keys())}"
+            ) from e
+
+    # Priority 3: Default pattern from settings
+    elif settings.blob_name_pattern is not None:
+        # Pattern without placeholders (fixed name)
+        final_blob_name = settings.blob_name_pattern
+
+    else:
+        raise ValueError(
+            "blob_name is not provided, placeholders are not provided, "
+            "and blob_name_pattern is not set in settings"
+        )
+
+    bucket = get_bucket(config_key, auth_config_key=auth_config_key, **kwargs)
+    return bucket.blob(final_blob_name)

kiarina_lib_google_cloud_storage-1.6.2/src/kiarina/lib/google/cloud_storage/settings.py

@@ -0,0 +1,19 @@
+from pydantic_settings import BaseSettings
+from pydantic_settings_manager import SettingsManager
+
+
+class GoogleCloudStorageSettings(BaseSettings):
+    bucket_name: str | None = None
+
+    blob_name_pattern: str | None = None
+    """
+    Blob name pattern with placeholders.
+    
+    Examples:
+        - "data.json" (fixed name)
+        - "files/{basename}" (single placeholder)
+        - "web/{user_id}/{agent_id}/files/{basename}" (multiple placeholders)
+    """
+
+
+settings_manager = SettingsManager(GoogleCloudStorageSettings, multi=True)

kiarina_lib_google_cloud_storage-1.6.2/tests/test_get_blob.py

@@ -0,0 +1,224 @@
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from kiarina.lib.google.cloud_storage import get_blob, settings_manager
+
+
+def test_get_blob_with_blob_name():
+    """Test get_blob with explicit blob_name parameter."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "data/file.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ):
+        blob = get_blob(blob_name="data/file.json")
+        assert blob.name == "data/file.json"
+        mock_bucket.blob.assert_called_once_with("data/file.json")
+
+
+def test_get_blob_with_pattern_and_placeholders():
+    """Test get_blob with blob_name_pattern and placeholders."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "users/{user_id}/files/{basename}",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "users/123/files/profile.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ):
+        blob = get_blob(placeholders={"user_id": "123", "basename": "profile.json"})
+        assert blob.name == "users/123/files/profile.json"
+        mock_bucket.blob.assert_called_once_with("users/123/files/profile.json")
+
+
+def test_get_blob_with_fixed_pattern():
+    """Test get_blob with fixed blob_name_pattern (no placeholders)."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "data/fixed.json",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "data/fixed.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ):
+        blob = get_blob()
+        assert blob.name == "data/fixed.json"
+        mock_bucket.blob.assert_called_once_with("data/fixed.json")
+
+
+def test_get_blob_priority_blob_name_over_placeholders():
+    """Test that blob_name takes precedence over placeholders."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "users/{user_id}/files/{basename}",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "direct/path.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ):
+        blob = get_blob(
+            blob_name="direct/path.json",
+            placeholders={"user_id": "123", "basename": "ignored.json"},
+        )
+        assert blob.name == "direct/path.json"
+        mock_bucket.blob.assert_called_once_with("direct/path.json")
+
+
+def test_get_blob_with_missing_placeholder():
+    """Test error when placeholder is missing."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "users/{user_id}/files/{basename}",
+        }
+    }
+
+    with pytest.raises(
+        ValueError,
+        match=r"Missing placeholder 'basename' in blob_name_pattern: "
+        r"users/\{user_id\}/files/\{basename\}",
+    ):
+        get_blob(placeholders={"user_id": "123"})
+
+
+def test_get_blob_without_blob_name_and_pattern():
+    """Test error when neither blob_name nor blob_name_pattern is provided."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+        }
+    }
+
+    with pytest.raises(
+        ValueError,
+        match="blob_name is not provided, placeholders are not provided, "
+        "and blob_name_pattern is not set in settings",
+    ):
+        get_blob()
+
+
+def test_get_blob_with_placeholders_but_no_pattern():
+    """Test error when placeholders are provided but pattern is not set."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+        }
+    }
+
+    with pytest.raises(
+        ValueError,
+        match="placeholders provided but blob_name_pattern is not set in settings",
+    ):
+        get_blob(placeholders={"user_id": "123"})
+
+
+def test_get_blob_with_custom_config_key():
+    """Test get_blob with custom config_key."""
+    settings_manager.user_config = {
+        "custom": {
+            "bucket_name": "custom-bucket",
+            "blob_name_pattern": "custom/path.json",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "custom/path.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ) as mock_get_bucket:
+        blob = get_blob(config_key="custom")
+        assert blob.name == "custom/path.json"
+        mock_get_bucket.assert_called_once_with("custom", auth_config_key=None)
+
+
+def test_get_blob_with_auth_config_key():
+    """Test get_blob with custom auth_config_key."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "data.json",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "data.json"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ) as mock_get_bucket:
+        blob = get_blob(auth_config_key="custom_auth")
+        assert blob.name == "data.json"
+        mock_get_bucket.assert_called_once_with(None, auth_config_key="custom_auth")
+
+
+def test_get_blob_with_complex_pattern():
+    """Test get_blob with complex multi-level pattern."""
+    settings_manager.user_config = {
+        "default": {
+            "bucket_name": "test-bucket",
+            "blob_name_pattern": "web/{user_id}/{agent_id}/files/{basename}",
+        }
+    }
+
+    mock_bucket = MagicMock()
+    mock_blob = MagicMock()
+    mock_blob.name = "web/user123/agent456/files/document.pdf"
+    mock_bucket.blob.return_value = mock_blob
+
+    with patch(
+        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
+        return_value=mock_bucket,
+    ):
+        blob = get_blob(
+            placeholders={
+                "user_id": "user123",
+                "agent_id": "agent456",
+                "basename": "document.pdf",
+            }
+        )
+        assert blob.name == "web/user123/agent456/files/document.pdf"
+        mock_bucket.blob.assert_called_once_with(
+            "web/user123/agent456/files/document.pdf"
+        )

kiarina_lib_google_cloud_storage-1.6.1/src/kiarina/lib/google/cloud_storage/_get_blob.py

@@ -1,28 +0,0 @@
-from typing import Any
-
-from google.cloud import storage  # type: ignore[import-untyped]
-
-from ._get_bucket import get_bucket
-from .settings import settings_manager
-
-
-def get_blob(
-    blob_name: str | None = None,
-    *,
-    config_key: str | None = None,
-    auth_config_key: str | None = None,
-    **kwargs: Any,
-) -> storage.Blob:
-    settings = settings_manager.get_settings_by_key(config_key)
-
-    if blob_name is None and settings.blob_name is None:
-        raise ValueError("blob_name is not set in the settings and not provided")
-
-    if blob_name is None:
-        blob_name = settings.blob_name
-
-    if settings.blob_name_prefix:
-        blob_name = f"{settings.blob_name_prefix}/{blob_name}"
-
-    bucket = get_bucket(config_key, auth_config_key=auth_config_key, **kwargs)
-    return bucket.blob(blob_name)

kiarina_lib_google_cloud_storage-1.6.1/src/kiarina/lib/google/cloud_storage/settings.py

@@ -1,13 +0,0 @@
-from pydantic_settings import BaseSettings
-from pydantic_settings_manager import SettingsManager
-
-
-class GoogleCloudStorageSettings(BaseSettings):
-    bucket_name: str | None = None
-
-    blob_name_prefix: str | None = None
-
-    blob_name: str | None = None
-
-
-settings_manager = SettingsManager(GoogleCloudStorageSettings, multi=True)

kiarina_lib_google_cloud_storage-1.6.1/tests/test_get_blob.py

@@ -1,175 +0,0 @@
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from kiarina.lib.google.cloud_storage import get_blob, settings_manager
-
-
-def test_get_blob():
-    # Setup settings
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-            "blob_name": "test-blob.txt",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "test-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ):
-        blob = get_blob()
-        assert blob.name == "test-blob.txt"
-
-        # Verify blob was called with correct blob name
-        mock_bucket.blob.assert_called_once_with("test-blob.txt")
-
-
-def test_get_blob_with_blob_name_parameter():
-    # Setup settings
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "custom-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ):
-        blob = get_blob(blob_name="custom-blob.txt")
-        assert blob.name == "custom-blob.txt"
-
-        # Verify blob was called with custom blob name
-        mock_bucket.blob.assert_called_once_with("custom-blob.txt")
-
-
-def test_get_blob_with_blob_name_prefix():
-    # Setup settings with blob_name_prefix
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-            "blob_name_prefix": "prefix",
-            "blob_name": "test-blob.txt",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "prefix/test-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ):
-        blob = get_blob()
-        assert blob.name == "prefix/test-blob.txt"
-
-        # Verify blob was called with prefixed blob name
-        mock_bucket.blob.assert_called_once_with("prefix/test-blob.txt")
-
-
-def test_get_blob_with_blob_name_prefix_and_parameter():
-    # Setup settings with blob_name_prefix
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-            "blob_name_prefix": "prefix",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "prefix/custom-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ):
-        blob = get_blob(blob_name="custom-blob.txt")
-        assert blob.name == "prefix/custom-blob.txt"
-
-        # Verify blob was called with prefixed custom blob name
-        mock_bucket.blob.assert_called_once_with("prefix/custom-blob.txt")
-
-
-def test_get_blob_without_blob_name():
-    # Setup settings without blob_name
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-        }
-    }
-
-    with pytest.raises(
-        ValueError, match="blob_name is not set in the settings and not provided"
-    ):
-        get_blob()
-
-
-def test_get_blob_with_custom_config_key():
-    # Setup settings with custom config key
-    settings_manager.user_config = {
-        "custom": {
-            "bucket_name": "custom-bucket",
-            "blob_name": "custom-blob.txt",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "custom-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ) as mock_get_bucket:
-        blob = get_blob(config_key="custom")
-        assert blob.name == "custom-blob.txt"
-
-        # Verify get_bucket was called with custom config key and no auth_config_key
-        mock_get_bucket.assert_called_once_with("custom", auth_config_key=None)
-
-
-def test_get_blob_with_auth_config_key():
-    # Setup settings
-    settings_manager.user_config = {
-        "default": {
-            "bucket_name": "test-bucket",
-            "blob_name": "test-blob.txt",
-        }
-    }
-
-    # Mock get_bucket and blob
-    mock_bucket = MagicMock()
-    mock_blob = MagicMock()
-    mock_blob.name = "test-blob.txt"
-    mock_bucket.blob.return_value = mock_blob
-
-    with patch(
-        "kiarina.lib.google.cloud_storage._get_blob.get_bucket",
-        return_value=mock_bucket,
-    ) as mock_get_bucket:
-        blob = get_blob(auth_config_key="custom_auth")
-        assert blob.name == "test-blob.txt"
-
-        # Verify get_bucket was called with custom auth config key
-        mock_get_bucket.assert_called_once_with(None, auth_config_key="custom_auth")