smooth-google-api-client 0.1.0
A Python HTTP client library for Google Translation API Server
License: MIT
Requires Python: >=3.8
Keywords: google, translation, client, api, http-client, async, httpx

# Google API Client

A Python client library for Google Cloud APIs.

## Installation

### From Source

```bash
cd google-api-client
pip install -e .
```

Or install dependencies only:

```bash
pip install -r requirements.txt
```

### Using pip

```bash
pip install google-api-client
```

## Features

- **Interface Segregation**: Clean separation of interface and implementation
- **Strong Typing**: Full type hints for better IDE support and error detection
- HTTP client interface for Google API Server
- Easy integration with Translation API
- Support for custom domain configuration
- Async/await support
- Streaming translation support
- Batch translation support
- **Testability**: Easy to create mock implementations
- **Extensibility**: Multiple implementations possible (HTTP, gRPC, etc.)

## Architecture

The library follows **Interface Segregation Principle** with clear separation:

- **Interface** (`interface.py`): Protocol definition for type checking
- **Implementation** (`client.py`): HTTP client implementation
- **Types** (`types.py`): Strong type definitions
- **Response** (`response.py`): Response data models

This separation enables:
- ✅ Easy testing with mock implementations
- ✅ Multiple implementations (HTTP, gRPC, WebSocket, etc.)
- ✅ Strong type safety and IDE support
- ✅ Dependency injection and loose coupling

## Quick Start

### Basic Usage

```python
import asyncio
from google_api_client import GoogleAPIClient

async def main():
    # Create client with custom domain
    async with GoogleAPIClient(base_url="http://localhost:8000") as client:
        # Translate text
        result = await client.translate(
            text="Hello, World!",
            source_language="en",
            target_language="zh-CN"
        )
        print(f"Translated: {result.translated_text}")

asyncio.run(main())
```

### Using Interface for Dependency Injection

```python
from google_api_client import IGoogleAPIClient, GoogleAPIClient

async def translate_text(client: IGoogleAPIClient, text: str):
    """Function accepts interface, allowing easy testing with mocks"""
    return await client.translate(text, "en", "zh-CN")

# Use concrete implementation
async with GoogleAPIClient() as client:
    result = await translate_text(client, "Hello")
```

### Custom Domain Configuration

```python
from google_api_client import GoogleAPIClient

# Use custom domain
client = GoogleAPIClient(base_url="https://api.example.com")

# Or with port
client = GoogleAPIClient(base_url="http://192.168.1.100:8000")

# Or with subdomain
client = GoogleAPIClient(base_url="https://translate.company.com")
```

### Batch Translation

```python
async with GoogleAPIClient(base_url="http://localhost:8000") as client:
    result = await client.translate_to_multiple(
        text="Good morning!",
        source_language="en",
        target_languages=["zh-CN", "ja", "es", "fr", "de"]
    )
    
    for lang, translation in result.translations.items():
        print(f"{lang}: {translation}")
```

### Streaming Translation

```python
async with GoogleAPIClient(base_url="http://localhost:8000") as client:
    async for data in client.translate_stream(
        text="Hello, World!",
        source_language="en",
        target_languages=["zh-CN", "ja", "es"]
    ):
        if data.get('type') == 'translation':
            print(f"{data.get('language')}: {data.get('translated_text')}")
```

### Language Detection

```python
async with GoogleAPIClient(base_url="http://localhost:8000") as client:
    result = await client.detect_language("Hello, how are you?")
    print(f"Detected language: {result.detected_language}")
```

## API Reference

### GoogleAPIClient

Main client class for interacting with Google API Server.

#### Constructor

```python
GoogleAPIClient(
    base_url: str = "http://localhost:8000",
    timeout: float = 30.0,
    max_retries: int = 3
)
```

**Parameters:**
- `base_url`: Base URL of the API server (default: "http://localhost:8000")
- `timeout`: Request timeout in seconds (default: 30.0)
- `max_retries`: Maximum number of retry attempts (default: 3)

#### Methods

##### translate()

Translate text from source language to target language.

```python
result: TranslationResponse = await client.translate(
    text: str,
    source_language: str,
    target_language: str
)
```

##### translate_to_multiple()

Translate text to multiple languages concurrently.

```python
result: BatchTranslationResponse = await client.translate_to_multiple(
    text: str,
    source_language: str,
    target_languages: List[str]
)
```

##### detect_language()

Detect the language of text.

```python
result: LanguageDetectionResponse = await client.detect_language(text: str)
```

##### translate_stream()

Stream translations using Server-Sent Events (SSE).

```python
async for data in client.translate_stream(
    text: str,
    source_language: str,
    target_languages: List[str]
):
    # Process each translation result
    pass
```

### Response Types

#### TranslationResponse

```python
@dataclass
class TranslationResponse:
    original_text: str
    translated_text: str
    source_language: str
    target_language: str
```

#### BatchTranslationResponse

```python
@dataclass
class BatchTranslationResponse:
    original_text: str
    source_language: str
    translations: Dict[str, str]  # Map of target language to translation
```

#### LanguageDetectionResponse

```python
@dataclass
class LanguageDetectionResponse:
    text: str
    detected_language: str
```

## Configuration

### Enabling Required APIs

Make sure the following APIs are enabled in your Google Cloud project:
- Google Cloud Translation API

## Requirements

- Python 3.8 or higher
- httpx>=0.24.0 (for HTTP client)

### Dependencies

- httpx>=0.24.0

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.