py-ipfs-http-client API全解析：覆盖文件、网络、配置的完整参考手册

【免费下载链接】py-ipfs-http-client A python client library for the IPFS API 项目地址: https://gitcode.com/gh_mirrors/py/py-ipfs-http-client

py-ipfs-http-client是一个功能强大的Python客户端库，专为IPFS API设计，让开发者能够轻松与IPFS网络交互，实现文件管理、网络配置等核心功能。本指南将系统介绍其API结构、核心功能及使用方法，帮助新手快速掌握这个实用工具。

一、快速入门：API架构概览

py-ipfs-http-client采用模块化设计，将IPFS功能划分为多个专项模块，每个模块对应特定的IPFS功能域。核心模块集中在ipfshttpclient/client/目录下，主要包括：

• 文件操作：files.py（文件增删改查）、object.py（DAG对象管理）
• 网络管理：swarm.py（节点连接）、dht.py（分布式哈希表）
• 系统配置：config.py（节点配置）、repo.py（仓库管理）

初始化客户端

使用connect()函数创建IPFS连接是所有操作的起点：

import ipfshttpclient
client = ipfshttpclient.connect()  # 默认连接本地IPFS节点

二、文件管理核心API 🔑

文件操作是IPFS的核心功能，py-ipfs-http-client提供了丰富的API接口，支持从简单的文件上传到复杂的目录管理。

1. 文件上传与获取

• 添加文件/目录：add()方法支持单个文件、多个文件或目录的上传，返回唯一的CID（内容标识符）

# 添加单个文件
cid = client.add("localfile.txt")['Hash']

# 添加目录
cid = client.add("localdirectory/", recursive=True)['Hash']

• 获取文件：get()方法通过CID将IPFS网络中的文件下载到本地

client.get(cid, target="/path/to/save")  # 保存到指定路径

2. 文件系统操作

files.py模块模拟了类Unix文件系统操作，支持以下常用方法：

方法	功能描述	参数示例
ls(path)	列出IPFS路径下的内容	client.files.ls("/ipfs/QmXYZ...")
mkdir(path)	创建IPFS目录	client.files.mkdir("/myipfsdir", parents=True)
cp(source, dest)	复制IPFS文件/目录	client.files.cp("/ipfs/src", "/ipfs/dest")
rm(path)	删除IPFS文件/目录	client.files.rm("/ipfs/oldfile", recursive=True)

三、网络与节点管理 🖧

1. 节点连接控制

swarm.py模块负责节点的网络连接管理：

• 添加/删除节点地址：

  # 添加引导节点
  client.swarm.add("/ip4/104.131.131.82/tcp/4001/ipfs/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ")
  
  # 查看已连接节点
  peers = client.swarm.peers()
  

2. 分布式哈希表(DHT)操作

dht.py模块提供内容发现和路由功能：

• 查找内容提供者：findprovs(cid)返回存储指定内容的节点列表
• 发布/获取键值对：put(key, value)和get(key)实现分布式数据存储

# 查找内容提供者
providers = client.dht.findprovs("QmXYZ...")

# 存储键值对
client.dht.put("mykey", "mydata")

四、系统配置与维护 ⚙️

1. 节点配置管理

config.py模块允许读取和修改IPFS节点配置：

# 获取当前配置
config = client.config.get()

# 修改配置（例如设置API地址）
client.config.set("Addresses.API", "/ip4/0.0.0.0/tcp/5001")

2. 仓库维护

repo.py提供仓库状态查询和垃圾回收功能：

# 查看仓库状态
stats = client.repo.stat()

# 执行垃圾回收
client.repo.gc()  # 清理未固定的内容

五、高级功能：固定与命名系统 📌

1. 内容固定

pin.py模块用于确保重要内容不会被垃圾回收：

# 固定内容
client.pin.add(cid)

# 查看固定列表
pins = client.pin.ls()

# 取消固定
client.pin.rm(cid)

2. IPNS名称发布

name.py模块实现IPNS（IPFS命名系统）功能，将易变的内容CID映射到稳定的节点ID：

# 发布IPNS名称
client.name.publish(cid)  # 返回类似 "/ipns/QmNodeID..." 的名称

# 解析IPNS名称
resolved_cid = client.name.resolve("/ipns/QmNodeID...")

六、实用工具与错误处理 🛠️

常用工具方法

• 节点信息：id()返回当前节点的ID和地址信息

  node_info = client.id()
  

• 版本查询：version()获取IPFS节点和客户端版本

  versions = client.version()
  

异常处理

所有API调用可能抛出的异常定义在exceptions.py中，建议使用try-except块捕获：

from ipfshttpclient.exceptions import IPFSError

try:
    client.add("largefile.dat")
except IPFSError as e:
    print(f"IPFS操作失败: {e}")

七、官方文档与资源

• 完整API参考：项目文档docs/http_client_ref.md
• 单元测试示例：test/unit/目录包含各模块的测试用例
• 功能测试：test/functional/目录提供端到端使用示例

通过本指南，您已掌握py-ipfs-http-client的核心API及使用方法。无论是构建分布式应用、内容存储系统还是区块链项目，这个强大的客户端库都能为您提供便捷的IPFS网络接入能力。开始探索去中心化数据世界的无限可能吧！

【免费下载链接】py-ipfs-http-client A python client library for the IPFS API 项目地址: https://gitcode.com/gh_mirrors/py/py-ipfs-http-client