Metadata-Version: 2.4
Name: kxy-open-id-client
Version: 0.1.1
Summary: Client library for KXY Open ID Service - ID segment allocation
Author: KXY Development Team
License: MIT
Project-URL: Homepage, https://github.com/kxy/kxy-open-id-client
Project-URL: Documentation, https://github.com/kxy/kxy-open-id-client#readme
Project-URL: Repository, https://github.com/kxy/kxy-open-id-client
Project-URL: Issues, https://github.com/kxy/kxy-open-id-client/issues
Keywords: kxy,open-id,id-generator,distributed-id,segment
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# kxy-open-id-client

Python 客户端库,用于对接 KXY Open ID 服务,实现分布式 ID 分段分配。

## 特性

- 简洁易用的 API
- 支持同步和异步调用
- 完整的类型提示支持
- 详细的错误处理
- 基于 httpx 的高性能 HTTP 客户端

## 安装

### 使用 pip 安装

```bash
pip install kxy-open-id-client
```

### 从源码安装

```bash
git clone https://github.com/kxy/kxy-open-id-client.git
cd kxy-open-id-client
pip install -e .
```

## 快速开始

### 基础用法(同步)

```python
from kxy_open_id_client import SegmentClient

# 创建客户端实例
client = SegmentClient(base_url="http://localhost:5801")

# 分配 ID 段
segment = client.allocate_segment(
    system_code="my-system",
    db_name="my_database",
    table_name="users",
    field_name="id",
    segment_count=10000  # 可选,默认 10000
)

print(f"分配到的 ID 段: {segment.start} 到 {segment.end}")
# 输出: 分配到的 ID 段: 1 到 10000
```

### 异步用法

```python
import asyncio
from kxy_open_id_client import SegmentClient

async def main():
    client = SegmentClient(base_url="http://localhost:5801")

    # 异步分配 ID 段
    segment = await client.allocate_segment_async(
        system_code="my-system",
        db_name="my_database",
        table_name="orders",
        field_name="order_id",
        segment_count=5000
    )

    print(f"分配到的 ID 段: {segment.start} 到 {segment.end}")

asyncio.run(main())
```

## 详细用法

### 客户端配置

```python
from kxy_open_id_client import SegmentClient

client = SegmentClient(
    base_url="http://localhost:5801",  # 服务地址
    timeout=30.0,                      # 请求超时时间(秒)
    verify_ssl=True,                   # 是否验证 SSL 证书
    headers={                          # 自定义请求头
        "X-Custom-Header": "value"
    }
)
```

### 错误处理

```python
from kxy_open_id_client import (
    SegmentClient,
    OpenIdAPIError,
    OpenIdConnectionError,
    OpenIdTimeoutError
)

client = SegmentClient(base_url="http://localhost:5801")

try:
    segment = client.allocate_segment(
        system_code="my-system",
        db_name="my_database",
        table_name="users",
        field_name="id"
    )
except OpenIdAPIError as e:
    # API 返回错误响应
    print(f"API 错误 {e.code}: {e.msg}")
    if e.trace_id:
        print(f"Trace ID: {e.trace_id}")
except OpenIdConnectionError as e:
    # 连接失败
    print(f"连接错误: {e}")
except OpenIdTimeoutError as e:
    # 请求超时
    print(f"请求超时: {e}")
```

### 实际应用示例

```python
from kxy_open_id_client import SegmentClient

class IDGenerator:
    """ID 生成器,基于分段分配"""

    def __init__(self, client: SegmentClient, system_code: str,
                 db_name: str, table_name: str, field_name: str):
        self.client = client
        self.system_code = system_code
        self.db_name = db_name
        self.table_name = table_name
        self.field_name = field_name

        self.current = 0
        self.end = 0

    def next_id(self) -> int:
        """获取下一个 ID"""
        if self.current >= self.end:
            # 当前段已用完,分配新的段
            self._allocate_new_segment()

        self.current += 1
        return self.current

    def _allocate_new_segment(self):
        """分配新的 ID 段"""
        segment = self.client.allocate_segment(
            system_code=self.system_code,
            db_name=self.db_name,
            table_name=self.table_name,
            field_name=self.field_name,
            segment_count=10000
        )
        self.current = segment.start - 1
        self.end = segment.end

# 使用示例
client = SegmentClient(base_url="http://localhost:5801")
id_gen = IDGenerator(
    client=client,
    system_code="my-system",
    db_name="my_database",
    table_name="users",
    field_name="id"
)

# 生成 ID
for _ in range(5):
    print(f"Generated ID: {id_gen.next_id()}")
```

## API 参考

### SegmentClient

#### `__init__(base_url, timeout=30.0, verify_ssl=True, headers=None)`

创建客户端实例。

**参数:**
- `base_url` (str): KXY Open ID 服务的基础 URL
- `timeout` (float): 请求超时时间,默认 30 秒
- `verify_ssl` (bool): 是否验证 SSL 证书,默认 True
- `headers` (dict): 自定义请求头,可选

#### `allocate_segment(system_code, db_name, table_name, field_name, segment_count=10000)`

同步分配 ID 段。

**参数:**
- `system_code` (str): 系统代码
- `db_name` (str): 数据库名称
- `table_name` (str): 表名
- `field_name` (str): 字段名
- `segment_count` (int): 分配的 ID 数量,默认 10000

**返回:** `SegmentResponse` 对象,包含 `start` 和 `end` 属性

**异常:**
- `OpenIdAPIError`: API 返回错误
- `OpenIdConnectionError`: 连接失败
- `OpenIdTimeoutError`: 请求超时

#### `allocate_segment_async(system_code, db_name, table_name, field_name, segment_count=10000)`

异步分配 ID 段(参数和返回值同上)。

### 数据模型

#### SegmentRequest
- `system_code`: str
- `db_name`: str
- `table_name`: str
- `field_name`: str
- `segment_count`: int (默认 10000,最大 2^63-1)

#### SegmentResponse
- `start`: int - 段起始 ID
- `end`: int - 段结束 ID

#### ApiResponse[T]
- `code`: int - 状态码 (0 表示成功)
- `msg`: str - 消息
- `data`: Optional[T] - 数据
- `traceId`: Optional[str] - 追踪 ID

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 运行测试

```bash
pytest
```

### 代码格式化

```bash
black kxy_open_id_client
```

### 类型检查

```bash
mypy kxy_open_id_client
```

## 许可证

MIT License

## 相关项目

- [kxy-open-id](https://github.com/kxy/kxy-open-id) - KXY Open ID 服务端
