Skip to main content

Python SDK

在一些权限受限的环境中（如非特权容器和大部分 Serverless 环境），由于无法使用 FUSE 模块，挂载文件系统会受到限制。为了解决这些限制并更好地支持 AI 场景，JuiceFS 云服务和企业版在 5.1 版本中推出了 Python SDK，允许应用程序在进程内直接访问 JuiceFS。

注意

JuiceFS Python SDK 处于 Beta 发布阶段，使用过程中遇到问题请给我们反馈。

安装​

确保安装了 Python 3.8 及以上版本，然后通过 pip 安装 JuiceFS Python SDK：

pip install https://static.juicefs.com/misc/juicefs-5.1.5.202411290726-py3-none-any.whl

初始化 JuiceFS 客户端​

在使用之前，需要先初始化一个 Client 对象。

如果此前使用云服务客户端挂载过文件系统，也就是说在当前用户的 ~/.juicefs 目录下已经存在文件系统的 *.conf 配置文件，那么在初始化 Client 对象时只需指定文件系统名称：

import juicefs

# 使用名为 myjfs 的文件系统初始化客户端对象
jfs = juicefs.Client("myjfs")

如果没有，则需要提供 JuiceFS 的配置信息，包括文件系统名称、token、对象存储的访问密钥等：

import os
import juicefs

# 从环境变量中获取配置信息，也可以直接填写。
volume = os.getenv("VOLUME_NAME")
jfs_token = os.getenv("TOKEN")
ak = os.getenv("ACCESS_KEY")
sk = os.getenv("SECRET_KEY")

# 初始化 JuiceFS 客户端
jfs = juicefs.Client(volume,           # 文件系统名称
                     token=jfs_token,  # JuiceFS 控制台获取的文件系统 token
                     access_key=ak,    # 对象存储的 Access Key
                     secret_key=sk)    # 对象存储的 Secret Key

基本文件操作​

为了便于用户快速上手使用，JuiceFS Python SDK 在设计上参考了 Python 的内置函数和 os 包中的部分函数。以下是一些基本的文件操作示例。

列出目录中的文件​

使用 listdir() 方法列出指定目录中的文件：

jfs.listdir('/')

创建目录​

你可以使用 makedirs() 方法创建目录：

jfs.makedirs("/files")

检查文件或目录是否存在​

使用 exists() 方法检查文件或目录是否存在：

if jfs.exists("/files/hello.txt"):
    print("File exists")
else:
    print("File does not exist")

写入文件​

使用 open() 方法打开文件并使用 write() 方法写入内容：

with jfs.open("/files/hello.txt", "w") as f:
    f.write("hello")

追加内容​

使用 open() 方法以追加模式打开文件并写入内容：

with jfs.open("/files/hello.txt", "a+") as f:
    f.write(" world")

读取文件​

使用 open 方法打开文件并使用 read() 方法读取内容：

with jfs.open("/files/hello.txt") as f:
    data = f.read()
    print(data)

删除文件​

使用 remove() 方法删除文件：

jfs.remove("/files/hello.txt")

高级操作​

修改文件权限​

使用 chmod() 方法修改文件权限，权限参数为八进制数：

jfs.chmod("/files/hello.txt", 0o777)

使用 symlink() 方法创建符号链接：

jfs.symlink("/files/hello.txt", "/files/link")

使用 readlink() 方法读取符号链接的目标文件：

link_target = jfs.readlink("/files/link")
print(link_target)

使用 unlink() 方法删除符号链接：

jfs.unlink("/files/link")

设置和获取扩展属性​

使用 setxattr() 和 getxattr() 方法设置和获取文件的扩展属性：

jfs.setxattr("/files/hello.txt", "user.key", b"value\0")
xx = jfs.getxattr("/files/hello.txt", "user.key")
print(xx)

API 索引​

Client 类​

Client 类是 JuiceFS 云服务的客户端类，用于与 JuiceFS 进行交互。

初始化方法​

提示

关于初始化方法的参数说明，请参考 juicefs auth 及 juicefs mount 命令的选项说明。

需要特别注意某些选项的默认值和 FUSE 客户端不同，例如 cache_dir 的默认值是 memory、cache_size 的默认值是 100M。

class Client(name, *, token="", conf_dir="", console_url="https://juicefs.com",
             bucket=None, access_key=None, secret_key=None, session_token=None, shards=0, storage_class=None,
             bucket2=None, access_key2=None, secret_key2=None, session_token2=None, shards2=0, storage_class2=None,
             rsa_key_path="", rsa_passphrase=None, internal=False, external=False,
             max_uploads=20, max_downloads=200, prefetch=1, put_timeout="60s", get_timeout="5s",
             upload_limit='', download_limit='', writeback=False,
             metacache=True, max_cached_inodes=500000, opencache=False,
             attr_cache="1s", entry_cache="0s", dir_entry_cache="1s",
             buffer_size="300M", cache_size="100M", free_space_ratio=0.1, cache_dir="memory",
             cache_evict="2-random", cache_expire="0s", verify_cache_checksum="full",
             cache_group="", group_ip="", group_weight=100, group_weight_unit="0M", group_port=0, no_sharing=False,
             cache_partial_only=False, cache_large_write=False, fill_group_cache=False, cache_priority=0,
             mount_point="/jfs", access_log="", debug=False, flip=False,
             **kwargs)

open()​

Client.open(path, mode='r', buffering=-1, encoding=None, errors=None, newline=None)

参数说明：

  • path (str)：文件路径
  • mode (str)：文件打开模式
  • buffering (int)：缓冲区大小
  • encoding (str)：文件编码
  • errors (str)：错误处理策略
  • newline (str)：换行符处理策略

返回值：

  • 返回一个 File 对象

makedirs()​

Client.makedirs(path, mode=0o777, exist_ok=False)

参数说明：

  • path (str)：目录路径
  • mode (int)：目录权限
  • exist_ok (bool)：如果目录已存在，是否忽略错误

返回值：

  • 无返回值

exists()​

Client.exists(path)

参数说明：

  • path (str)：文件或目录路径

返回值：

  • 返回一个布尔值，表示文件或目录是否存在

remove()​

Client.remove(path)

参数说明：

  • path (str)：文件路径

返回值：

  • 无返回值

chmod()​

Client.chmod(path, mode)

参数说明：

  • path (str)：文件路径
  • mode (int)：文件权限

返回值：

  • 无返回值
Client.symlink(src, dst)

参数说明：

  • src (str)：源文件路径
  • dst (str)：目标符号链接路径

返回值：

  • 无返回值
Client.readlink(path)

参数说明：

  • path (str)：符号链接路径

返回值：

  • 返回符号链接的目标路径
Client.unlink(path)

参数说明：

  • path (str)：符号链接路径

返回值：

  • 无返回值

setxattr()​

Client.setxattr(path, name, value, flags=0)

参数说明：

  • path (str)：文件路径
  • name (str)：扩展属性名称
  • value (bytes)：扩展属性值
  • flags (int)：扩展属性标志

返回值：

  • 无返回值

getxattr()​

Client.getxattr(path, name)

参数说明：

  • path (str)：文件路径
  • name (str)：扩展属性名称

返回值：

  • 返回扩展属性值

File 类​

File 类是 JuiceFS 文件操作的类，用于读写文件。

初始化方法​

通常使用 Client.open() 方法来初始化 File 对象，不会直接创建。

fileno()​

File.fileno()

返回值：

  • 返回文件描述符

isatty()​

File.isatty()

返回值：

  • 返回一个布尔值，表示文件是否为 TTY

read()​

File.read(size=-1)

参数说明：

  • size (int)：读取的字节数，默认为 -1，表示读取整个文件

返回值：

  • 返回读取的字节数据

write()​

File.write(data)

参数说明：

  • data (bytes)：要写入的数据

返回值：

  • 返回写入的字节数

close()​

File.close()

返回值：

  • 无返回值

flush()​

File.flush()

返回值：

  • 无返回值

readlines()​

File.readlines(hint=-1)

参数说明：

  • hint (int)：读取的行数，默认为 -1，表示读取所有行

返回值：

  • 返回一个包含文件行的列表

writelines()​

File.writelines(lines)

参数说明：

  • lines (list)：要写入的行列表

返回值：

  • 无返回值

seek()​

File.seek(offset, whence=0)

参数说明：

  • offset (int)：偏移量
  • whence (int)：偏移基准，0 表示从文件开头，1 表示从当前位置，2 表示从文件末尾

返回值：

  • 返回新的文件指针位置

tell()​

File.tell()

返回值：

  • 返回当前文件指针位置

truncate()​

File.truncate(size=None)

参数说明：

  • size (int)：截断后的文件大小，默认为当前文件指针位置

返回值：

  • 无返回值

readable()​

File.readable()

返回值：

  • 返回一个布尔值，表示文件是否可读

writable()​

File.writable()

返回值：

  • 返回一个布尔值，表示文件是否可写

seekable()​

File.seekable()

返回值：

  • 返回一个布尔值，表示文件是否可寻址
最后于 更新
Follow us on X
Let's chat on Slack