Metadata-Version: 2.4
Name: feie-print-sdk
Version: 1.0.0
Summary: 飞鹅云打印Python SDK
Home-page: https://https://gitee.com/HN_Lee/feie-print-sdk
Author: Mr.Li
Author-email: 543662945@qq.com
License: MIT
Keywords: feieyun printer print esc-pos sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.7
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: Topic :: Printing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Feie Print SDK

<h1 align="center">飞鹅云打印 Python SDK</h4>


飞鹅云打印 API 的 Python SDK 封装，支持打印、状态查询等功能。


## Requirement

```
Python >= 3.7
```

## Installation

```bash
pip install feie-print-sdk
```

## Quick Start

#### 第一步：引入模块

```python
from feie_print_sdk import FeieClient
```

#### 第二步：实例化客户端

```python
client = FeieClient(
    user='yourname@mail.com',          # 飞鹅云用户名（邮箱）
    ukey='yourukey'            # 飞鹅云UKEY
)
```

#### 第三步：发送打印请求

```python
# 打印
success, message = client.print(
    sn='932521687',                    # 打印机序列号
    content='<BOLD>测试打印</BOLD><BR>' # 打印内容（ESC/POS指令）
)

if success:
    print(f'✅ 打印成功: {message}')
else:
    print(f'❌ 打印失败: {message}')
```

#### 第四步：查询打印机状态（可选）

```python
ok, status = client.query_status('932521687')
print(f'打印机状态: {status}')
```

#### 完整示例

```python
from feie_print_sdk import FeieClient

# 初始化客户端
client = FeieClient(
    user='your_feie_username@mail.com',
    ukey='your_feie_ukey'
)

# 打印
success, msg = client.print(
    sn='your_sn',
    content='''
        <C><L><BOLD>门店测试 - 拣货联</BOLD></L></C><BR>
        订单号: <BOLD>20241001001</BOLD><BR>
        商品: 测试商品 x 1<BR>
        合计: 10.00 元<BR>
    ''',
    times=1
)
print(f'打印结果: {success}, {msg}')

# 查询打印机状态
ok, status = client.query_status('932521687')
print(f'打印机状态: {ok}, {status}')

# 关闭客户端
client.close()
```

## Usage or Instructions

### 1. 核心类说明

| 模块 | 说明 |
|------|------|
| `FeieClient` | 主客户端，统一入口 |
| `FeieError` | SDK基础异常 |
| `AuthError` | 认证异常 |
| `NetworkError` | 网络异常 |
| `PrintError` | 打印异常 |
| `StatusError` | 状态查询异常 |

### 2. 初始化配置

```python
from feie_print_sdk import FeieClient

# 方式一：默认API地址
client = FeieClient(
    user='your_feie_username@mail.com',
    ukey='your_feie_ukey'
)

# 方式二：自定义API地址和超时时间
client = FeieClient(
    user='your_feie_username@mail.com',
    ukey='your_feie_ukey',
    url='http://api.feieyun.cn/Api/Open/',  # 可选
    timeout=30                               # 可选，默认30秒
)
```

### 3. 打印接口

```python
# 基本打印
success, message = client.print(
    sn='932521687',      # 打印机序列号
    content='打印内容'    # ESC/POS指令格式
)

# 多份打印
success, message = client.print(
    sn='your_sn',
    content='打印内容',
    times=3               # 打印3份
)

# 批量打印（使用循环）
sn_list = ['your_sn1', 'your_sn2', 'your_sn3']
for sn in sn_list:
    client.print(sn, '测试内容')
    time.sleep(1)  # 避免请求过快
```

### 4. 状态查询接口

```python
# 查询单个打印机状态
ok, status = client.query_status('your_sn')

if ok:
    print(f'✅ 打印机正常: {status}')
else:
    print(f'❌ 打印机异常: {status}')
```

### 5. 使用上下文管理器（推荐）

```python
from feie_print_sdk import FeieClient

with FeieClient(user='xxx', ukey='xxx') as client:
    success, msg = client.print('your_sn', '测试内容')
    # 自动关闭客户端，释放资源
```

### 6. 异常处理

```python
from feie_print_sdk import (
    FeieClient,
    AuthError,
    NetworkError,
    PrintError
)

try:
    client = FeieClient(user='xxx', ukey='xxx')
    success, msg = client.print('your_sn', '测试内容')
except AuthError as e:
    print(f'❌ 认证失败: {e}')
except NetworkError as e:
    print(f'❌ 网络异常: {e}')
except PrintError as e:
    print(f'❌ 打印失败: {e}')
```

### 7. 扩展自定义功能

```python
from feie_print_sdk import FeieClient
import time

class MyFeieClient(FeieClient):
    """自定义客户端（添加重试功能）"""
    
    def print_with_retry(self, sn, content, retry=3, delay=2):
        """
        带重试的打印
        """
        for i in range(retry):
            success, msg = self.print(sn, content)
            if success:
                return True, msg
            print(f'第 {i+1} 次重试...')
            time.sleep(delay)
        return False, f'重试 {retry} 次后仍然失败'

# 使用
client = MyFeieClient(user='xxx', ukey='xxx')
success, msg = client.print_with_retry('932521687', '测试', retry=5)
```

## API Reference

### FeieClient

#### `__init__(user, ukey, url=None, timeout=30)`

初始化飞鹅云客户端

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `user` | str | ✅ | 飞鹅云用户名（邮箱） |
| `ukey` | str | ✅ | 飞鹅云UKEY |
| `url` | str | ❌ | API地址（默认官方地址） |
| `timeout` | int | ❌ | 请求超时时间（秒，默认30） |

#### `print(sn, content, times=1)`

发送打印请求

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sn` | str | ✅ | 打印机序列号 |
| `content` | str | ✅ | 打印内容（ESC/POS指令） |
| `times` | int | ❌ | 打印份数（默认1） |

**返回**: `(bool, str)` - (是否成功, 消息)

#### `query_status(sn)`

查询打印机状态

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sn` | str | ✅ | 打印机序列号 |

**返回**: `(bool, str)` - (是否正常, 状态描述)

#### `close()`

关闭客户端，释放资源

### 异常类

| 异常 | 说明 |
|------|------|
| `FeieError` | SDK基础异常 |
| `AuthError` | 认证异常（参数错误、签名错误） |
| `APIError` | API调用异常（业务返回错误） |
| `NetworkError` | 网络异常（超时、连接失败） |
| `PrintError` | 打印异常 |
| `StatusError` | 状态查询异常 |

### 数据模型

| 模型 | 说明 |
|------|------|
| `PrintRequest` | 打印请求模型 |
| `StatusRequest` | 状态查询请求模型 |
| `PrintResponse` | 打印响应模型 |
| `StatusResponse` | 状态查询响应模型 |

## ChangeLog

### [v1.0.0] - 2026-01-18

- **Feature**: 初始版本发布
- **Feature**: 支持打印功能 (`print`)
- **Feature**: 支持打印机状态查询 (`query_status`)
- **Feature**: 支持上下文管理器
- **Feature**: 统一的异常处理体系
- **Feature**: 请求超时控制
- **Feature**: 完整的类型提示

## License

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系

- 作者: Your Name
- 邮箱: your_email@example.com
- GitHub: [https://gitee.com/HN_Lee/feie-print-sdk](https://gitee.com/HN_Lee/feie-print-sdk)

---

如果觉得好用，请在 Gitee 上给个 Star ⭐️，感谢支持！
