feie-print-sdk 1.0.0__tar.gz

feie_print_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Mr.Lee]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feie_print_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,342 @@
+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 ⭐️，感谢支持！

feie_print_sdk-1.0.0/README.md

@@ -0,0 +1,306 @@
+# 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 ⭐️，感谢支持！