feie-print-sdk 1.0.0

飞鹅云打印Python SDK

Feie Print SDK

飞鹅云打印 Python SDK

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

Requirement

Python >= 3.7

Installation

pip install feie-print-sdk

Quick Start

第一步：引入模块

from feie_print_sdk import FeieClient

第二步：实例化客户端

client = FeieClient(
    user='[e-mail]',          # 飞鹅云用户名（邮箱）
    ukey='yourukey'            # 飞鹅云UKEY
)

第三步：发送打印请求

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

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

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

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

完整示例

from feie_print_sdk import FeieClient

# 初始化客户端
client = FeieClient(
    user='[e-mail]',
    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. 初始化配置

from feie_print_sdk import FeieClient

# 方式一：默认API地址
client = FeieClient(
    user='[e-mail]',
    ukey='your_feie_ukey'
)

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

3. 打印接口

# 基本打印
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. 状态查询接口

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

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

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

from feie_print_sdk import FeieClient

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

6. 异常处理

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. 扩展自定义功能

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
• 邮箱: [e-mail]
• GitHub: https://gitee.com/HN_Lee/feie-print-sdk

---

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