本文主要介绍TosFileSystem 和 TosFile 两个核心类的常用方法及其参数简介。

tosfsspec.TosFileSystem

TosFileSystem 是与 TOS 交互的主要入口，提供了文件系统的所有顶层操作。

构造函数

常用方法

构造参数表

参数名	类型	默认值	说明
region	str	必填	目标 Bucket 所在地域，例如 'cn-beijing'。
endpoint	str	''	TOS 访问域名。为空字符串时，根据 region 使用默认 Endpoint；如果需要内网访问或自定义域名，可以在此处显式指定。
key	str	''	访问 TOS 的 Access Key ID。建议显式配置。
secret	str	''	访问 TOS 的 Secret Access Key。
part_size	int	8 * 1024 * 1024	分片上传和分片复制时的基础分片大小（字节）。说明 part_size必须大于等于 4 * 1024 * 1024，否则会抛出 ValueError。
max_retry_count	int	3	请求失败时的最大重试次数。
shared_prefetch_tasks	int	32	读取时的预拉取任务并发数。
shared_upload_part_tasks	int	32	分片上传时的并发任务数。
shared_upload_part_copy_tasks	int	32	分片复制时的并发任务数。
enable_crc	bool	True	是否启用 CRC64 校验。启用后会在上传和下载完成后校验数据完整性。

常用方法

下面列出了 TosFileSystem 的常用方法、关键参数以及对应的简单示例。示例均默认已完成实例初始化:

open(self, path, mode='rb', block_size=None, autocommit=True, **kwargs)

用途：打开 TOS 上的对象，返回 TosFile 文件对象。

关键参数：

path: 可以是 'tos://bucket/key' 或 'bucket/key' 形式，推荐使用带协议的形式。

mode: 只支持二进制模式 'rb'、'wb'、'ab'。

block_size: 读写时使用的块大小（字节）。在写入模式下必须大于等于 4MB；未显式设置时会回落到 part_size。

其他常用关键字参数：写入模式下可以通过 ContentType 显式指定对象的 Content-Type。

代码示例：

ls(path, detail=True, sort_names=True)

用途：列出指定路径下的文件和目录。

关键参数：

path: '/' 或 '' 时列出所有 Bucket，'tos://bucket/prefix/' 时列出该 Bucket 下的前缀。

detail: 为 True 时返回包含元信息的字典列表，否则返回字符串路径列表。

代码示例：

info(path, **kwargs) / stat(path)

用途：获取单个文件或目录的详细元信息。

exists(path, **kwargs)

用途：判断给定路径是否存在。

checksum(path)

用途：获取当前对象版本的校验值。文件类型使用对象的 ETag，目录类型使用目录信息的哈希。

代码示例：

isdir(path) / isfile(path)

用途：判断路径是否为目录或文件。

代码示例：

glob(path, maxdepth=None, **kwargs)

用途：使用通配符模式匹配路径，返回匹配到的文件列表。

find(path, maxdepth=None, withdirs=False, detail=False, **kwargs)

用途：列出路径下所有文件（以及可选的目录），通常用于实现自定义遍历逻辑。

walk(path, maxdepth=None, detail=False, **kwargs)

用途：递归遍历目录树，返回 (root, dirs, files) 生成器。

代码示例：

put_file(lpath, rpath, callback=None, **kwargs)

用途：将本地文件上传到 TOS 指定路径。

关键参数：

lpath: 本地文件路径。

rpath: 目标 TOS 路径，通常为 'tos://bucket/key'。

callback: 可选的进度回调，实现 set_size() 与 relative_update() 接口。

其他常用关键字参数：通过 ContentType 显式指定对象的 Content-Type。未指定时会根据本地文件扩展名自动推断。

代码示例：

get_file(rpath, lpath, callback=None, **kwargs)

用途：将远程对象下载到本地文件。

关键参数：

rpath: 源 TOS 路径。

lpath: 本地保存路径；如果中间目录不存在会自动创建。

callback: 可选的进度回调。

代码示例：

cp_file(path1, path2, reserve_metadata=False, **kwargs)

用途：在 TOS 内部复制单个对象。

关键参数：

path1: 源对象路径。

path2: 目标对象路径。

reserve_metadata: 为 True 时会尽可能保留源对象的元数据。

copy(path1, path2, recursive=False, maxdepth=None, on_error=None, reserve_metadata=False, **kwargs)

用途：在 TOS 内部复制一个或多个路径，支持递归目录拷贝和通配符。

mv(path1, path2, recursive=False, maxdepth=None, reserve_metadata=False, **kwargs)

用途：在 TOS 内部移动（重命名）对象或目录。对于 HNS Bucket，目录移动通常是原子操作；对于 FNS Bucket，则可能涉及拷贝加删除。

rm(path, recursive=False, maxdepth=None)

用途：删除单个路径或一组路径。path 可以是字符串或字符串列表。

rmdir(path, **kwargs)

用途：删除一个空目录；当传入 delete_bucket=True 时可以删除整个 Bucket。

mkdir(path, create_parents=True, create_bucket=False, **kwargs)

用途：创建目录；当 create_bucket=True 且路径仅包含 Bucket 名称时，会尝试创建 Bucket。

makedirs(path, exist_ok=False)

用途：递归创建目录结构，exist_ok=True 时目录已存在不会报错。

touch(path, truncate=True, **kwargs)

用途：创建一个 0 字节对象或截断已有对象。

关键参数：

truncate: 为 False 且对象已存在时会抛出异常。

content_type: 可选，显式指定 Content-Type。未指定时会基于 Key 后缀自动推断。

代码示例：

close()

用途：关闭底层客户端连接，释放资源。一般在进程退出时自动调用，如需提前释放可显式调用。

代码示例：

tosfsspec.TosFile

TosFile 是 fs.open() 返回的文件类对象，提供了标准的 I/O 方法。

构造函数

常用方法

方法/属性	描述
read(size=-1)	从当前位置读取指定字节数的数据。size=-1 表示读取到文件末尾。
readinto(buf)	将数据直接读取到可写的缓冲区对象 buf 中，返回实际读取的字节数，避免额外的内存拷贝。
readuntil(char=b'\n', blocks=None)	持续读取数据直到遇到指定的分隔符 char（包含该分隔符），或文件结束。
write(data)	将字节数据 data 写入文件缓冲区。
seek(loc, whence=0)	移动文件指针到指定位置。whence 可为 0 (开头)、1 (当前位置)、2 (文件末尾)。
tell()	返回当前文件指针的位置。
flush(force=False)	将缓冲区中累积的数据刷新到底层写入流。通常由 commit() 或关闭文件时自动调用。
commit()	提交当前缓冲区中的所有数据。对于启用了自动提交的写入模式，一般不需要显式调用。
discard()	放弃当前写入会话，终止底层分片上传并丢弃未提交的数据。
close()	关闭文件，并确保所有数据都已写入。在 with 语句块退出时会自动调用。
readable() / writable() / seekable()	返回文件是否支持读、写、随机访问的布尔值。
closed	文件是否已关闭。
bucket	当前文件所属的 Bucket 名称。
key	当前文件在 Bucket 中的对象 Key。

代码示例

对象存储