kiarina-lib-google 2.0.0__tar.gz

kiarina_lib_google-2.0.0/.env.sample

@@ -0,0 +1 @@
+KIARINA_LIB_GOOGLE_TEST_SETTINGS_FILE=/path/to/your/test_settings.yaml

kiarina_lib_google-2.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# uv
+.uv_cache/
+
+# Virtual environments & config
+.venv/
+.env
+
+# OS
+.DS_Store
+
+# Project specific
+*.log
+tmp/
+packages/*/test_settings.yaml
+
+# Test data
+tests/data/large/
+
+# mise tasks (always include)
+!.mise/tasks/
+!.mise/tasks/**

kiarina_lib_google-2.0.0/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.envFile": "${workspaceFolder}/.env"
+}

kiarina_lib_google-2.0.0/CHANGELOG.md

@@ -0,0 +1,316 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2.0.0] - 2026-06-10
+
+### Changed (BREAKING)
+- **kiarina-lib-google**: Package renamed from `kiarina-lib-google-auth` to `kiarina-lib-google`.
+- Python module namespace simplified from `kiarina.lib.google.auth` to `kiarina.lib.google`.
+- `GoogleAuthSettings` has been renamed to `GoogleSettings`.
+- Environment variable prefix changed from `KIARINA_LIB_GOOGLE_AUTH_` to `KIARINA_LIB_GOOGLE_`.
+
+## [1.37.0] - 2026-05-27
+
+### Changed
+- No changes
+
+## [1.35.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.34.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.33.1] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.33.0] - 2026-01-31
+
+### Changed
+- No changes
+
+## [1.32.0] - 2026-01-30
+
+### Changed
+- No changes
+
+## [1.31.1] - 2026-01-29
+
+### Changed
+- No changes
+
+## [1.31.0] - 2026-01-29
+
+### Changed
+- No changes
+
+## [1.30.0] - 2026-01-27
+
+### Changed
+- No changes
+
+## [1.29.0] - 2026-01-16
+
+### Changed
+- No changes
+
+## [1.28.0] - 2026-01-16
+
+### Changed
+- No changes
+
+## [1.27.0] - 2026-01-12
+
+### Changed
+- No changes
+
+## [1.26.0] - 2026-01-09
+
+### Changed
+- No changes
+
+## [1.25.1] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.25.0] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.24.0] - 2026-01-08
+
+### Changed
+- No changes
+
+## [1.23.0] - 2026-01-06
+
+### Changed
+- No changes
+
+## [1.22.1] - 2026-01-06
+
+### Changed
+- Upgraded dependencies and removed unnecessary type ignore comments
+
+## [1.22.0] - 2026-01-05
+
+### Changed
+- No changes
+
+## [1.21.1] - 2026-01-05
+
+### Changed
+- No changes
+
+## [1.21.0] - 2025-12-30
+
+### Changed
+- No changes
+
+## [1.20.1] - 2025-12-25
+
+### Changed
+- No changes
+
+## [1.20.0] - 2025-12-19
+
+### Changed
+- No changes
+
+## [1.19.0] - 2025-12-19
+
+### Changed
+- No changes
+
+## [1.18.2] - 2025-12-17
+
+### Changed
+- No changes
+
+## [1.18.1] - 2025-12-16
+
+### Changed
+- No changes
+
+## [1.18.0] - 2025-12-16
+
+### Changed
+- No changes
+
+## [1.17.0] - 2025-12-15
+
+### Changed
+- No changes
+
+## [1.16.0] - 2025-12-15
+
+### Changed
+- No changes
+
+## [1.15.1] - 2025-12-14
+
+### Changed
+- No changes
+
+## [1.15.0] - 2025-12-13
+
+### Added
+- **API key authentication**: Added support for API key authentication method
+  - New `type: "api_key"` option in `GoogleSettings`
+  - New `api_key` field for storing API keys securely with `SecretStr`
+  - Enables direct API key usage for Google APIs that support it
+
+## [1.14.0] - 2025-12-13
+
+### Fixed
+- **Service account credentials**: Fixed scope application for service account credentials
+  - `get_service_account_credentials()` now accepts `scopes` parameter
+  - Scopes are properly applied via `with_scopes()` method
+  - Resolves `invalid_scope` errors when using service account credentials with Google APIs
+
+## [1.13.0] - 2025-12-09
+
+### Changed
+- No changes
+
+## [1.12.0] - 2025-12-05
+
+### Changed
+- Refactored internal module structure following project architecture rules
+- Renamed function parameters for consistency (`config_key` → `settings_key`)
+
+## [1.11.2] - 2025-12-02
+
+### Changed
+- No changes
+
+## [1.11.1] - 2025-12-01
+
+### Changed
+- No changes
+
+## [1.11.0] - 2025-12-01
+
+### Changed
+- No changes
+
+## [1.10.0] - 2025-12-01
+
+### Changed
+- No changes
+
+## [1.9.0] - 2025-11-26
+
+### Changed
+- No changes
+
+## [1.8.0] - 2025-10-24
+
+### Changed
+- No changes
+
+## [1.7.0] - 2025-10-21
+
+### Changed
+- Simplified credentials retrieval and caching logic in user account credentials handling
+
+## [1.6.3] - 2025-10-13
+
+### Changed
+- Updated `pydantic-settings-manager` dependency from `>=2.1.0` to `>=2.3.0`
+- Improved test configuration approach using YAML-based settings file instead of individual environment variables
+- Tests now use `pydantic-settings-manager` with multiple named configurations for different authentication scenarios
+- Added `test_settings.sample.yaml` as a template for test configuration
+- Added `.env.sample` to document required environment variables
+- Reorganized `GoogleSettings` field order for better readability (common fields first)
+- Enhanced test coverage with more comprehensive authentication method tests
+- Simplified test fixtures using session-scoped `load_settings` fixture
+
+## [1.6.2] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.6.1] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.6.0] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.5.0] - 2025-10-10
+
+### Changed
+- No changes
+
+## [1.4.0] - 2025-10-09
+
+### Added
+- Initial release of kiarina-lib-google
+- Google Cloud authentication library with configuration management using pydantic-settings-manager
+- Multiple authentication methods:
+  - Default credentials (Application Default Credentials)
+  - Service account authentication (from file or JSON data)
+  - User account authentication (OAuth2 authorized user credentials)
+  - Service account impersonation with configurable scopes
+- Credentials caching support with `CredentialsCache` protocol
+- Self-signed JWT generation for service accounts
+- Type safety with full type hints and Pydantic validation
+- Environment variable configuration support with `KIARINA_LIB_GOOGLE_` prefix
+- Runtime configuration overrides
+- Multiple named configurations support via pydantic-settings-manager
+- Automatic credential refresh for user accounts
+- Stable cache key generation for user account credentials
+- Default scopes for GCP, Google Drive, and Google Sheets
+
+### Features
+- **`get_credentials()`**: Main function to obtain credentials based on configuration
+- **`get_self_signed_jwt()`**: Generate self-signed JWTs for service account authentication
+- **`get_default_credentials()`**: Utility to get default Google credentials (ADC)
+- **`get_service_account_credentials()`**: Utility to get service account credentials
+- **`get_user_account_credentials()`**: Utility to get user account credentials with caching
+- **`GoogleSettings`**: Pydantic settings model with comprehensive configuration options
+- **`CredentialsCache`**: Protocol for implementing custom credentials caching strategies
+- **`Credentials`**: Type alias for all supported credential types
+
+### Security
+- **Enhanced credential protection**: Changed `service_account_data`, `client_secret_data`, and `authorized_user_data` fields to use `SecretStr`
+  - Credentials are now masked in string representations and logs (displayed as `**********`)
+  - Prevents accidental exposure of sensitive data in debug output
+  - Access secret values explicitly via `.get_secret_value()` method
+  - Minimal breaking change: only affects direct field access (use `get_*_data()` methods instead)
+
+### Configuration Options
+- `type`: Authentication type (default, service_account, user_account)
+- `service_account_file`: Path to service account key file
+- `service_account_data`: Service account key data as JSON string
+- `service_account_email`: Service account email address
+- `authorized_user_file`: Path to authorized user credentials file
+- `authorized_user_data`: Authorized user credentials as JSON string
+- `user_account_email`: User account email address
+- `client_secret_file`: Path to OAuth2 client secret file
+- `client_secret_data`: OAuth2 client secret as JSON string
+- `impersonate_service_account`: Target service account for impersonation
+- `scopes`: List of OAuth2 scopes
+- `project_id`: GCP project ID
+
+### Dependencies
+- google-api-python-client>=2.184.0
+- pydantic-settings>=2.10.1
+- pydantic-settings-manager>=2.1.0

kiarina_lib_google-2.0.0/PKG-INFO

@@ -0,0 +1,354 @@
+Metadata-Version: 2.4
+Name: kiarina-lib-google
+Version: 2.0.0
+Summary: Google Cloud client library for kiarina namespace
+Project-URL: Homepage, https://github.com/kiarina/kiarina-python
+Project-URL: Repository, https://github.com/kiarina/kiarina-python
+Project-URL: Issues, https://github.com/kiarina/kiarina-python/issues
+Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/packages/kiarina-lib-google/CHANGELOG.md
+Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-lib-google#readme
+Author-email: kiarina <kiarinadawa@gmail.com>
+Maintainer-email: kiarina <kiarinadawa@gmail.com>
+License-Expression: MIT
+Keywords: client,cloud,gcp,google,google-cloud,pydantic,settings
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: google-api-python-client>=2.184.0
+Requires-Dist: pydantic-settings-manager>=3.2.0
+Requires-Dist: pydantic-settings>=2.10.1
+Description-Content-Type: text/markdown
+
+# kiarina-lib-google
+
+A Python library for Google Cloud authentication with configuration management using pydantic-settings-manager.
+
+## Features
+
+- **Multiple Authentication Methods**: Default credentials (ADC), service accounts, and user accounts
+- **Service Account Impersonation**: Delegated access with configurable scopes
+- **Configuration Management**: Flexible configuration with pydantic-settings-manager
+- **Credentials Caching**: Automatic caching and refresh for user accounts
+- **Self-Signed JWT**: Generate JWTs for service account authentication
+- **Type Safety**: Full type hints and Pydantic validation
+
+## Installation
+
+```bash
+pip install kiarina-lib-google
+```
+
+## Quick Start
+
+### Default Credentials (ADC)
+
+```python
+from kiarina.lib.google import get_credentials
+
+# Uses Application Default Credentials
+credentials = get_credentials()
+```
+
+### Service Account
+
+```python
+from kiarina.lib.google import get_credentials, GoogleSettings
+
+# From key file
+credentials = get_credentials(
+    settings=GoogleSettings(
+        type="service_account",
+        service_account_file="~/path/to/key.json"
+    )
+)
+
+# From JSON data
+credentials = get_credentials(
+    settings=GoogleSettings(
+        type="service_account",
+        service_account_data='{"type":"service_account",...}'
+    )
+)
+```
+
+### User Account (OAuth2)
+
+```python
+# From authorized user file
+credentials = get_credentials(
+    settings=GoogleSettings(
+        type="user_account",
+        authorized_user_file="~/.config/gcloud/application_default_credentials.json",
+        scopes=["https://www.googleapis.com/auth/drive"]
+    )
+)
+```
+
+### Service Account Impersonation
+
+```python
+# Impersonate a service account
+credentials = get_credentials(
+    settings=GoogleSettings(
+        type="service_account",
+        service_account_file="~/source-key.json",
+        impersonate_service_account="target@project.iam.gserviceaccount.com",
+        scopes=["https://www.googleapis.com/auth/cloud-platform"]
+    )
+)
+```
+
+**Note**: Source principal requires `roles/iam.serviceAccountTokenCreator` role.
+
+### Credentials Caching
+
+```python
+from kiarina.lib.google import CredentialsCache
+
+class InMemoryCache(CredentialsCache):
+    def __init__(self):
+        self._cache: str | None = None
+
+    def get(self) -> str | None:
+        return self._cache
+
+    def set(self, value: str) -> None:
+        self._cache = value
+
+# Use cache for user account credentials
+credentials = get_credentials(
+    settings=GoogleSettings(
+        type="user_account",
+        authorized_user_file="~/authorized-user.json",
+        scopes=["https://www.googleapis.com/auth/drive"]
+    ),
+    cache=InMemoryCache()
+)
+```
+
+### Self-Signed JWT
+
+```python
+from kiarina.lib.google import get_self_signed_jwt
+
+jwt_token = get_self_signed_jwt(
+    settings=GoogleSettings(
+        type="service_account",
+        service_account_file="~/key.json"
+    ),
+    audience="https://your-service.example.com/"
+)
+```
+
+## Configuration
+
+### YAML Configuration (Recommended)
+
+```yaml
+kiarina.lib.google:
+  development:
+    type: user_account
+    authorized_user_file: ~/.config/gcloud/application_default_credentials.json
+    scopes:
+      - https://www.googleapis.com/auth/cloud-platform
+
+  production:
+    type: service_account
+    service_account_file: /secrets/prod-sa-key.json
+    project_id: your-project-id
+    scopes:
+      - https://www.googleapis.com/auth/cloud-platform
+
+  impersonation:
+    type: service_account
+    service_account_file: ~/source-key.json
+    impersonate_service_account: target@project.iam.gserviceaccount.com
+    scopes:
+      - https://www.googleapis.com/auth/cloud-platform
+```
+
+Load configuration:
+
+```python
+from pydantic_settings_manager import load_user_configs
+import yaml
+
+with open("config.yaml") as f:
+    config = yaml.safe_load(f)
+    load_user_configs(config)
+
+# Use configured credentials
+from kiarina.lib.google import get_credentials
+credentials = get_credentials("production")
+```
+
+### Environment Variables
+
+```bash
+export KIARINA_LIB_GOOGLE_TYPE="service_account"
+export KIARINA_LIB_GOOGLE_SERVICE_ACCOUNT_FILE="~/key.json"
+export KIARINA_LIB_GOOGLE_PROJECT_ID="your-project-id"
+export KIARINA_LIB_GOOGLE_SCOPES="https://www.googleapis.com/auth/cloud-platform"
+```
+
+### Programmatic Configuration
+
+```python
+from kiarina.lib.google import settings_manager
+
+settings_manager.user_config = {
+    "dev": {
+        "type": "user_account",
+        "authorized_user_file": "~/.config/gcloud/application_default_credentials.json"
+    },
+    "prod": {
+        "type": "service_account",
+        "service_account_file": "/secrets/key.json"
+    }
+}
+
+settings_manager.active_key = "prod"
+credentials = get_credentials()
+```
+
+## API Reference
+
+### Main Functions
+
+#### `get_credentials(settings_key=None, *, settings=None, scopes=None, cache=None)`
+
+Get Google Cloud credentials based on configuration.
+
+**Parameters:**
+- `settings_key` (str | None): Configuration key for multi-config setup
+- `settings` (GoogleSettings | None): Settings object (overrides settings_key)
+- `scopes` (list[str] | None): OAuth2 scopes (overrides settings.scopes)
+- `cache` (CredentialsCache | None): Credentials cache for user accounts
+
+**Returns:** `Credentials` - Google Cloud credentials
+
+#### `get_self_signed_jwt(settings_key=None, *, settings=None, audience)`
+
+Generate a self-signed JWT for service account authentication.
+
+**Parameters:**
+- `settings_key` (str | None): Configuration key
+- `settings` (GoogleSettings | None): Settings object
+- `audience` (str): JWT audience (target service URL)
+
+**Returns:** `str` - Self-signed JWT token
+
+### Utility Functions
+
+#### `get_default_credentials()`
+
+Get default credentials using Application Default Credentials (ADC).
+
+**Returns:** `Credentials`
+
+#### `get_service_account_credentials(*, service_account_file=None, service_account_data=None)`
+
+Get service account credentials from file or data.
+
+**Returns:** `google.oauth2.service_account.Credentials`
+
+#### `get_user_account_credentials(*, authorized_user_file=None, authorized_user_data=None, scopes, cache=None)`
+
+Get user account credentials from file or data with optional caching.
+
+**Returns:** `google.oauth2.credentials.Credentials`
+
+### Configuration
+
+#### `GoogleSettings`
+
+Pydantic settings model for authentication configuration.
+
+**Key Fields:**
+- `type`: Authentication type (`"default"`, `"service_account"`, `"user_account"`)
+- `service_account_file`: Path to service account key file
+- `service_account_data`: Service account key data (JSON string, SecretStr)
+- `authorized_user_file`: Path to authorized user file
+- `authorized_user_data`: Authorized user data (JSON string, SecretStr)
+- `impersonate_service_account`: Target service account email for impersonation
+- `scopes`: OAuth2 scopes (default: cloud-platform, drive, spreadsheets)
+- `project_id`: GCP project ID
+
+**Helper Methods:**
+- `get_service_account_data()`: Parse service_account_data JSON
+- `get_client_secret_data()`: Parse client_secret_data JSON
+- `get_authorized_user_data()`: Parse authorized_user_data JSON
+
+#### `CredentialsCache` (Protocol)
+
+Protocol for implementing credentials cache.
+
+**Methods:**
+- `get() -> str | None`: Retrieve cached credentials (JSON string)
+- `set(value: str) -> None`: Store credentials (JSON string)
+
+## Authentication Priority
+
+### Default Credentials
+
+Uses Application Default Credentials (ADC) in this order:
+
+1. `GOOGLE_APPLICATION_CREDENTIALS` environment variable (service account)
+2. `gcloud auth application-default login` credentials (user account)
+3. Compute Engine metadata server (compute engine)
+
+### Default Scopes
+
+- `https://www.googleapis.com/auth/cloud-platform` - All GCP resources
+- `https://www.googleapis.com/auth/drive` - Google Drive
+- `https://www.googleapis.com/auth/spreadsheets` - Google Sheets
+
+Override by specifying custom scopes in configuration or function call.
+
+## Testing
+
+### Setup Test Configuration
+
+> [!Note] ADC tests
+> Tests that depend on default credentials (ADC) require you to be authenticated with Google Cloud. Run `gcloud auth application-default login` before running the tests.
+
+```bash
+# Copy sample configuration
+cp packages/kiarina-lib-google/test_settings.sample.yaml \
+   packages/kiarina-lib-google/test_settings.yaml
+
+# Edit with your credentials
+# Set environment variable
+export KIARINA_LIB_GOOGLE_TEST_SETTINGS_FILE="packages/kiarina-lib-google/test_settings.yaml"
+```
+
+### Run Tests
+
+```bash
+# Run all checks
+mise run package kiarina-lib-google
+
+# Run tests with coverage
+mise run package:test kiarina-lib-google --coverage
+```
+
+## Dependencies
+
+- [google-api-python-client](https://github.com/googleapis/google-api-python-client) - Google API client
+- [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) - Settings management
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Advanced settings management
+
+## License
+
+MIT License - see the [LICENSE](../../LICENSE) file for details.
+
+## Related Projects
+
+- [kiarina-python](https://github.com/kiarina/kiarina-python) - Main monorepo
+- [pydantic-settings-manager](https://github.com/kiarina/pydantic-settings-manager) - Configuration management library