Metadata-Version: 2.4
Name: kiarina-lib-google
Version: 2.2.1
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

English | [日本語](README.ja.md)

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=None, 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: empty)
- `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

No scopes are requested by default. Specify only the scopes required by the
application in configuration or the function call.

User account credentials reuse scopes stored in the authorized user data when
no scopes are specified. Service account impersonation requires at least one
explicit scope.

## 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:check 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
