Python之python-fisco包语法、参数和实际应用案例

python-fisco 完整使用手册FISCO BCOS Python SDK一、包基础概述1. 包定义与核心定位python-fisco是FISCO BCOS 区块链官方推出的 Python 语言 SDK全称fisco-bcos-python-sdkPyPI 包名统一为python-fisco用于 Python 程序对接 FISCO BCOS 联盟链节点实现链上交互全流程开发。核心定位无需手动拼接 RPC 请求封装链节点 JSON-RPC 接口支持合约部署、调用、交易签名、区块/交易查询、账户管理、AMOP 消息、CRUD 表操作兼容 FISCO BCOS 2.0/2.5/3.0 全版本区分2.x与3.x接口逻辑支持同步/异步调用、本地离线签名、多节点负载均衡、国密/非国密双加密体系。2. 核心功能总览节点基础交互获取节点版本、区块高度、区块信息、交易回执、交易详情、链配置合约全生命周期Solidity 合约编译、部署、只读调用call、写交易sendRawTransaction账户与签名ECDSA/国密 SM2 公私钥生成、私钥本地签名、交易离线签名、账户地址转换链上数据查询按高度/哈希查区块、按哈希查交易、查回执、查交易历史、日志解析CRUD 存储表FISCO BCOS 内置 Table 表增删改查、联合索引、分页查询AMOP 点对点消息链下服务间加密点对点通信跨机构数据传输权限管理节点权限、合约部署白名单、账户权限、群组管理异步并发异步接口批量发送交易高并发场景性能优化事件监听实时订阅合约 Event 事件自动解析事件参数国密支持SM2签名、SM3哈希、SM4加密适配政务、金融等合规场景。3. 环境适配要求项目适配标准Python版本Python3.6 ~ Python3.11不支持3.12部分依赖FISCO链版本2.x群组链、3.x并行链操作系统Windows/Linux/macOS依赖库pycryptodome、requests、pyserial、websockets、gmssl国密二、完整安装教程方式1PyPI 在线安装推荐普通非国密版本pipinstallpython-fisco国密GM版本支持SM2/SM3/SM4pipinstallpython-fisco[gm]指定版本安装pipinstallpython-fisco2.9.0方式2源码编译安装官方仓库最新版拉取官方SDK仓库gitclone https://github.com/FISCO-BCOS/python-sdk.gitcdpython-sdk本地安装# 普通版python3 setup.pyinstall# 国密版python3 setup.pyinstall--gm3. 依赖修复常见命令# 升级pippipinstall--upgradepip# 修复加密库报错pipinstallpycryptodome gmssl websockets requests4. 前置配置文件必须python-fisco运行依赖config.ini链节点连接配置文件模板内置在SDK中核心配置项[rpc] # 链节点RPC地址多节点逗号分隔 rpc_url http://127.0.0.1:8545,http://127.0.0.1:8546 # 链群组IDFISCO2.x必填 group_id 1 # 链版本 2/3 chain_version 2 # 国密开关 0非国密 1国密 is_gm 0 [account] # 账户私钥路径SDK内置accounts文件夹 private_key 0x789...三、核心语法、对象与参数详解1. 核心顶层对象FiscoBcosClient程序入口类所有链交互通过该实例调用初始化核心参数fromfisco_bcosimportFiscoBcosClient# 初始化方式1读取配置文件clientFiscoBcosClient(config.ini)# 初始化方式2代码动态传参不读取文件clientFiscoBcosClient(rpc_urls[http://127.0.0.1:8545],group_id1,chain_version2,is_gmFalse,private_key0xxxxx私钥字符串)FiscoBcosClient 初始化参数明细参数类型说明config_pathstr配置文件路径传参则无需填rpc等参数rpc_urlslist[str]节点RPC接口列表支持多节点自动故障切换group_idintFISCO群组ID2.x多群组必填3.x固定1chain_versionint链版本 2 / 3接口逻辑差异大is_gmbool是否国密链True启用SM2签名private_keystr发送交易的签名账户私钥0x开头十六进制timeoutintRPC请求超时时间默认30秒async_enablebool开启异步调用默认False2. 合约对象Contract用于部署、调用智能合约核心构造参数# abi合约ABI字符串/列表bytecode合约编译字节码contractclient.get_contract(abi,bytecode)Contract 核心方法deploy()部署合约上链返回合约地址、交易回执参数构造函数入参*args、gas限制、区块限制call_func(func_name, *args)只读调用合约view函数不上链、不消耗gassend_transaction(func_name, *args)发送写交易修改链上状态返回交易哈希与回执get_event_logs(tx_hash)解析交易内所有合约Event事件日志3. 交易、区块查询核心接口参数1获取区块高度block_heightclient.get_block_number()# 无入参返回int数字2按高度获取区块# 参数1区块高度参数2是否返回完整交易详情 True/Falseblock_infoclient.get_block_by_number(100,True)3发送原始交易# raw_tx本地签名后的交易十六进制字符串tx_hashclient.send_raw_transaction(raw_tx)4获取交易回执# tx_hash交易哈希0x开头receiptclient.get_transaction_receipt(tx_hash)4. 账户签名工具类Accountfromfisco_bcos.accountimportAccount# 生成新账户私钥地址accAccount(is_gmFalse)priv_keyacc.private_key addracc.address# 私钥签名交易signed_txacc.sign_transaction(tx_data)5. CRUD Table 表操作参数FISCO内置分布式表参数表名、主键名、字段字典、查询条件、分页offset/limit# 插入数据client.table_insert(table_nameUserTable,keyuser001,fields{name:test,age:18})# 查询resclient.table_select(table_nameUserTable,keyuser001)四、8个完整可运行实战应用案例前置统一环境本地启动FISCO BCOS 2.0单群组节点config.ini配置完成Python3.9非国密链。案例1基础节点信息查询读取链基础数据功能获取链高度、节点版本、群组信息只读无交易fromfisco_bcosimportFiscoBcosClient# 初始化客户端clientFiscoBcosClient(config.ini)# 1. 获取当前区块高度heightclient.get_block_number()print(f当前链高度{height})# 2. 获取节点版本node_versionclient.get_node_version()print(f节点版本信息{node_version})# 3. 获取群组列表group_listclient.get_group_list()print(f节点支持群组{group_list})client.close()案例2生成链上账户离线公私钥创建功能本地生成ECDSA签名账户无需连接节点用于多用户管理fromfisco_bcos.accountimportAccount# 生成非国密账户user_accAccount(is_gmFalse)print(账户私钥,user_acc.private_key)print(账户地址,user_acc.address)# 国密SM2账户gm_accAccount(is_gmTrue)print(国密私钥,gm_acc.private_key)print(国密地址,gm_acc.address)# 私钥导入恢复账户priv0x748f97b4340a4171282a733c495376944014f5a75a437f82551a4a17a274c316load_accAccount.from_private_key(priv,is_gmFalse)print(导入恢复地址,load_acc.address)案例3Solidity合约部署上链基础存证合约示例pragma solidity ^0.4.25; contract Evidence { mapping(string string) public data; function save(string key, string val) public { data[key] val; } function get(string key) public view returns(string) { return data[key]; } }Python部署代码fromfisco_bcosimportFiscoBcosClient clientFiscoBcosClient(config.ini)# 合约编译后的ABI与Bytecode编译工具fisco-solc输出abi[{inputs:[{name:key,type:string},{name:val,type:string}],name:save,outputs:[],type:function},...]bytecode608060405234801561001057600080fd5b5060...# 获取合约对象evidence_contractclient.get_contract(abi,bytecode)# 部署合约无构造参数deploy_receiptevidence_contract.deploy()contract_addrdeploy_receipt[contractAddress]print(部署成功合约地址,contract_addr)print(部署交易哈希,deploy_receipt[transactionHash])client.close()案例4合约只读调用view函数查询不消耗gas承接案例3已部署存证合约读取链上存证数据fromfisco_bcosimportFiscoBcosClient clientFiscoBcosClient(config.ini)abi[合约完整ABI]contract_addr0x123456789abcdef...# 绑定已部署合约地址evidenceclient.get_contract(abi,addresscontract_addr)# 只读调用get查询数据不上链resultevidence.call_func(get,file001)print(链上存证内容,result)client.close()案例5合约写交易修改链上状态发送交易调用合约save方法写入存证数据生成链上交易并获取回执fromfisco_bcosimportFiscoBcosClient clientFiscoBcosClient(config.ini)abi[合约完整ABI]contract_addr0x123456789abcdef...evidenceclient.get_contract(abi,addresscontract_addr)# 发送写交易修改链数据tx_hashevidence.send_transaction(save,file001,2026存证文件哈希123xyz)print(交易哈希,tx_hash)# 等待并获取交易回执receiptclient.get_transaction_receipt(tx_hash)print(交易执行状态,receipt[status])# 0x0成功0x1失败print(区块高度,receipt[blockNumber])client.close()案例6区块、交易数据遍历与日志解析批量查询区块提取交易哈希、解析合约Event事件fromfisco_bcosimportFiscoBcosClient clientFiscoBcosClient(config.ini)current_heightclient.get_block_number()# 查询最新10个区块forhinrange(current_height-10,current_height1):blockclient.get_block_by_number(h,True)tx_listblock[transactions]print(f区块{h}交易数量{len(tx_list)})fortxintx_list:txhtx[hash]receiptclient.get_transaction_receipt(txh)# 解析合约事件日志logsreceipt[logs]iflogs:print(f交易{txh}包含事件{logs})client.close()案例7FISCO CRUD Table分布式表增删改查使用链内置Table存储结构化业务数据无需编写合约fromfisco_bcosimportFiscoBcosClient clientFiscoBcosClient(config.ini)table_nameUserInfoprimary_keyuser_id_001# 1. 插入数据insert_resclient.table_insert(table_nametable_name,keyprimary_key,fields{username:张三,id_card:110xxxx,balance:1000})print(插入结果,insert_res)# 2. 单条查询query_resclient.table_select(table_name,primary_key)print(查询用户数据,query_res)# 3. 更新字段update_resclient.table_update(table_nametable_name,keyprimary_key,fields{balance:2000})print(更新余额结果,update_res)# 4. 删除数据del_resclient.table_delete(table_name,primary_key)print(删除结果,del_res)client.close()案例8AMOP 链下点对点消息通信FISCO跨机构服务加密通信A服务发送、B服务订阅接收消息发送端代码fromfisco_bcos.amopimportAmopClient amopAmopClient(config.ini)# 订阅主题topictopiccompany_a_data# 发送二进制消息msgb机构A同步业务数据20260620amop.send(topic,msg)amop.close()接收端异步监听代码fromfisco_bcos.amopimportAmopClient amopAmopClient(config.ini)topiccompany_a_data# 定义消息回调函数defmsg_callback(topic,data):print(f收到主题{topic}消息{data.decode(utf-8)})# 订阅主题持续监听amop.subscribe(topic,msg_callback)# 持续阻塞接收amop.listen_forever()五、常见报错、原因与解决方案1. 安装报错 ModuleNotFoundError: gmssl原因未安装国密依赖直接使用国密模式解决pip install python-fisco[gm]2. RPC连接失败 ConnectionRefusedError原因1FISCO节点未启动RPC端口未开放原因2config.ini中rpc_url端口写错、防火墙拦截8545端口解决启动节点核对rpc地址关闭防火墙或放行端口3. 交易回执status0x1交易执行失败常见诱因合约函数入参类型不匹配字符串传数字、数组长度错误合约内部revert报错余额不足、权限校验失败合约地址不存在或群组ID配置错误解决核对ABI与入参本地调试Solidity逻辑确认group_id一致4. Private Key格式错误 InvalidPrivateKey原因私钥缺少0x前缀、非十六进制字符串、国密链使用ECDSA私钥解决私钥统一加0x国密链使用Account(is_gmTrue)生成私钥5. get_block_by_number返回空数组原因查询高度超过当前链高度、群组ID与节点不匹配解决先调用get_block_number获取真实高度再查询修正config.ini group_id6. 异步调用websockets报错原因python版本过高3.12websockets依赖不兼容解决降级Python至3.9/3.10重装websockets10.47. Table表插入报错 TableNotExist原因未在链初始化创建Table表解决部署TableManager合约或使用控制台创建对应表结构8. AMOP收不到消息原因两端topic名称大小写不一致、节点跨机构证书未互信解决topic完全一致节点证书互相导入许可六、使用注意事项生产环境重点1. 私钥安全规范禁止硬编码私钥在代码中使用环境变量、加密密钥管理服务生产环境禁止明文存储私钥使用AES加密存储多用户场景统一离线生成账户服务端不保存原始私钥。2. 链节点高可用配置config.ini配置多个rpc_urlSDK自动故障转移生产环境开启HTTPS RPC关闭HTTP明文接口增加timeout超时参数避免节点卡死导致程序阻塞。3. 并发交易性能优化高并发场景开启async_enableTrue异步发送交易批量交易添加延时避免节点限流报错监听合约Event使用长连接websocket轮询会造成性能损耗。4. 国密/非国密环境隔离国密链必须统一is_gm1ABI、私钥、节点加密模式全部匹配国密链不可使用普通ECDSA账户发送交易签名校验失败。5. 合约ABI维护Solidity版本与SDK编译工具fisco-solc版本对齐合约修改后必须更新ABI与bytecode否则调用参数解析错乱线上合约地址持久化存储不要每次重新部署。6. 数据上链合规敏感身份证、手机号等隐私数据建议哈希后上链明文不上链完整业务原始数据存储链下数据库链仅存校验哈希用于存证核验。7. 资源释放程序退出必须调用client.close()、amop.close()关闭RPC/AMOP长连接避免端口占用、连接泄露。8. 版本兼容区分FISCO BCOS 2.x与3.x接口存在不兼容群组机制、并行交易、存储结构差异部署前确认链版本修改config.ini中chain_version参数。《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章前6章涵盖深度学习基础包括张量运算、神经网络原理、数据预处理及卷积神经网络等后5章进阶探讨图像、文本、音频建模技术并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法每章附有动手练习题帮助读者巩固实战能力。内容兼顾数学原理与工程实现适配PyTorch框架最新技术发展趋势。